npm install 에러 완전 가이드: 모든 에러와 해결법

npm install을 실행하고 빨간 에러 메시지에 막히는 것은 모든 JavaScript 개발자의 통과 의례입니다. macOS의 권한 오류, monorepo의 의존성 충돌, CI의 손상된 캐시 등 원인을 알면 해결은 보통 간단합니다. 이 가이드는 모든 일반적인 npm install 오류를 다루고, 원인을 설명하고, 정확한 수정 명령을 제공합니다.

오류 사전: 빠른 참조 테이블

EACCES: 권한 오류 수정

macOS와 Linux에서 가장 흔한 오류입니다. npm이 /usr/local/lib/node_modules 같은 시스템 디렉터리에 글로벌 패키지를 설치하려 할 때 발생합니다.

macOS / Linux에서 수정 (권장: nvm 사용)

가장 좋은 영구적 해결책은 Node 버전 관리자를 사용하여 npm이 홈 디렉터리에 설치하도록 하는 것입니다:

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Restart terminal, then install Node
nvm install --lts
nvm use --lts

# Verify — npm now installs to ~/.nvm/
which npm
# /home/youruser/.nvm/versions/node/v20.x.x/bin/npm

대안: npm 기본 디렉터리를 수동으로 변경:

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

# Add to ~/.bashrc or ~/.zshrc:
export PATH=~/.npm-global/bin:$PATH

# Reload shell
source ~/.bashrc

최후의 수단 (대부분의 사용자에게 비권장):

# NOT recommended — changes system directory ownership
sudo chown -R $(whoami) /usr/local/lib/node_modules
sudo chown -R $(whoami) /usr/local/bin
sudo chown -R $(whoami) /usr/local/share

Windows에서 수정

Windows에서 관리자 권한으로 터미널을 실행하거나 nvm-windows를 사용:

# Install nvm-windows from:
# https://github.com/coreybutler/nvm-windows/releases

# Then in an elevated (Admin) PowerShell:
nvm install lts
nvm use lts

# Or fix npm prefix for current user:
npm config set prefix %APPDATA%\npm

ERESOLVE: 의존성 충돌 수정

npm 7부터 peer 의존성 충돌은 기본적으로 설치를 실패시킵니다. 충돌하는 패키지를 보여주는 트리 다이어그램이 표시됩니다.

일반적인 오류 출력:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR!
npm ERR! While resolving: @some-org/some-package@2.1.0
npm ERR! Found: react@18.2.0
npm ERR! node_modules/react
npm ERR!   react@"^18.2.0" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^16.8.0 || ^17.0.0" from some-library@3.5.0
npm ERR! node_modules/some-library
npm ERR!   some-library@"^3.5.0" from the root project

--legacy-peer-deps vs --force

--legacy-peer-deps는 npm에게 peer 의존성 충돌을 완전히 무시하라고 지시합니다 (npm 6과 동일한 동작). --force는 충돌에 관계없이 설치를 강제합니다. 사용 시기:

# Option 1: Ignore peer deps (safest workaround)
npm install --legacy-peer-deps

# Option 2: Force install (overrides everything)
npm install --force

권장 접근법 — 충돌하는 의존성 고정:

// In package.json — add "overrides" to pin the conflicting dep
{
  "overrides": {
    "some-library": {
      "react": "^18.2.0"
    }
  }
}

// Then run:
// npm install

node_modules 손상: 언제 그리고 어떻게 삭제하고 재설치하는가

node_modules는 때때로 비정상 상태가 됩니다. package.json에 있는 패키지의 "Cannot find module" 오류나 브랜치 전환 후 이상한 빌드 실패가 증상입니다.

node_modules를 삭제해야 할 때

• 다른 의존성 트리를 가진 브랜치로 전환한 후.
• package-lock.json의 병합 충돌을 해결한 후.
• 명확히 설치된 패키지에서 "Module not found"가 나타날 때.
• Node.js를 새 메이저 버전으로 업그레이드한 후.

클린 재설치 방법

크로스 플랫폼 원라이너 (bash):

rm -rf node_modules package-lock.json
npm install

Windows (PowerShell):

Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
npm install

npx 사용:

npx rimraf node_modules
npm install

문제가 지속되면 npm 캐시도 정리:

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

package-lock.json 충돌: 병합 전략

여러 개발자가 의존성을 변경하면 package-lock.json 병합 충돌은 거의 확실히 발생합니다. 수동으로 해결하려 하지 마세요 — 이 파일은 기계 생성입니다.

권장 병합 전략

충돌의 어느 쪽이든 수락 (어느 쪽이든 상관없음):

# Accept "theirs" (the incoming branch's version)
git checkout --theirs package-lock.json
git add package-lock.json

# OR accept "ours" (your branch's version)
git checkout --ours package-lock.json
git add package-lock.json

잠금 파일 재생성:

npm install

결과 커밋:

git add package-lock.json
git commit -m "chore: regenerate package-lock.json after merge"

.gitattributes로 충돌 방지

.gitattributes에 다음을 추가하여 잠금 파일 충돌 자동 해결:

# .gitattributes
package-lock.json merge=ours

Node.js 버전 비호환성

많은 패키지는 특정 Node.js 버전을 필요로 합니다. Node 버전이 너무 오래되거나 새로우면 컴파일 오류나 지원되지 않는 엔진 경고로 npm install이 실패할 수 있습니다.

필요한 버전 확인

package.json의 engines 필드를 확인:

// package.json
{
  "engines": {
    "node": ">=18.0.0",
    "npm": ">=9.0.0"
  }
}

// Check your current version:
// node -v
// npm -v

nvm 또는 fnm으로 버전 전환

nvm (Node Version Manager):

# List available versions
nvm ls-remote

# Install a specific version
nvm install 20

# Switch to a version
nvm use 20

# Set a default
nvm alias default 20

fnm (Fast Node Manager) — 더 빠른 대안:

# Install fnm (Rust-based, faster than nvm)
curl -fsSL https://fnm.vercel.app/install | bash

# Install and use a version
fnm install 20
fnm use 20
fnm default 20

프로젝트 루트에 .nvmrc 파일을 생성하여 팀 전체가 같은 버전을 사용:

# Create .nvmrc file
echo "20" > .nvmrc

# Team members just run:
nvm use
# or
fnm use

CI/CD 문제: Docker 빌드와 GitHub Actions

npm install은 CI 환경에서 다르게 동작합니다. 캐싱, 권한, 네트워크 설정 모두 특별한 주의가 필요합니다.

Docker 빌드

Dockerfile의 일반적인 실수:

# BAD Dockerfile — no layer caching, uses npm install
FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm install
CMD ["node", "index.js"]

# GOOD Dockerfile — proper layer caching, uses npm ci
FROM node:20-alpine
WORKDIR /app

# Copy package files first (layer caching!)
COPY package.json package-lock.json ./

# Use npm ci for deterministic installs
RUN npm ci --ignore-scripts

# Then copy the rest of the source
COPY . .

# Run any build steps after copy
RUN npm run build

CMD ["node", "index.js"]

핵심: 레이어 캐싱을 위해 package 파일을 먼저 복사, CI에서는 npm install 대신 npm ci 사용 (더 빠르고 결정적), postinstall 스크립트가 불필요하면 --ignore-scripts 사용.

GitHub Actions 캐싱

적절한 캐싱으로 설치 시간을 70% 이상 단축할 수 있습니다:

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'  # Caches ~/.npm automatically

      - run: npm ci       # Deterministic install
      - run: npm test
      - run: npm run build

결정 플로우차트: npm install 실패 — 이 순서를 따르세요

이 플로우차트로 npm install 실패를 진단하세요:

자주 묻는 질문