npm ERR! code ERESOLVE 의존성 충돌 에러 해결하기

 

"npm install 쳤는데 빨간 줄이 수십 개 떴어요!" 멘붕에 빠진 프론트엔드 개발자분들 주목! 악명 높은 ERESOLVE 의존성 충돌 에러의 원인부터 캐시를 싹 밀어버리고 강제로 패키지를 설치하는 속 시원한 해결법까지 완벽 정리해 드립니다.

 

새로운 프로젝트를 클론받거나, 오랜만에 토이 프로젝트를 열어서 기분 좋게 npm install을 입력했는데... 터미널 화면이 온통 시뻘건 에러 메시지로 도배된 적 있으신가요? 특히 npm ERR! code ERESOLVE라는 문구를 보면 진짜 눈앞이 캄캄해지죠. "나는 코드 한 줄 건드린 게 없는데 도대체 왜 이러는 거야!" 하면서 모니터를 샷건 치고 싶었던 경험, 프론트엔드 개발자라면 다들 한 번쯤 있으실 거예요. 솔직히 완전 짜증 나잖아요. 😭

저도 신입 시절에 이 에러 하나 잡겠다고 스택오버플로우를 하루 종일 뒤지다가, 결국 팀장님께 헬프를 요청했던 쓰라린 기억이 납니다. 하지만 알고 보면 이 에러는 내 코드가 망가진 게 아니라, 패키지들끼리 버전이 안 맞아서 멱살 잡고 싸우는(?) 아주 자연스러운 현상이랍니다. 오늘 제가 이 지긋지긋한 의존성 충돌 에러를 부드럽게 달래는 방법부터, 도저히 안 될 때 쓰는 강력한 '캐시 폭파' 팁까지 아낌없이 대방출할게요. 이 글만 다 읽으시면 앞으로 터미널 빨간 줄도 두렵지 않으실 거예요! 😊

 

1. 도대체 ERESOLVE 에러가 뭘까? 🤔

문제를 해결하려면 녀석의 정체부터 알아야겠죠? ERESOLVE 에러는 쉽게 말해 '피어 의존성(Peer Dependency) 충돌'입니다. NPM이 버전 7로 대규모 업데이트를 하면서 이전에 비해 보안과 버전 관리가 엄청나게 깐깐해졌거든요.

예를 들어, 내 프로젝트는 최신 'React 18' 버전을 쓰고 있는데, 내가 설치하려는 예쁜 캘린더 라이브러리가 속으로는 'React 17' 버전만 호환된다고 고집을 부리는 상황입니다. 예전 NPM(버전 6 이하)에서는 "그래, 뭐 일단 깔아줄게. 작동 안 되면 네 책임~" 하고 넘어갔지만, 요즘 NPM은 "잠깐! 둘이 버전 안 맞잖아! 나 이거 설치 못 해!" 하고 설치 자체를 엎어버립니다. 이게 바로 ERESOLVE 에러의 실체예요.

💡 알아두세요!
React 18이 출시된 직후에 이 에러가 전국적으로 폭발(?)했었습니다. 수많은 서드파티 라이브러리들이 미처 React 18 버전에 맞춰 업데이트를 하지 못했기 때문이죠.

 

2. 해결책 1단계: 강제 설치 마법의 명령어 🪄

가장 빠르고 대중적인 해결책은 터미널에 옵션을 추가해서 NPM의 깐깐한 성격을 잠시 죽여놓는(?) 것입니다. 주로 2가지 마법의 명령어가 쓰이는데요, 상황에 맞게 골라 쓰시면 됩니다.

명령어 옵션	특징 및 추천 상황
--legacy-peer-deps	NPM 버전 6처럼 피어 의존성 검사를 무시하고 설치합니다. 가장 안전하고 실무에서 1순위로 추천하는 방법입니다. 예: npm install --legacy-peer-deps
--force	버전 충돌뿐만 아니라 로컬 캐시까지 무시하고 억지로 패키지들을 쑤셔 넣습니다. legacy 방식으로도 해결이 안 될 때 사용하는 최후의 수단입니다. 예: npm install --force

⚠️ 주의하세요!
--force 옵션은 진짜 꼭 필요할 때만 쓰세요! 억지로 설치는 완료되겠지만, 나중에 앱을 실행했을 때 런타임 에러(흰 화면)가 발생할 확률이 높습니다. 가급적 --legacy-peer-deps로 타협하는 것이 좋습니다.

 

3. 해결책 2단계: 최후의 보루, node_modules 폭파 💣

명령어 옵션으로도 해결이 안 되거나, 알 수 없는 캐시 꼬임 현상이 발생했다면? 제 생각엔 이때는 우주에서 가장 무겁다는 그 폴더, node_modules를 과감하게 싹 밀어버리고 초기화하는 게 최고예요.

어설프게 하나씩 지우느니 백지상태에서 다시 시작하는 게 시간도 절약되고 멘탈에도 좋거든요. 터미널 명령어가 헷갈리시는 분들을 위해 제가 자주 쓰는 '원터치 캐시 초기화 마법사'를 만들어봤습니다. 본인의 환경을 선택해 보세요!

🔧 패키지 완전 초기화 명령어 생성기

사용 중인 패키지 매니저: NPM 사용 Yarn 사용

// 아래 명령어를 복사해서 터미널에 한 줄씩 입력하세요!

참고로 윈도우(CMD) 환경이시라면 rm -rf 대신에 해당 폴더를 마우스 우클릭해서 직접 지워주신 뒤에 캐시 클린 명령어부터 따라 하시면 됩니다. 락(lock) 파일까지 싹 지우고 다시 설치하면 언제 그랬냐는 듯 뽀송뽀송하게 설치가 완료될 거예요!

핵심 요약 📝

오늘 알아본 ERESOLVE 의존성 에러 탈출 비법을 보기 쉽게 카드 한 장으로 요약해 드릴게요.

💊

NPM 의존성 에러 구급상자

1. 원인 파악: NPM v7 이상의 엄격해진 피어 의존성(Peer Dependency) 검사로 인해 라이브러리 간 버전 충돌이 일어났기 때문입니다.

2. 1차 대응 (가장 추천):

npm install --legacy-peer-deps

과거 방식대로 충돌 검사를 무시하고 설치를 진행합니다.

3. 최종 필살기: 꼬일 대로 꼬였다면, node_modules와 package-lock.json을 완전 삭제한 뒤, npm cache clean --force를 실행하고 처음부터 재설치하세요!

더 이상 붉은 터미널 창 앞에서 떨지 마세요!

 

자주 묻는 질문 ❓

Q: --legacy-peer-deps 말고 아예 에러를 안 나게 할 순 없나요?

A: 완벽한 해결을 위해서는 에러 메시지에 뜨는 문제가 되는 패키지의 버전을 수동으로 낮추거나(Downgrade), 혹은 프로젝트 자체의 React 버전을 패키지에 맞춰야 합니다. 하지만 실무에서는 시간이 없기 때문에 보통 legacy 옵션으로 우회하는 것이 국룰이 되었습니다.

Q: Yarn을 쓰는데도 ERESOLVE가 뜰 수 있나요?

A: ERESOLVE는 주로 NPM v7+ 특유의 엄격한 검사 때문에 뜹니다. Yarn은 의존성 충돌 시 에러를 뿜기보다는 경고(Warning)만 띄우고 알아서 설치를 진행해 주는 편이라 상대적으로 스트레스가 적습니다. NPM 때문에 너무 고생하셨다면 이 기회에 Yarn이나 pnpm으로 갈아타시는 것도 강력히 추천해요!

Q: npm cache clean --force를 치면 내 컴퓨터 파일들이 지워지는 건가요?

A: 걱정 마세요! 여러분의 소스 코드나 개인 파일이 지워지는 게 아니라, NPM이 패키지를 빨리 다운로드하려고 꽁꽁 숨겨두었던 '임시 다운로드 찌꺼기'들만 삭제되는 겁니다. 가끔 이 찌꺼기가 오염돼서 에러를 뱉기도 하거든요.

매번 우리를 멘붕에 빠트리는 의존성 충돌 에러! 오늘 제가 알려드린 --legacy-peer-deps 신공과 node_modules 초기화 비법으로 앞으로는 당황하지 말고 쿨하게 넘어가시길 바랍니다. 코딩하시다가 또 꽉 막히는 에러가 생기면 언제든 댓글로 질문 남겨주세요~ 즐겁게 코딩해요! 😊