패키지를 하나 설치하려 했을 뿐인데 peer dependency 충돌 로그가 길게 나오면 어떤 패키지를 바꿔야 할지 판단하기 어렵습니다.
ERESOLVE 로그는 충돌한 두 패키지를 찾는 것부터 시작합니다
의 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과 lockfile을 같이 봅니다
은 원하는 버전 범위이고 lockfile은 실제 설치된 버전 기록입니다. 오래된 lockfile이 남아 있거나 과 lockfile이 섞이면 충돌을 더 찾기 어려워집니다. 팀 프로젝트에서는 패키지 매니저 하나를 정하고 lockfile도 하나만 유지하는 것이 좋습니다. node_modules를 지우고 lockfile 기준으로 다시 설치해보면 현재 프로젝트가 재현 가능한 상태인지 확인할 수 있습니다.
해결은 업데이트, 다운그레이드, 대체 패키지 순서로 판단합니다
충돌한 패키지가 오래된 경우에는 해당 패키지의 최신 버전이 현재 React나 Next.js를 지원하는지 확인합니다. 반대로 프로젝트 핵심 버전이 너무 최신이라 주변 패키지가 따라오지 못한다면 다운그레이드가 더 현실적일 수 있습니다. 유지보수가 멈춘 패키지라면 대체 패키지를 검토합니다. 해결 후에는 만 보지 말고 run build까지 확인해야 실제 충돌이 사라졌는지 알 수 있습니다.
–legacy-peer-deps는 임시 우회로만 봅니다
–legacy-peer-deps나 –force는 설치를 통과시키는 데 도움이 될 수 있지만 충돌 자체를 해결한 것은 아닙니다. 급하게 로컬 확인이 필요할 때는 쓸 수 있지만, 배포나 팀 프로젝트의 기본 해결책으로 남기면 나중에 더 큰 문제가 됩니다. 어떤 충돌을 우회했는지 기록하고가능한 한 호환되는 버전 조합으로 정리하는 것이 좋습니다.
발행 전 마지막 점검 기준
의존성 충돌 해결: ERESOLVE 오류가 날 때 대처 방법은 문제 해결형 글이므로 독자가 바로 따라 할 수 있는 순서가 중요합니다. 증상부터 원인을 좁히고로컬에서 재현한 뒤, 설정과 버전 차이를 확인하는 흐름으로 마무리해야 합니다. 기존 글과 겹치는 설명은 길게 반복하지 않고, 현재 글에서는 어떤 기준으로 다음 행동을 선택할지 남기는 것이 좋습니다.
실제 발행 전에는 제목과 포커스 키워드가 너무 넓지 않은지, 본문 이미지가 문제 해결 흐름을 설명하는지, WordPress JSON의 카테고리와 Rank Math 포커스 키워드가 비어 있지 않은지 확인합니다. 이 점검까지 끝나야 단순 초안이 아니라 업로드 가능한 작성본으로 볼 수 있습니다.
실제 작업에서는 재현 조건을 먼저 고정합니다
의존성 충돌 해결: ERESOLVE 오류가 날 때 대처 방법 같은 문제 해결형 글은 해결 명령어를 바로 나열하는 것보다 재현 조건을 고정하는 과정이 중요합니다. 같은 코드라도 로컬 개발 서버로컬 빌드, Preview 배포, Production 배포에서 다르게 동작할 수 있기 때문입니다. 독자는 먼저 어느 환경에서 문제가 나는지 표시하고같은 조건으로 다시 실행해본 뒤 원인을 좁혀야 합니다.
문제가 재현되는 조건을 적어두면 수정 후 검증도 쉬워집니다. 예를 들어 환경변수 문제라면 개발 서버 재시작 전후를 나눠 보고, 의존성 문제라면 node_modules를 지운 뒤 lockfile 기준으로 다시 설치합니다. 폼 validation 문제라면 submit 전과 submit 후의 errors 객체를 비교하고, 문제라면 브라우저 Network 탭에서 Origin과 응답 코드를 확인합니다.
또 하나 중요한 점은 임시 우회와 실제 해결을 구분하는 것입니다. 빌드 옵션을 끄거나 강제 설치 옵션을 쓰면 당장 지나갈 수는 있지만, 다음 배포에서 다시 막힐 수 있습니다. 글 본문에서는 빠른 확인 방법을 소개하되, 최종적으로는 설정과 버전을 맞추고 원인을 기록하는 쪽으로 안내해야 합니다.
같은 오류가 반복되지 않게 기록할 것
문제를 해결한 뒤에는 어떤 로그가 원인이었는지, 어떤 설정을 바꿨는지, 어떤 버전 기준으로 맞췄는지 남겨두는 것이 좋습니다. 팀 프로젝트라면 README나 작업 메모에 Node 버전, 패키지 매니저, 환경변수 이름, 배포 플랫폼 설정 위치를 적어두면 다음 사람이 같은 시간을 쓰지 않아도 됩니다.
블로그 글에서도 이 기록 방식이 중요합니다. 독자가 글을 읽고 단순히 “해결했다”에서 끝나는 것이 아니라, 다음에 같은 증상이 나오면 어디부터 확인해야 하는지 기억할 수 있어야 합니다. 그래서 마지막에는 증상, 확인 위치, 수정 방법, 재발 방지 기준을 짧게 다시 연결해주는 구성이 좋습니다.
마지막으로, 해결 후에는 같은 증상이 다시 나왔을 때 바로 비교할 수 있도록 수정 전후 조건을 남깁니다. 어떤 명령어를 실행했는지, 어떤 로그가 바뀌었는지, 어떤 설정값을 수정했는지 적어두면 다음 배포나 다음 설치에서 문제를 더 빨리 좁힐 수 있습니다. 문제 해결 글의 목적은 한 번의 정답을 외우게 하는 것이 아니라, 비슷한 오류를 만났을 때 확인 순서를 떠올리게 만드는 데 있습니다.
이 기준은 혼자 작업할 때보다 팀 프로젝트에서 더 중요합니다. 누군가는 같은 오류를 로컬에서 보고, 다른 사람은 배포 환경에서만 볼 수 있습니다. 그래서 오류 메시지 원문, 실행한 명령어, 사용한 Node/npm 버전, 수정한 설정 파일을 함께 남겨두면 문제 해결 과정이 개인 기억에만 의존하지 않습니다.