npm ERESOLVE 에러 해결법 — unable to resolve dependency tree

증상

패키지를 설치하려는데 이런 에러가 뜨면서 설치가 거부됩니다.

npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error
npm error While resolving: my-project@0.0.1
npm error Found: astro@7.0.6
npm error Could not resolve dependency:
npm error peer astro@"^1.6.0 || ... || ^5.0.0" from @vite-pwa/astro@1.2.0

원인

피어 의존성(peer dependency) 버전 불일치입니다. 설치하려는 패키지가 “나는 A 패키지의 1~5 버전과만 호환된다”고 선언해 놨는데, 내 프로젝트에는 A의 7 버전이 깔려 있는 상황입니다. npm 7부터는 이 충돌을 발견하면 설치를 아예 중단시킵니다.

에러 메시지에서 두 줄만 읽으면 됩니다.

• Found: — 내 프로젝트에 실제로 설치된 버전
• peer ... from ... — 설치하려는 패키지가 요구하는 버전 범위

해결 방법 3가지

1. 호환되는 버전이 있는지 먼저 확인 (권장)

npm view 문제패키지 versions --json

최신 버전이 내 환경을 지원할 수도 있습니다. 패키지의 GitHub 이슈에서 “support Astro 7” 같은 키워드로 검색해 보는 것도 빠릅니다.

2. –legacy-peer-deps로 강제 설치

npm install 문제패키지 --legacy-peer-deps

피어 의존성 검사를 건너뛰고 설치합니다. 대부분 작동하지만 보장은 없습니다. 선언만 오래됐고 실제로는 호환되는 경우가 많아서 시도해 볼 가치는 있습니다. 다만 이후 모든 npm install에서 같은 옵션이 필요해질 수 있다는 점을 기억하세요.

3. 그 패키지 없이 해결하기

의외로 자주 최선의 답입니다. 제 경우 PWA 플러그인(@vite-pwa/astro)이 Astro 7을 지원하지 않아 충돌이 났는데, 플러그인이 해주는 일이 매니페스트 + 서비스워커 생성뿐이라 직접 20줄 작성으로 대체했습니다. 의존성 하나가 줄면 이런 충돌을 겪을 일도 하나 줄어듭니다.

정리