npm ERR! code ERESOLVE 해결법 — 에러 원문 복붙 진단 런북

npm ERR! code ERESOLVE 30초 해결 런북 — 에러 원문 복붙 진단

지금 콘솔에 빨간 글자가 떠 있고, 빌드는 멈췄고, 위에서는 배포 언제 되냐고 묻고 있나요? 개념 설명은 맨 아래로 미루겠습니다. 먼저 아래 표에서 화면에 뜬 문구를 찾으세요. 1초 매칭 → 30초 진단 → 한 줄 복붙 복구 순서로 갑니다.

1. 에러 원문 exact-match 분류표

콘솔에 실제로 찍힌 줄을 그대로 찾으세요.

가장 중요한 건 Could not resolve dependency: 줄과 Conflicting peer dependency: 줄입니다. 여기에 충돌 패키지 이름과 요구 버전이 다 적혀 있습니다.

2. 30초 결정 트리

먼저 npm 버전부터 확인합니다.

npm -v

npm 7 미만(6.x) → ERESOLVE 거의 안 뜸. (지금 이 에러면 npm 7+일 확률 99%)
npm 7 이상     → peer 의존성을 자동 설치 + 엄격 검사. 이게 원인.
                ↓
에러 메시지에서 충돌 줄 찾기:
  "Could not resolve dependency: peer X@\"범위\" from Y"
  → 충돌 패키지 = Y, 문제의 peer = X, 요구 버전 = 범위
                ↓
        ┌───────────────┴───────────────┐
   ① 데모/급한 빌드             ② 프로덕션/장기 유지
   "일단 돌아가면 됨"            "다음 사람도 똑같이 깔려야 함"
        ↓                              ↓
   3번: legacy-peer-deps          4번: overrides 버전 고정

한 줄 요약: 급하면 우회, 제대로면 고정. 우회는 절대 근본 해결이 아닙니다.

3. 일단 돌리기 — legacy-peer-deps vs force 비교표

당장 설치만 통과시켜야 할 때 쓰는 두 플래그입니다. 차이를 모르고 --force를 쓰면 다음 주에 더 큰 사고가 납니다.

# 단일 peer 충돌, 일단 빌드만 돌리고 싶을 때
npm install --legacy-peer-deps

# 최후의 수단 (무엇이 깔릴지 보장 안 됨)
npm install --force

매번 플래그 치기 싫으면 프로젝트에 박아둘 수도 있습니다.

# .npmrc
legacy-peer-deps=true

⚠️ 둘 다 근본 해결이 아닙니다. peer 충돌은 그대로 남아 있고, 동료 머신·CI에서 다른 버전이 깔릴 수 있습니다. 프로덕션이면 반드시 4번으로 가서 overrides로 버전을 고정하세요.

4. 제대로 고치기 — overrides 버전 고정 런북

4-1. 누가 충돌 peer를 요구하는지 추적

# 예: react 버전 충돌이면
npm ls react

[email protected]
├── [email protected]
└─┬ [email protected]
  └── react@"^17.0.0"   ← 얘가 범인

이렇게 어떤 패키지가 옛 버전을 요구하는지 트리로 바로 보입니다.

4-2. package.json overrides로 강제 고정 (npm 8.3+)

transitive 의존성까지 특정 버전으로 못 박는 방법입니다.

{
  "overrides": {
    "react": "18.3.1",
    // 특정 패키지 아래의 react만 바꾸고 싶다면 중첩
    "some-old-lib": {
      "react": "18.3.1"
    }
  }
}

yarn은 같은 일을 resolutions로 합니다.

// yarn (package.json)
{
  "resolutions": {
    "react": "18.3.1"
  }
}

적용 후에는 lockfile과 node_modules를 깨끗이 지우고 다시 깔아야 반영됩니다.

rm -rf node_modules package-lock.json
npm install

4-3. 그래도 안 되면 캐시까지 정리

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

실무 한마디: React 18→19 마이그레이션 때 이 패턴을 정말 자주 만납니다. 오래된 UI 라이브러리가 peer react@"^17"을 고집하면, 라이브러리 업그레이드 PR을 올리되 머지 전까지는 overrides로 react를 고정해 팀 전체가 동일 버전으로 깔리게 했습니다. --legacy-peer-deps만 박아두고 넘어간 프로젝트는 몇 주 뒤 CI에서 미묘하게 다른 버전이 깔려 "내 로컬에선 됐는데"를 두 번 겪었습니다.

5. yarn / pnpm은 명령이 다릅니다

같은 peer 충돌이라도 패키지 매니저별로 손이 다릅니다.

pnpm 예시:

// package.json
{
  "pnpm": {
    "overrides": {
      "react": "18.3.1"
    }
  }
}

pnpm은 strict peer 정책이 기본이라 npm보다 충돌이 더 잘 드러납니다. 급할 땐 pnpm install --no-strict-peer-dependencies로 우회하되, 역시 임시 조치입니다.

6. 재발 방지 체크리스트

다시는 이 빨간 글자를 안 보려면 아래를 박아두세요.

1) 버전 고정 (package.json)

{
  "engines": {
    "node": ">=20.0.0",
    "npm": ">=10.0.0"
  }
}

2) Node 버전 통일 (.nvmrc)

20.11.0

3) CI에서는 install 말고 ci

# install: lockfile을 갱신할 수 있음(재현성 깨짐)
# ci: lockfile 그대로 정확히 재현, 불일치 시 즉시 실패
npm ci

npm ci는 package-lock.json을 100% 그대로 재현하므로 "로컬은 되는데 CI는 안 됨"을 막아줍니다.

복붙 명령어 한눈 요약

npm -v                                  # 1) 버전 확인 (7+ 면 ERESOLVE 정상)
npm ls <패키지명>                        # 2) 충돌 범인 추적
npm install --legacy-peer-deps          # 3) 급하면 임시 우회
# package.json에 overrides 추가 후 ↓     # 4) 근본 해결
rm -rf node_modules package-lock.json
npm install
npm cache clean --force                 # 5) 그래도 안 되면 캐시까지

참고: 공식 문서

이 글에서 다루는 동작·설정·에러의 1차 출처는 다음 공식 문서입니다. 버전별 옵션과 정확한 동작은 여기서 확인하세요.

• Node.js 공식 문서

자주 묻는 질문 (FAQ)

Q. --legacy-peer-deps랑 --force 중 뭘 써야 하나요? A. 단일 peer 충돌을 잠깐 우회만 할 거면 --legacy-peer-deps. --force는 모든 충돌을 강제로 덮어쓰고 의도치 않은 버전이 깔릴 수 있어 최후의 수단입니다. 둘 다 근본 해결은 아니므로 프로덕션이면 overrides로 버전을 고정하세요.

Q. npm WARN ERESOLVE overriding peer dependency는 고쳐야 하나요? A. 아니요. WARN은 에러가 아니라 optional peer 경고입니다. 설치는 정상 완료되며 빌드가 멈추지 않습니다. 무시하고 진행해도 됩니다.

Q. overrides를 넣었는데 적용이 안 돼요. A. lockfile 캐시 때문입니다. rm -rf node_modules package-lock.json 후 npm install로 다시 받아야 반영됩니다. npm 8.3 이상인지(npm -v)도 확인하세요. 그 미만은 overrides를 지원하지 않습니다.