npm install 의존성 충돌 해결: ERESOLVE 오류가 날 때 해결법

패키지를 하나 설치하려 했을 뿐인데 peer dependency 충돌 로그가 길게 나오면 어떤 패키지를 바꿔야 할지 판단하기 어렵습니다.

이 글에서 확인할 내용

아래 섹션 링크를 통해 필요한 내용을 바로 확인할 수 있습니다.

ERESOLVE 로그는 충돌한 두 패키지를 찾는 것부터 시작합니다
peer dependency는 같이 써야 하는 버전 약속입니다
과 lockfile을 같이 봅니다
해결은 업데이트, 다운그레이드, 대체 패키지 순서로 판단합니다
--legacy-peer-deps는 임시 우회로만 봅니다
발행 전 마지막 점검 기준
실제 작업에서는 재현 조건을 먼저 고정합니다
같은 오류가 반복되지 않게 기록할 것

ERESOLVE 로그는 충돌한 두 패키지를 찾는 것부터 시작합니다

npm install의 ERESOLVE 오류는 의존성 트리를 만들 수 없다는 뜻입니다. 로그가 길지만 핵심은 보통 두 줄입니다. 현재 설치된 패키지 버전과 다른 패키지가 요구하는 peer dependency 버전입니다. 예를 들어 React 19를 쓰는데 어떤 라이브러리가 React 18 peer dependency만 허용하면 충돌이 납니다. 먼저 Found와 Could not resolve dependency 또는 peer 메시지를 찾아 어떤 패키지끼리 부딪혔는지 표시합니다.

npm install 의존성 충돌이 로컬이 아니라 배포 중에 터진다면 Vercel Next.js 배포 실패 체크리스트에서 Node 버전, lock 파일, install 로그를 함께 확인하는 것이 좋습니다.

peer dependency는 같이 써야 하는 버전 약속입니다

peer dependency는 이 패키지가 특정 라이브러리와 함께 쓰일 때 기대하는 버전 범위입니다. 플러그인, UI 라이브러리, React 관련 도구에서 자주 보입니다. 충돌을 해결하려면 새로 설치하려는 패키지를 낮출지, 기존 핵심 패키지를 올릴지, 호환되는 다른 버전을 찾을지 결정해야 합니다. 단순히 최신 버전으로 맞추는 것이 항상 답은 아닙니다. 프로젝트의 React, Next.js, TypeScript 기준과 맞아야 합니다.

npm install
npm explain react
rm -rf node_modules
npm install

package.json과 lockfile을 같이 봅니다

package.json은 원하는 버전 범위이고 lockfile은 실제 설치 트리의 기록입니다. 오래된 lockfile이 남아 있거나 package.json과 lockfile이 어긋나면 충돌을 더 찾기 어려워집니다. 팀 프로젝트에서는 패키지 매니저 하나를 정하고 lockfile도 하나만 유지하는 것이 좋습니다. lockfile 기준으로 엄격하게 재현하려면 npm ci를 먼저 보고, 의존성 변경을 반영해야 하는 일반 재설치라면 npm install과 lockfile diff를 함께 확인합니다.

해결은 업데이트, 다운그레이드, 대체 패키지 순서로 판단합니다

충돌한 패키지가 오래된 경우에는 해당 패키지의 최신 버전이 현재 React나 Next.js를 지원하는지 확인합니다. 반대로 프로젝트 핵심 버전이 너무 최신이라 주변 패키지가 따라오지 못한다면 다운그레이드가 더 현실적일 수 있습니다. 유지보수가 멈춘 패키지라면 대체 패키지를 검토합니다. 해결 후에는 npm install만 보지 말고 npm run build까지 확인해야 실제 충돌이 사라졌는지 알 수 있습니다.

`--legacy-peer-deps`는 임시 우회로만 봅니다

--legacy-peer-deps나 --force는 설치를 통과시키는 데 도움이 될 수 있지만 충돌 자체를 해결한 것은 아닙니다. --legacy-peer-deps는 peer dependency 계약을 무시하고 트리를 만들며, --force는 더 넓은 보호 장치를 끄는 옵션이라 기본 해결책으로 남기면 위험합니다. 급하게 로컬 확인이 필요할 때만 쓰고, 어떤 충돌을 우회했는지 기록한 뒤 가능한 한 호환되는 버전 조합으로 정리하는 것이 좋습니다.

공식 npm 문서 기준으로 npm explain은 패키지가 현재 프로젝트에 설치된 의존성 체인을 보여주고, npm ci는 lockfile 기반의 깨끗한 설치에 적합합니다. 또한 legacy-peer-deps는 peerDependencies를 무시하므로 권장되는 기본 해결책이 아닙니다. 자세한 기준은 npm explain 문서, npm ci 문서, npm legacy-peer-deps 설정 문서를 함께 확인하면 좋습니다.

발행 전 마지막 점검 기준

설치가 한 번 통과했다고 바로 끝난 것은 아닙니다. 충돌한 패키지 이름, 요구하는 peer dependency 범위, 실제로 선택한 해결 방법을 다시 확인해야 다음 설치나 배포에서 같은 오류를 줄일 수 있습니다.

ERESOLVE 로그에서 충돌한 패키지 두 개를 확인했는가?
package.json과 lockfile이 같은 패키지 매니저 기준으로 정리되어 있는가?
업데이트, 다운그레이드, 대체 패키지 중 어떤 선택을 했는지 기록했는가?
npm install 뒤에 npm run build까지 확인했는가?
--legacy-peer-deps나 --force를 썼다면 임시 우회인지 구분했는가?

실제 작업에서는 재현 조건을 먼저 고정합니다

의존성 충돌은 로컬 설치, CI 설치, Vercel 같은 배포 환경에서 다르게 보일 수 있습니다. 먼저 Node 버전, npm 버전, 패키지 매니저, lockfile 종류를 고정한 뒤 같은 조건으로 다시 설치해 봅니다.

재현 조건이 정리되면 lockfile 기준의 반복 가능성을 보려면 npm ci를 사용하고, 의존성을 실제로 바꾸는 중이라면 npm install 후 lockfile 변경을 확인합니다. 이미 설치된 트리에서 특정 패키지가 왜 들어왔는지 볼 때는 npm explain 패키지명으로 유입 경로를 확인할 수 있습니다. 배포에서만 실패한다면 로컬과 배포 환경의 Node 버전, install 명령, lockfile 반영 여부를 함께 비교합니다.

같은 오류가 반복되지 않게 기록할 것

문제를 해결한 뒤에는 어떤 패키지가 어떤 peer dependency 범위를 요구했는지, 어떤 버전 조합으로 정리했는지 남겨둡니다. 팀 프로젝트라면 Node 버전, npm 버전, 패키지 매니저, lockfile 종류도 함께 적어두는 것이 좋습니다.

특히 우회 옵션을 사용했다면 이유와 제거 기준을 남겨야 합니다. 기록이 있어야 다음 설치나 배포에서 같은 ERESOLVE 오류가 나왔을 때 임시 우회인지, 실제 호환성 정리가 필요한 상황인지 빠르게 판단할 수 있습니다.

이 글이 마음에 드세요?

RSS 피드를 구독하세요!