Vue 프로젝트에서 esbuild.exe ENOENT 오류 해결 방법

문제 상황

최근 사무실 이전으로 새로운 장비로 교체하게 되었습니다. 개발자 입장에서 장비 교체는 개발 환경 재설정이 필요해 번거로운 작업입니다. 몇 시간의 작업 끝에 개발 환경을 다시 설정했지만, 백엔드 관리 프로젝트를 시작할 때 다음과 같은 오류가 발생했습니다:

> admin-project@3.9.7 dev D:\Projects\admin-dashboard
> NODE_OPTIONS=--max-old-space-size=2048 vite

node:events:496
      throw er; // Unhandled 'error' event
      ^

Error: spawn D:\Projects\admin-dashboard\node_modules\.pnpm\esbuild@0.11.3\node_modules\esbuild\esbuild.exe ENOENT
    at ChildProcess._handle.onexit (node:internal/child_process:285:19)
    at onErrorNT (node:internal/child_process:483:16)
    at process.processTicksAndRejections (node:internal/process/task_queues:90:21)
Emitted 'error' event on ChildProcess instance at:
    at ChildProcess._handle.onexit (node:internal/child_process:291:12)
    at onErrorNT (node:internal/child_process:483:16)
    at process.processTicksAndRejections (node:internal/process/task_queues:90:21) {
  errno: -4058,
  code: 'ENOENT',
  syscall: 'spawn D:\\Projects\\admin-dashboard\\node_modules\\.pnpm\\esbuild@0.11.3\\node_modules\\esbuild\\esbuild.exe',
  path: 'D:\\Projects\\admin-dashboard\\node_modules\\.pnpm\\esbuild@0.11.3\\node_modules\\esbuild\\esbuild.exe',
  spawnargs: [ '--service=0.11.3', '--ping' ]
}

Node.js v22.17.1
 ELIFECYCLE  Command failed with exit code 1.

오류 원인

오류 메시지를 분석해보면 esbuild.exe 파일 생성 과정에서 문제가 발생한 것으로 보입니다. esbuild는 Go 언어로 작성된 도구로, 다양한 운영체제(Windows, Linux, macOS 등)에서 효율적으로 실행되기 위해 설치 시 현재 시스템 환경에 맞는 미리 컴파일된 실행 파일(예: Windows의 esbuild.exe)을 다운로드합니다. esbuild는 Vite와 같은 빌드 도구의 핵심 의존성으로, 프로젝트 시작 시 이 실행 파일을 호출하여 코드를 컴파일/패키징합니다. 이 파일이 누락되면 프로젝트 시작이 실패하게 됩니다.

해결 방안

방법 1: 파일 복사

가장 간단한 해결책은 동료에게서 esbuild.exe 파일을 복사하여 지정된 디렉터리에 붙여넣는 것입니다. 이 방법은 문제를 일시적으로 해결할 수 있지만, 근본적인 해결책은 아닙니다.

방법 2: 수동 생성 스크립트 실행

프로젝트 루트 디렉터리에서 다음 명령을 실행하여 esbuild.exe를 수동으로 생성할 수 있습니다:

node .\node_modules\esbuild\install.js

이 스크립트는 esbuild 패키지에 포함된 설치 스크립트로, 다음과 같은 작업을 수행합니다:

현재 시스템 환경을 확인하고 필요한 esbuild 미리 컴파일된 실행 파일 버전을 결정
해당 실행 파일을 자동으로 다운로드하고 node_modules/esbuild 디렉터리의 올바른 위치에 배치

이 스크립트를 수동으로 실행하면 누락된 esbuild.exe(또는 다른 시스템에 해당하는 실행 파일)의 "재설치" 또는 "초기화" 프로세스를 강제로 트리거하여 문제를 해결할 수 있습니다.

방법 3: 의존성 재설치 및 권한 설정

가장 권장되는 해결책은 다음과 같습니다:

프로젝트의 node_modules 디렉터리를 삭제합니다
관리자 권한으로 CMD를 시작합니다
pnpm install 명령을 실행합니다
경고가 표시되면 pnpm approve-builds 명령을 실행합니다
모든 빌드 스크립트 실행을 허용합니다(y 선택)

pnpm은 보안 등의 이유로 일부 의존성의 빌드 스크립트 실행을 기본적으로 차단합니다. pnpm approve-builds 명령을 사용하여 어떤 의존성이 빌드 스크립트를 실행할 수 있는지 선택적으로 허용할 수 있습니다. 관리자 권한으로 이 과정을 수행하면 파일 생성 권한 문제도 해결됩니다.

문제 해결 과정에서의 교훈

AI는 개발자에게 유용한 도구이지만, 항상 최적의 해결책을 제공하는 것은 아닙니다. 이 문제를 해결하는 과정에서 AI는 Node.js 버전이 낮을 수 있다고 제안했으며, 버전 18으로 전환하고 pnpm.lock 파일을 삭제한 후 재설치하라고 권장했습니다. 이 방법으로 esbuild 문제는 해결되었지만, pnpm.lock 파일 삭제로 인해 많은 의존성 패키지 버전이 맞지 않아 새로운 오류가 발생했습니다.

여러 사람이 협력하는 프로젝트이고 오랫동안 운영되어 온 프로젝트의 경우, 의존성을 대규모로 변경하는 것은 바람직하지 않습니다. 이런 경우에는 동료와의 소통이 중요합니다. 동료들이 이미 같은 문제를 겪고 해결책을 찾았을 수 있기 때문입니다. 하지만 동료가 제공한 해결책이 항상 최적의 방법은 아니므로, 직접 다양한 방법을 시도해보는 것도 중요합니다.

또한 프로젝트 의존성 설치 시 경고 메시지를 주의 깊게 살펴보는 습관을 들이는 것이 좋습니다. 프로젝트가 실행되지 않을 때 이 경고 메시지가 문제의 근원일 수 있습니다. 기술 개발자로서 우리는 문제를 해결해 나가는 과정에서 성장하며, 이제는 강력한 AI 도구의 도움도 받을 수 있습니다.

태그: esbuild vue Vite Node.js pnpm

9월 5일 21:35에 게시됨

괴물 클럽