Cannot use import statement outside a module 에러 해결

Cannot use import statement outside a module 에러 해결

자바스크립트에서 import를 사용했는데 갑자기 SyntaxError: Cannot use import statement outside a module이라는 오류가 나타날 때가 있습니다. 분명 다른 예제에서는 정상적으로 사용하는 문법인데 내 코드에서는 왜 안 되는지 헷갈리기 쉬운데요.

 
이 오류의 핵심은 현재 자바스크립트 파일이 ES Module로 인식되지 않고 있다는 것입니다.
 
브라우저와 Node.js에서는 해결 방법이 조금 다르기 때문에 현재 어떤 환경에서 코드를 실행하는지부터 확인해야 합니다. 원인부터 상황별 해결법까지 차근차근 알아보겠습니다.
 
 

Cannot use import statement outside a module 뜻은?

import는 다른 자바스크립트 파일에서 내보낸 함수, 변수, 클래스 등을 가져올 때 사용하는 ES Module(ESM) 문법입니다.

// math.js
export function sum(a, b) {
  return a + b;
}
// app.js
import { sum } from "./math.js";
console.log(sum(1, 2));

 

그런데 실행 환경이 app.js를 일반 스크립트 또는 다른 모듈 방식으로 처리하고 있다면 import를 만났을 때 오류가 발생할 수 있습니다.

 
쉽게 표현하면 자바스크립트가 “이 파일은 모듈이 아닌데 왜 import 문법이 들어 있지?”라고 알려주는 것입니다. 따라서 import를 삭제하기 전에 파일이 어떤 방식으로 실행되고 있는지 확인하는 것이 먼저입니다.
 
 

브라우저 import 오류, type="module" 확인

HTML에서 자바스크립트 파일을 불러오면서 ES Module을 사용하려면 script 태그에 type="module"을 지정해야 합니다.

<!-- 잘못된 예 -->
<script src="app.js"></script>
<!-- ES Module로 실행 -->
<script type="module" src="app.js"></script>

type="module"을 지정하면 브라우저는 해당 스크립트를 일반 자바스크립트 파일이 아닌 ES Module로 처리합니다. 그러면 파일 내부에서 import와 export를 사용할 수 있습니다.

 

또한 브라우저의 ES Module은 보통 파일을 직접 더블클릭해 file:// 방식으로 실행하기보다 로컬 개발 서버를 이용하는 편이 안전합니다. 모듈 로딩에는 브라우저의 보안 정책과 서버 응답 방식 등이 영향을 줄 수 있기 때문입니다.

 
 

Node.js에서 Cannot use import 오류 해결하기

Node.js에서 .js 파일에 ES Module 문법을 사용하려면 프로젝트의 모듈 방식을 확인해야 합니다. 대표적인 방법은 package.json에 다음 설정을 추가하는 것입니다.

{
  "type": "module"
}

이렇게 설정하면 해당 package 범위의 .js 파일을 ES Module 방식으로 처리할 수 있습니다. 이후 다음과 같이 import/export 문법을 사용할 수 있습니다.

 

// math.js
export function sum(a, b) {
  return a + b;
}
// app.js
import { sum } from "./math.js";
console.log(sum(10, 20));

또 다른 방법은 ES Module 파일에 .mjs 확장자를 사용하는 것입니다. 반대로 CommonJS를 명시적으로 사용해야 한다면 .cjs와 require() 방식도 고려할 수 있습니다.

 
 

import 오류가 발생하는 원인 6가지

1. 브라우저에서 type="module"을 빠뜨린 경우
HTML의 일반 script 태그에서 import를 사용하고 있다면 가장 먼저 확인하세요. type="module"을 추가하는 것만으로 해결되는 경우가 많습니다.

 

2. Node.js의 모듈 설정이 맞지 않는 경우
프로젝트가 CommonJS 방식으로 동작하고 있는데 ES Module의 import 문법을 사용하면 문제가 생길 수 있습니다. package.json의 type 설정과 파일 확장자를 확인하세요.

 

3. import와 require 방식을 혼동한 경우
import는 ES Module, require()는 전통적인 CommonJS에서 사용하는 대표적인 방식입니다. 프로젝트가 어떤 모듈 시스템을 사용하는지 파악한 뒤 일관되게 작성하는 것이 좋습니다.

// ES Module
import { sum } from "./math.js";
// CommonJS
const { sum } = require("./math.js");

 
4. 파일을 잘못된 방식으로 실행한 경우
프로젝트에서는 정상적으로 동작하는 파일을 테스트 목적으로 별도로 실행했을 때 모듈 설정이 적용되지 않을 수 있습니다. 어떤 명령과 환경에서 파일이 실행되는지 확인해 보세요.
 
5. 테스트 도구나 빌드 환경의 설정이 다른 경우
브라우저에서는 정상인데 테스트 환경에서만 import 오류가 발생할 수도 있습니다. 테스트 러너나 빌드 도구가 ESM을 어떤 방식으로 처리하는지 해당 설정을 확인해야 합니다.
 
6. 오래된 예제나 다른 실행 환경의 코드를 그대로 사용한 경우
인터넷에서 찾은 예제는 브라우저, Node.js, React, Vite 등 특정 환경을 전제로 작성됐을 수 있습니다. 코드만 복사하기보다 어떤 프로젝트 환경에서 사용하는 예제인지 함께 확인하는 것이 중요합니다.
 
 

파일 경로 오류와는 어떻게 다를까?

Cannot use import statement outside a module은 보통 import 대상 파일을 찾지 못해서 발생하는 오류가 아닙니다. import 문법 자체를 현재 실행 문맥에서 사용할 수 없다고 판단한 것입니다.
 

반대로 모듈 설정은 정상인데 경로가 틀렸다면 module not found처럼 다른 형태의 오류가 나타날 수 있습니다. 따라서 먼저 모듈 설정을 해결한 뒤 경로 문제를 확인하는 것이 좋습니다.

// 상대 경로 예시
import { sum } from "./math.js";

 
브라우저에서 직접 ES Module을 사용할 때는 상대 경로와 파일 확장자도 정확하게 작성하는 습관을 들이면 좋습니다.
 
 

Cannot use import 해결 순서 7단계

이 오류를 만났다면 무작정 import를 require로 변경하기보다 현재 실행 환경부터 확인하세요. 브라우저인지 Node.js인지에 따라 필요한 설정이 달라집니다.
 

순서	확인할 내용
1단계	브라우저인지 Node.js인지 실행 환경 확인
2단계	현재 파일에서 import를 사용하는 위치 확인
3단계	브라우저라면 type="module" 확인
4단계	Node.js라면 package.json의 type 설정 확인
5단계	.js, .mjs, .cjs 등 파일 확장자 확인
6단계	ESM과 CommonJS가 혼용됐는지 확인
7단계	수정 후 개발 서버나 Node.js를 다시 실행

 
 

import를 require로 바꾸면 해결될까?

검색하다 보면 import를 require()로 바꾸라는 해결법을 쉽게 볼 수 있습니다. CommonJS 프로젝트라면 적절한 방법이 될 수 있지만 모든 프로젝트에 적용되는 정답은 아닙니다.

 
React나 최신 프론트엔드 프로젝트처럼 ES Module을 기준으로 구성된 환경이라면 오히려 모듈 설정을 제대로 맞추는 것이 중요합니다.
 
import와 require 중 무엇이 더 좋은가가 아니라 현재 프로젝트가 어떤 모듈 시스템을 사용하는가를 기준으로 결정해야 합니다.
 
 

ES Module 오류 예방하는 방법

새 프로젝트를 시작할 때부터 ES Module과 CommonJS 중 어떤 방식을 사용할지 명확하게 정하면 관련 오류를 줄일 수 있습니다. 기존 프로젝트라면 package.json과 빌드 도구 설정을 먼저 확인한 뒤 다른 예제 코드를 적용하는 것이 좋습니다.

 
또한 import 오류가 발생했을 때 문법만 계속 수정하지 말고 실행 환경 → 모듈 설정 → 파일 확장자 → import 경로 순으로 확인하는 습관을 들여보세요. 문제의 범위를 훨씬 빠르게 좁힐 수 있습니다.
 
 

Cannot use import statement outside a module은 쉽게 말해 “현재 파일을 모듈로 처리하고 있지 않은데 import를 사용했다”는 의미입니다. 브라우저라면 type="module"을, Node.js라면 package.json의 "type": "module"이나 파일 확장자를 우선 확인해 보세요.

 
무조건 import를 require로 바꾸기보다는 현재 프로젝트의 모듈 방식을 파악하는 것이 핵심입니다. 이 기준만 이해해 두면 비슷한 import/export 오류를 만났을 때도 훨씬 쉽게 해결할 수 있습니다.