npm ERR! ERESOLVE 의존성 충돌 해결

증상

npm install 도중 설치가 멈추고 다음과 같은 오류가 출력됩니다.

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^18.0.0" from some-lib@1.2.3

원인

설치하려는 패키지의 **peer dependency(요구 버전)**가 현재 설치된 버전과 맞지 않습니다. 예를 들어 라이브러리는 React 18을 요구하는데 프로젝트는 React 19를 쓰는 경우입니다. npm 7+ 부터 이 충돌을 기본적으로 막습니다.

해결

1) 충돌 메시지 먼저 읽기

Could not resolve dependency 아래에 어떤 패키지가 무슨 버전을 요구하는지 나옵니다. 가능하면 그 패키지를 호환 버전으로 올리거나 내립니다.

npm install some-lib@latest

2) peer 충돌 무시하고 설치 (임시 우회)

npm install --legacy-peer-deps

package.json이 아닌 환경 설정으로 고정하려면:

npm config set legacy-peer-deps true

3) 깨끗하게 재설치

캐시·lock 꼬임이 원인일 때:

rm -rf node_modules package-lock.json
npm install

--force는 충돌을 강제로 덮어써 더 위험합니다. 우선 --legacy-peer-deps로 우회하고, 근본적으로는 충돌난 패키지 버전을 맞추는 것이 안전합니다.