Uncaught TypeError: $ is not a function 오류 해결 방법(가장 흔한 원인 5가지)

웹 개발을 하다 보면 jQuery를 사용하는 프로젝트에서
가장 자주 발생하는 오류가 바로 다음 오류 메시지입니다.

 

Uncaught TypeError: $ is not a function

 

이 오류는 브라우저가 $() 문법을 이해하지 못해 발생합니다.
대부분 jQuery가 정상적으로 로딩되지 않았거나,
다른 라이브러리와 충돌했을 때 발생합니다.

아래에서는 이 오류가 발생하는 대표적인 원인들과
실무에서 가장 확실한 해결 방법을 정리해드리겠습니다.

 

 

1. jQuery 파일이 로드되지 않았을 때

가장 흔한 원인입니다.

 

<script src="/js/jquery.min.js"></script> <script> console.log($); // 오류 발생 가능 </script>

위 상황에서 $가 undefined라면
jQuery 자체가 로딩되지 않은 것입니다.

🔧 해결 방법

• 경로가 맞는지 확인하시고
• CDN을 사용하면 문제를 크게 줄일 수 있습니다.

 

<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>

---

2. jQuery보다 먼저 스크립트를 실행한 경우

jQuery가 로딩되기 전에 $를 호출해도 동일한 오류가 발생합니다.

 

<script> 
	$('#test').hide(); // jQuery보다 먼저 실행되면 오류 
</script> 
<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>

🔧 해결 방법

항상 jQuery 뒤에 코드를 작성하셔야 합니다.

 

<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script> <script> $('#test').hide(); </script>

또는 $(document).ready()로 감쌀 수도 있습니다.

 

$(document).ready(function(){
    $('#test').hide();
});

---

3. jQuery noConflict()가 적용된 경우

특정 라이브러리(Prototype.js 등)가
jQuery의 $ 심볼을 가져가면서 충돌이 발생하는 경우입니다.

 

 

*해결 방법

<script>
    $.noConflict();
    $('#test').hide();   // 오류 발생
</script>

noConflict 모드를 사용해야 한다면 $ 대신 jQuery를 사용해야 합니다.

jQuery('#test').hide();

 

또는 아래처럼 변수에 다시 넣어 사용하실 수도 있습니다.

 

var $j = jQuery.noConflict(); $j('#test').hide();

---

4. jQuery가 두 번 이상 포함된 경우 (버전 충돌)

서로 다른 jQuery 버전을 중복으로 로딩하면
$ 객체가 뒤집히면서 오류가 날 수 있습니다.

 

<script src="jquery-1.12.js"></script>
<script src="jquery-3.7.1.js"></script>

 

이런 상황에서는 $가 생각과 다르게 동작하거나
undefined로 치환되는 경우도 있습니다.

 

8 해결 방법

jQuery는 한 번만 로딩되도록 정리해 주세요.

---

5. 모듈 환경(ESM)에서 $가 선언되지 않은 경우

React, Vue, Webpack, Vite 등
모듈 환경에서는 $와 jQuery가 자동으로 글로벌 등록되지 않습니다.

 

$('#test'); // 오류

* 해결 방법

import $ from "jquery";

$('#test').hide();

 

---

 

6. Script defer 속성으로 로딩 순서가 꼬였을 때

<script defer>는 로딩 순서를 보장하지 않기 때문에
jQuery보다 먼저 실행되면 $ undefined 문제가 발생할 수 있습니다.

 

<script defer src="/js/myscript.js"></script> 
<script defer src="/js/jquery.js"></script>

* 해결 방법

jQuery에는 defer를 사용하지 않는 것이 가장 안전합니다.

 

 

※요약: 가장 빠른 해결 체크리스트

문제를 만났을 때 아래 4가지만 확인해보시면
대부분 바로 해결됩니다.

 

1.  jQuery가 제대로 로드 되었는가?

2. jQuery보다 먼저 실행되는 스크립트가 있는가?

3. noConflict 모드가 켜진 상태인가?

4. jQuery가 중복 로딩되지는 않았는가?

 

 

이 네 가지 중 하나가 원인일 가능성이 90% 이상입니다.