npm install 에러 해결 — 자주 나는 원인들 (ERESOLVE, EACCES, network 등)

증상: npm install이 실패할 때

npm install 도중 빨간 에러가 쏟아지면 보통 다음 중 하나입니다.

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

npm ERR! code EACCES
npm ERR! Error: EACCES: permission denied

npm ERR! code ENOTFOUND  (네트워크)

핵심은 npm ERR! code 뒤의 코드를 읽는 것입니다. 이 코드가 원인을 거의 다 알려줍니다.

왜 npm install 에러가 나는가

주요 원인

• ERESOLVE — 패키지들이 요구하는 버전이 서로 충돌(peer dependency).
• EACCES / permission denied — 전역 설치 권한 부족, 또는 sudo로 만든 폴더 소유권 문제.
• 네트워크(ETIMEDOUT, ENOTFOUND) — 사내 프록시·방화벽·레지스트리 접속 실패.
• 캐시/lock 손상 — node_modules와 package-lock.json 불일치.
• node 버전 불일치 — 패키지가 요구하는 엔진과 다름.

케이스별 해결

1) ERESOLVE (의존성 충돌)

먼저 메시지에 적힌 충돌 패키지를 확인하세요. 급할 땐 다음으로 우회합니다.

npm install --legacy-peer-deps

--legacy-peer-deps는 peer dependency 검사를 느슨하게 합니다. 근본 해결은 충돌하는 패키지의 버전을 호환되게 맞추는 것입니다. --force는 더 위험하니 최후수단으로만.

2) EACCES (권한 문제)

sudo로 설치하지 마세요. 권한 꼬임의 원흉입니다. nvm으로 node를 사용자 영역에 설치하는 것이 정석입니다.

# macOS/Linux: nvm 설치 후
nvm install --lts
nvm use --lts

이미 권한이 꼬였다면 캐시 소유권을 복구합니다.

sudo chown -R $(whoami) ~/.npm

3) 캐시·lock 손상: 클린 재설치

가장 효과 좋은 만능 처방입니다.

rm -rf node_modules package-lock.json
npm cache clean --force
npm install

Windows PowerShell이라면:

Remove-Item -Recurse -Force node_modules, package-lock.json
npm cache clean --force
npm install

4) 네트워크 / 프록시

npm config get registry        # 레지스트리 확인
npm config set registry https://registry.npmjs.org/
# 사내망이면 프록시 설정
npm config set proxy http://proxy.회사:포트

5) node 버전 불일치 (EBADENGINE)

패키지가 요구하는 node 버전과 내 버전이 다르면 경고나 설치 실패가 납니다. 에러 메시지에 required: { node: '>=18' } 같은 정보가 함께 나오니 그 버전으로 맞춥니다.

node -v               # 현재 버전
nvm install 20        # 요구 버전 설치
nvm use 20            # 그 버전으로 전환

6) Windows 빌드 도구 / node-gyp 에러

네이티브 모듈(bcrypt, sharp 등)을 깔 때 gyp ERR!나 컴파일 에러가 나면, 빌드 도구가 없어서입니다. 가능하면 사전 빌드(prebuilt) 버전을 제공하는 패키지를 쓰고, 꼭 필요하면 다음으로 도구를 설치합니다.

# Windows (관리자 PowerShell)
npm install --global windows-build-tools
# macOS
xcode-select --install

에러 코드별 비교

예방

• 전역 설치보다 프로젝트 로컬 설치 + npx 사용을 권장.
• 팀은 node 버전을 .nvmrc로 고정.
• node를 sudo로 절대 깔지 마세요. nvm/volta 같은 버전 매니저 사용.
• package-lock.json은 커밋해서 모두 같은 버전을 쓰게.

자주 묻는 질문

Q1. --force랑 --legacy-peer-deps 중 뭘 써야 하나요?

먼저 --legacy-peer-deps를 쓰세요. peer 검사만 완화합니다. --force는 충돌을 무시하고 강제 설치해 런타임 버그를 부를 수 있어 최후수단입니다.

Q2. node_modules를 지워도 되나요?

네. node_modules는 언제든 npm install로 복원되는 임시 폴더입니다. lock 파일과 함께 지우고 재설치하면 깨진 상태가 깔끔하게 초기화됩니다.

Q3. EACCES인데 sudo로 깔면 안 되나요?

당장은 되지만, root 소유 파일이 생겨 다음 설치에서 또 권한 에러가 납니다. nvm으로 node를 사용자 폴더에 설치하는 것이 근본 해결입니다.