Node.js npm install 오류 (ERR!) 해결 방법 총정리

📌 문제 상황

Node.js 프로젝트에서 패키지를 설치하려고 아래 명령어를 실행했는데 오류가 발생하는 경우가 있다.

npm install

대표적으로 이런 에러가 자주 나온다:

npm ERR! code EACCES
npm ERR! syscall access

또는

npm ERR! code ENOENT
npm ERR! enoent ENOENT: no such file or directory

또는

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree

👉 초보 개발자라면 거의 반드시 한 번은 겪는 문제다.

---

📌 원인 정리

npm install 오류는 원인이 하나가 아니라 여러 가지다.

주요 원인은 다음과 같다:

1. 권한(permission) 문제
2. node_modules 손상
3. package.json 문제
4. 캐시(cache) 오류
5. Node.js 버전 충돌

---

✅ 해결 방법 1: node_modules 삭제 후 재설치

가장 먼저 해봐야 하는 기본 해결 방법이다.

✔ 실행 방법

rm -rf node_modules

rm package-lock.json

npm install

👉 Windows에서는 폴더 직접 삭제해도 된다.

---

✅ 해결 방법 2: npm 캐시 삭제

캐시 문제로 설치가 꼬이는 경우가 많다.

npm cache clean --force

그 다음 다시 설치:

npm install

---

✅ 해결 방법 3: 권한 오류(EACCES) 해결

Mac / Linux에서 자주 발생하는 오류다.

✔ 해결 방법

sudo npm install

또는 npm 기본 경로 변경:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

👉 권한 문제는 환경에 따라 다르게 발생한다.

---

✅ 해결 방법 4: Node.js 버전 확인

버전이 맞지 않으면 dependency 충돌이 발생한다.

✔ 확인 방법

node -v

npm -v

👉 프로젝트 요구 버전과 맞는지 확인

---

✔ 해결 방법 (nvm 사용 추천)

Node 버전을 쉽게 관리하려면 nvm 사용

nvm install 18
nvm use 18

---

✅ 해결 방법 5: dependency 충돌 (ERESOLVE) 해결

최신 npm에서는 의존성 충돌이 자주 발생한다.

✔ 해결 방법

npm install --legacy-peer-deps

또는

npm install --force

👉 단, force 옵션은 주의해서 사용

---

🔥 추가 팁

• package.json 직접 수정 시 오류 발생 가능
• lock 파일(package-lock.json) 중요
• 프로젝트마다 Node 버전 다를 수 있음

---

📌 마무리

npm install 오류는 대부분
👉 캐시 문제 / 권한 문제 / 버전 충돌이다.

위 방법을 순서대로 적용하면 대부분 해결된다.