라떼군 이야기
Vite 6 환경에서 발생하는 esbuild 'Expected identifier but found import' 에러 해결 방법
Problem
프론트엔드와 백엔드가 분리된 풀스택 프로젝트에서 Vite와 React로 구성된 프론트엔드 서버를 실행할 때 문제가 발생할 수 있습니다. npm run dev 명령어를 입력하면 vite.config.js 파일을 로드하는 과정에서 에러가 발생하며 서버가 켜지지 않습니다. 구체적으로는 esbuild가 import.meta.dirname, import.meta.filename, import.meta.url 구문을 파싱하지 못하고 Expected identifier but found "import"라는 구문 에러 메시지를 출력하며 빌드가 실패하는 증상이 나타납니다.
Background
이 문제를 이해하려면 Vite의 내부 동작 방식과 Node.js의 ES Module(ESM) 시스템을 알아야 합니다. Vite는 내부적으로 설정 파일(vite.config.js)이나 의존성을 빠르게 번들링하기 위해 esbuild라는 초고속 번들러를 사용합니다. 에러 메시지에 등장하는 import.meta.dirname과 import.meta.filename은 기존 CommonJS의 __dirname을 대체하기 위해 Node.js 환경의 ESM에 새롭게 도입된 속성입니다. 문제는 프로젝트의 의존성 트리에 설치된 esbuild 버전이 너무 낮아 이러한 최신 import.meta 문법을 올바르게 파싱(해석)하지 못할 때 발생합니다. 특히 최근 Vite 6.x 버전으로 업데이트되면서 내부적으로 요구하는 문법 수준과 실제 설치된 esbuild 버전 간의 불일치가 일어나는 것이 근본적인 원인입니다.
Solution
이 문제를 해결하는 방법은 크게 두 가지가 있습니다. 프로젝트의 상황에 맞게 선택하여 적용해 보세요.
해결 방법 1: esbuild 버전 수동 업데이트 (권장)
가장 근본적이고 권장되는 해결책은 에러를 발생시키는 주체인 esbuild의 버전을 최신(0.24.0 이상)으로 업데이트하는 것입니다. 이 방법을 사용하면 최신 Vite 6 버전을 그대로 유지하면서 문제를 해결할 수 있습니다.
# 1. esbuild 최신 버전을 개발 의존성(dev dependency)으로 설치합니다.
npm i -D esbuild@0.24.0
# 2. 패키지 트리를 정리하고 의존성을 다시 설치하여 꼬인 의존성을 풀어줍니다.
npm i
# 3. 개발 서버를 다시 실행합니다. 정상적으로 구동되는 것을 확인할 수 있습니다.
npm run dev
장단점: 프로젝트의 다른 핵심 의존성(Vite, React 등)의 버전을 변경하지 않고 파싱 에러만 깔끔하게 해결할 수 있어 가장 권장됩니다.
해결 방법 2: Vite 버전 다운그레이드 (임시 방편)
만약 현재 프로젝트 환경이나 다른 서드파티 플러그인들과의 호환성 문제로 인해 최신 esbuild나 Vite 6.x 버전을 당장 사용할 수 없다면, 안정적인 이전 버전인 Vite 5.x로 다운그레이드하는 방법도 있습니다.
# 1. 현재 설치된 문제가 있는 최신 vite 패키지를 제거합니다.
npm uninstall vite
# 2. 안정적인 vite 5버전 대역을 명시하여 설치합니다.
npm install vite@^5
# 3. 개발 서버를 실행합니다.
npm run dev
장단점: 당장 에러를 회피하고 프로젝트를 실행하기에는 빠르고 확실한 방법입니다. 하지만 장기적으로는 Vite 6의 새로운 기능이나 빌드 성능 향상의 이점을 누릴 수 없다는 단점이 있으므로, 추후 마이그레이션을 고려해야 합니다.
Deep Dive
이 에러를 근본적으로 예방하기 위해서는 프로젝트의 Node.js 버전과 패키지 매니저의 의존성 해결 방식을 점검해보는 것이 좋습니다. import.meta.dirname은 Node.js v20.11.0 및 v21.2.0 이상에서 공식 지원되므로, 로컬 개발 환경의 Node.js 버전을 최신 LTS 버전으로 업데이트하는 것을 권장합니다. 또한, npm의 overrides나 yarn의 resolutions 필드를 package.json에 추가하여 중첩된 의존성 내에서도 항상 특정 버전(예: 0.24.0) 이상의 esbuild가 강제로 사용되도록 설정할 수 있습니다. 프로덕션 환경으로 빌드할 때도 Vercel이나 Netlify 같은 CI/CD 파이프라인의 Node.js 버전 설정이 로컬 환경과 일치하는지 반드시 확인해야 배포 시 발생하는 예기치 못한 빌드 에러를 막을 수 있습니다.
Conclusion
Vite 프로젝트 실행 시 발생하는 Expected identifier but found "import" 에러는 내장된 esbuild가 최신 ESM 문법을 파싱하지 못해 발생하는 호환성 오류입니다. esbuild 패키지를 0.24.0 이상의 최신 버전으로 수동 업데이트하여 해결하는 것이 가장 이상적이며, 불가피한 경우 Vite 버전을 5.x로 낮추어 임시로 구동할 수 있습니다. 자신의 프로젝트 환경과 플러그인 호환성을 고려하여 가장 적절한 방법을 선택하시기 바랍니다.