vue(404)... 무슨 에러지?
Vue 기반의 자바스크립트 프로젝트를 진행하던 중, 팀원이 프로젝트를 Github에서 clone 받고 .vue 파일을 열자마자
이해할 수 없는 에러를 마주했습니다.
vue(404): Write global types file failed.
Please ensure that "node_modules" exists and "vue" is a direct dependency,
or set "vueCompilerOptions.globalTypesPath" in "tsconfig.json" manually.
Write global types file failed. Please ensure that "node_modules" exists and "vue" is a direct dependency, or set "vueCompilerOptions.globalTypesPath" in "tsconfig.json" manually.vue(404)
"우리는 TypeScript도 안 쓰고, Volar 확장도 설치 안 했는데... 왜?
구글에 검색한 결과 최근 3일 전 정도 쯤 부터 이 오류를 겪은 사람들이 존재했습니다.
버전업 되면서 발생한 오류로 추측했고,
이 글은 그 오류를 계기로 직접 Vue 공식 저장소에 오픈소스 issue를 제보하고, 공식 답변에 대한 정리한 글입니다.
상황정리
- 프로젝트: Vue 3 + Vite 기반의 JavaScript-only 프로젝트
- 환경:
- TypeScript 사용 안 함
- Volar 확장 설치 안 함
- .vue 파일을 VSCode에서 열었을 뿐 - 발생 시점:
- GitHub 프로젝트를 clone한 직 후
- npm install 완료
- VSCode를 재시작하지 않은 상태
증상
.vue 파일을 열자마자 VSCode에서 다음 오류 발생:
vue(404): Write global types file failed. Please ensure that "node_modules" exists...
해결 방법
처음에는 맨 아래에 있는 방법으로 진행했지만..
다른 컴퓨터로 다른 시도를 해봤습니다.
그 어떤 설정도 건드리지 않고, 그냥 npm install 한 다음 VSCode를 재시작만 해도 에러는 사라졌습니다.
그럼 이건 버그가 아닌 건가?
버그는 아니지만, 사용자는 충분히 혼란스러울 수 있습니다.
특히 처음 Vue를 사용하는 초보 개발자나 TypeScript를 사용하지 않는 경우, 언어 도구의 내부 동작에 익숙하지 않은 개발자들에게 말입니다.
그래서 저는 이 문제를 직접 Vue Opensource에 이슈로 제보했습니다.
https://github.com/vuejs/language-tools/issues/5554
vue(404) error on opening .vue file after fresh clone – global types path or vue dependency warning · Issue #5554 · vuejs/la
Vue - Official extension or vue-tsc version Not using the Volar extension. vue-tsc is not installed (JavaScript-only project). VSCode version 1.93.1 (Universal) Vue version ^3.5.17 TypeScript versi...
github.com
간단히 요약하면, 아래와 같이 제안했습니다.
- JS-only project에서 .vue 파일 열자마자 vue(404) 오류 발생
- node_modules가 존재해도 VSCode를 재시작하지 않으면 오류 계속 발생
- 이걸 치명적인 버그로 보긴 어렵지만, DX 측면에서 개선 여지가 있다고 조심히 생각함
- Waiting for dependencies.... 같은 메세지나 restart 안내가 있다면 좋겠다고 제안
공식 답변 요약
Vue 팀에서는 다음과 같은 피드백을 주었습니다.
왜 오류가 발생했는가?
- .vue 파일을 npm install 전에 열면, 언어 서버가 제대로 초기화되지 않음.
- npm install 이후에도 VSCode를 재시작하지 않으면, 여전히 오류가 발생할 수 있음
- 이는 언어 서버가 깨진 상태로 초기화되었기 때문이며, 단순히 의존성이 생겼다고 자동으로 회복되지는 않음.
자동 감지는 왜 불가능한지?
"의존성이 아직 설치되지 않은 것인지, 아니면 애초에 npm 환경이 아닌 프로젝트인지 언어 서버는 이를 구분할 수 없다"
- 즉, 언어 서버 입장에서는 "지금 기다려야 하는 상태인지 아닌지"를 판단할 수 있는 방법이 없음
- 따라서 "자동으로 에러를 숨기거나 조건부로 지연하는 처리는 어렵다"고 답변 받았습니다.
개선 가능성?
- 사용자가 혼란을 느끼지 않도록, 오류 메세지에 vue.action.restartServer 명령어를 실행하라는 안내 문구를 추가하는 방안은 긍정적으로 고려 중이라고 합니다.
추가로 알게 된 사실
- .vue 파일의 언어 지원(SFC) 기능은 JavaScript-only 프로젝트에서도 내부적으로 TypeScript에 의존하고 있었습니다.
- 즉, tsconfig.json이 없거나 TypeScript를 직접 사용하지 않더라도 언어 서버 내부 동작에는 TypeScript가 필요하며, TypeScript관련 오류 메세지를 완전히 숨기는 건 불가능하다는 것에 대해 알았습니다.
해결 방법(이렇게 안해도 됨)
1. jsconfig.json 또는 tsconfig.json 파일 생성/수정
vue-global-types.d.ts
{
"compilerOptions": {
"target": "esnext",
"module": "esnext",
"allowJs": true,
"checkJs": false
},
"vueCompilerOptions": {
"globalTypesPath": "./vue-global-types.d.ts"
},
"exclude": ["node_modules"]
}
이 설정은 Volar에게 "전역 타입을 이 경로에 한 번만 생성해달라"고 알려주는 역할을 합니다.
2. .gitignore에 파일 무시 추가
vue-global-types.d.ts
자동 생성되는 타입 파일이므로 git에 올릴 필요가 없습니다.
3. VSCode 재시작
변경사항을 적용하려면 VSCode를 완전히 종료 후 다시 실행해주세요
정리
이 오류가 뜬다면 당황하지 마시고! 위와 같이 해결하시면 됩니다.
전역 타입 경로를 명시하고 .gitigonore에만 추가해주면 됩니다.