npm install 충돌 난 초보가 3분 만에 확인할 4가지

AI 코딩 도구가 “이 패키지를 설치하면 됩니다”라고 해서 npm install을 실행했는데, 터미널에 ERESOLVE unable to resolve dependency tree가 뜨는 순간이 있습니다. 초보자는 이때 두 방향으로 흔들립니다. 하나는 오류를 전부 이해해야 할 것 같은 부담이고, 다른 하나는 검색에서 본 --legacy-peer-deps를 바로 붙이고 싶은 마음입니다.

Tap to zoom

이 오류는 대개 실력 문제가 아니라 패키지끼리 요구하는 버전 범위가 맞지 않는 상황입니다. docs.npmjs.com의 npm 공식 package.json 문서는 peerDependencies가 어떤 패키지가 호스트 도구나 라이브러리와 호환되는지를 표현한다고 설명합니다. npm v7 이후에는 peer dependency가 기본으로 설치되고, 서로 충돌하는 요구가 있으면 설치가 실패할 수 있습니다.

1분째에는 ERESOLVE 블록에서 패키지 이름만 뽑습니다

터미널 로그가 길어도 처음 볼 곳은 하나입니다. npm ERR! code ERESOLVE가 나온 다음 블록에서 Found:와 Could not resolve dependency: 또는 peer로 시작하는 줄을 찾습니다.

Found: [email protected]
Could not resolve dependency:
peer react@"^18.x" from example-package

이 구조라면 문제는 npm 전체가 아니라 example-package가 기대하는 React 범위와 현재 프로젝트의 React 버전이 맞지 않는 것입니다. npm 문서도 충돌하는 peer dependency 요구가 있으면 트리를 올바르게 해결하지 못해 오류가 날 수 있다고 설명합니다.

이 단계에서는 해결책을 고르지 않습니다. 아래 세 줄만 채웁니다.

설치하려던 패키지:
현재 프로젝트의 패키지와 버전:
충돌을 요구한 패키지와 버전 범위:

이 세 줄이 있어야 AI에게 다시 물어도 “그냥 설치 옵션을 바꿔보세요”가 아니라 “이 패키지가 현재 버전을 지원하는지 보자”로 좁혀집니다.

2분째에는 package-lock 변화부터 막습니다

npm install은 패키지와 그 의존성을 설치합니다. npm install 공식 문서에 따르면 lockfile이 있으면 npm-shrinkwrap.json, package-lock.json, yarn.lock 순서로 설치에 영향을 주고, 설치 과정에서 package-lock.json이 업데이트될 수 있습니다. 그래서 충돌이 난 뒤에는 먼저 파일이 바뀌었는지 봐야 합니다.

git diff -- package.json package-lock.json

초보자가 흔히 놓치는 지점은 “설치가 실패했으니 아무것도 안 바뀌었겠지”라고 생각하는 것입니다. 실제로는 설치 시도, 재시도, 다른 플래그 사용 때문에 lockfile이나 package.json이 바뀌어 있을 수 있습니다. 충돌 원인을 모르는 상태에서 이 파일들이 계속 바뀌면 다음 오류가 원래 충돌인지, 방금 바꾼 설치 상태 때문인지 분리하기 어려워집니다.

아직 판단이 안 섰다면 파일을 저장하기 전에 이렇게 묻습니다.

package 파일 diff를 봐 주세요.
이번 npm install 충돌 해결에 필요한 변경인지,
되돌려야 할 설치 흔적인지 분류해 주세요.
새 설치 명령은 아직 제안하지 마세요.

이 요청은 AI에게 코드를 더 쓰게 하는 질문이 아닙니다. 설치 상태를 분류하게 하는 질문입니다.

3분째에는 npm explain으로 누가 끌고 왔는지 봅니다

충돌 패키지 이름을 알았다면 npm explain을 씁니다. npm explain 공식 문서는 이 명령이 현재 프로젝트에서 특정 패키지가 설치되게 만든 의존성 체인을 출력한다고 설명합니다.

npm explain react
npm explain example-package

여기서 중요한 것은 “어떤 패키지가 직접 설치한 것인지”와 “어떤 패키지가 다른 패키지를 통해 들어온 것인지”를 나누는 일입니다. 직접 설치한 패키지라면 버전을 바꾸거나 제거하는 판단이 비교적 쉽습니다. 반대로 다른 라이브러리가 끌고 온 하위 의존성이라면 그 상위 패키지를 업데이트하거나 대체해야 할 수 있습니다.

Tap to zoom

AI에게는 이렇게 묶어 주면 됩니다.

npm install에서 ERESOLVE가 났습니다.

설치하려던 패키지:
ERESOLVE의 Found 줄:
ERESOLVE의 peer 요구 줄:
npm explain 결과:

요청:
원인 패키지를 셋 중 하나로 분류해 주세요.
- 직접 의존성
- 하위 의존성
- peer 요구

그 다음 안전한 선택을 골라 주세요.
- 업데이트
- 대체 패키지
- 설치 보류

이 프롬프트의 핵심은 legacy-peer-deps를 먼저 묻지 않는 것입니다. 충돌의 소유자를 찾은 뒤에야 우회가 필요한지 판단할 수 있습니다.

legacy-peer-deps는 마지막에만 검토합니다

--legacy-peer-deps는 자주 보이는 해결책처럼 보입니다. 하지만 npm config 문서는 legacy-peer-deps가 패키지 트리를 만들 때 peerDependencies를 완전히 무시하게 하며, peer dependency 계약을 강제하지 않기 때문에 권장하지 않는다고 설명합니다. 설치가 지나가도 런타임이나 빌드에서 다른 문제가 날 수 있다는 뜻입니다.

그렇다고 이 플래그가 절대 쓰면 안 되는 금지어라는 뜻은 아닙니다. 오래된 프로젝트를 임시로 살리거나, 팀이 이미 같은 설정을 합의해 .npmrc에 기록한 경우도 있습니다. 문제는 초보자가 이 플래그를 “정답”처럼 외워서 쓰는 순간입니다.

우회 전에 네 가지를 확인합니다.

1. 충돌 패키지의 최신 버전이 현재 프로젝트 버전을 지원하는지 봅니다.
2. 같은 기능을 하는 다른 패키지가 현재 React나 Next.js 버전을 지원하는지 봅니다.
3. 팀 프로젝트라면 기존 .npmrc나 CI 설치 명령이 같은 플래그를 쓰는지 봅니다.
4. 우회 후에는 npm run build 또는 프로젝트의 테스트 명령을 반드시 실행합니다.

CI 환경이라면 npm ci도 구분해야 합니다. npm ci 공식 문서는 lockfile과 package.json의 의존성이 맞지 않으면 오류로 종료하고, 기존 node_modules를 제거한 뒤 설치하며, package.json이나 lockfile을 쓰지 않는다고 설명합니다. 로컬에서 npm install --legacy-peer-deps로 만든 lockfile을 CI에서 다른 플래그 없이 npm ci로 설치하면 다시 실패할 수 있습니다.

오늘 남길 결과물은 충돌 요약 4줄입니다

지금 설치가 막혔다면 터미널을 닫지 말고 아래 네 줄만 채웁니다.

설치하려던 명령:
Found 줄:
peer 요구 줄:
npm explain으로 확인한 패키지:

이 네 줄이 있으면 AI에게 다시 물을 때 프로젝트 전체를 던질 필요가 없습니다. npm install 충돌은 무조건 빨리 넘기는 문제가 아니라, 어떤 패키지가 어떤 버전을 요구하는지 먼저 가르는 문제입니다. 오늘은 우회 플래그를 붙이기 전에 충돌 이름과 버전 범위를 3분 안에 분리하는 데서 멈추면 됩니다.

참고 출처

• npm package.json peerDependencies: https://docs.npmjs.com/cli/v10/configuring-npm/package-json/
• npm install 공식 문서: https://docs.npmjs.com/cli/v10/commands/npm-install/
• npm explain 공식 문서: https://docs.npmjs.com/cli/v10/commands/npm-explain/
• npm ci 공식 문서: https://docs.npmjs.com/cli/v10/commands/npm-ci/
• npm config legacy-peer-deps: https://docs.npmjs.com/cli/v10/using-npm/config/