설치가 자꾸 실패해서 파봤더니, 내 npm이 중국 서버를 보고 있었다
2026.07.26
npm 설치 실패: 중국 서버 문제 해결
"그런 버전 없다"는 에러가 떴는데 진짜 원인은 버전이 아니었다. npm이 받아오는 서버 주소가 두 달 전부터 바뀌어 있었고 나는 몰랐다. 추적부터 복구까지 5분.
한 줄 요약 — 에러 메시지가 가리킨 곳(패키지 버전)과 진짜 원인(패키지를 받아오는 서버)이 달랐다.
npm config get registry한 줄로 5분 만에 잡았다.
이런 분께 도움이 됩니다
npm install이 이유 없이 실패하는데 검색해도 안 나오는 분내 컴퓨터에 내가 설정하지 않은 게 있을까 찝찝한 분
남이 준 템플릿·스크립트를 그대로 따라 쓴 적 있는 분 (거의 전부)
설치 실패의 원인 분석
사이트를 Vercel로 배포하려고 CLI를 설치했다. 흔한 명령어다.
Open optionsauto
npm install -g vercel
복사그런데 이렇게 죽었다.
Open optionsauto
npm error code ETARGET
npm error notarget No matching version found for @vercel/[email protected].
npm error notarget In most cases you or one of your dependencies are requesting
npm error notarget a package version that doesn't exist.
복사“그런 버전이 존재하지 않는다.”
여기서 보통 하는 짓이 있다 — 캐시를 지우고, 버전을 낮춰서 깔아보고, 검색창에 ETARGET vercel을 친다. 나도 그럴 뻔했다.
그런데 이상했다. vercel은 하루에도 수만 명이 까는 패키지다. 공식 패키지가 자기 의존성 버전을 틀리게 적어놨을 리가 없다. 그러면 “버전이 없다”고 말하는 쪽을 의심해야 한다.
💡 여기가 갈림길이었다. 에러 메시지는 “요청한 쪽이 잘못됐다”고 말했지만, 실제로는 “대답한 쪽이 못 따라온 것”이었다.
문제 해결을 위한 추적 과정
패키지 존재 여부 확인
Open optionsauto
npm view vercel version
npm view "@vercel/build-utils" versions --json
복사결과: vercel의 최신은 57.0.0인데, @vercel/build-utils는 13.34.0까지만 보였다. 요구하는 13.35.0이 정말 안 보인다.
여기서 확신이 왔다. 패키지가 없는 게 아니라, 내가 보고 있는 목록이 낡은 것이다.
서버 주소 확인
Open optionsauto
npm config get registry
복사Open optionsauto
https://registry.npmmirror.com
복사여기였다. npm의 기본값은 https://registry.npmjs.org(공식)인데, 내 컴퓨터는 알리바바가 운영하는 중국 미러 서버를 보고 있었다. 그 미러가 최신 패키지를 아직 못 받아온 것이다.
설정 변경 원인 추적
Open optionsauto
npm config get userconfig
복사Open optionsauto
C:\Users\<사용자명>\.npmrc
복사열어봤다. 딱 한 줄 있었다.
Open optionsauto
registry=https://registry.npmmirror.com
복사파일 수정 시각을 봤다. 두 달 가까이 전이었다.
중국 미러 서버의 영향과 해결
나는 이걸 설정한 기억이 없다. 그런데 그 사이 설치한 모든 패키지가 이 서버를 거쳐서 내 컴퓨터에 들어왔다.
솔직히 찝찝했다. 그래서 그냥 넘기지 않고 따져봤다.
미러 서버가 뭔가 — 원본 서버를 복제해두는 곳이다. 중국은 해외 서버가 느려서 이런 미러를 쓰는 게 표준에 가깝다. 알리바바가 운영하고, 예전 npm.taobao.org의 후신이다. 악성 사고를 낸 적은 알려진 바 없다. 수상한 곳은 아니다.
그런데 나한테 이득이 있나 — 없다. 미러의 장점은 중국 내 속도인데 나는 한국에 있고, 공식 서버가 충분히 빠르다.
리스크는 있나 — 원리상 있다. 미러는 중간자다. 변조된 파일을 내려줄 수 있는 자리에 있다. npm의 무결성 검사(해시 대조)는 공식 서버에서 받은 lock 파일이 있을 때 방패가 되는데, 처음부터 미러에서 받으면 해시도 미러가 준 값이라 대조가 무의미해진다.
정리하면 — 얻는 건 없고, 신뢰만 넘기고 있었고, 오늘은 손해(설치 실패)까지 봤다.
되돌리기로 했다.
npm 설정 복구 방법
백업 생성
Open optionsauto
cp ~/.npmrc ~/.npmrc.backup
복사Windows PowerShell이면:
Open optionsauto
Copy-Item "$HOME\.npmrc" "$HOME\.npmrc.backup"
복사설정 제거
Open optionsauto
npm config delete registry --location=user
복사파일을 직접 열어 지워도 되지만, 이 명령이 형식을 안 깨뜨려서 안전하다.
설정 복구 확인
Open optionsauto
npm config get registry
복사Open optionsauto
https://registry.npmjs.org/ ✅
복사캐시 비우기
Open optionsauto
npm cache clean --force
복사이걸 안 하면 낡은 목록이 캐시에 남아 같은 에러가 또 날 수 있다.
재설치
Open optionsauto
npm install -g vercel
복사Open optionsauto
added 284 packages in 15s ✅
복사설치 후 변화
Before | After | |
|---|---|---|
받아오는 서버 | 중국 미러 (동기화 지연) | 공식 |
설치 결과 |
| 15초 만에 성공 |
안 상태 | 두 달간 몰랐음 | 어디를 보는지 알고 있음 |
진단부터 복구까지 5분. 검색으로 헤맸으면 훨씬 길었을 것이다.
배운 점
에러 메시지의 한계
화면은 “그런 버전 없다”고 말했다. 진짜 문제는 “낡은 서버를 보고 있다”였다. 둘은 완전히 다른 층위다.
메시지를 그대로 검색창에 넣기 전에 한 번 물어보면 좋다 — “이 말을 하고 있는 게 누구지?” 여기서는 npm이었고, npm이 그 말을 하려면 어딘가에 물어봤을 테고, 그 “어딘가”가 범인이었다.
환경 설정의 중요성
설정 파일 한 줄은 깨지기 전까지 아무 소리도 안 낸다. 두 달을 몰랐다.
남의 스크립트를 실행하거나, 강의를 따라 하거나, 도구를 설치할 때 설정 파일이 바뀌는 일은 흔하다. 그게 나쁜 의도인 경우는 드물지만, 모르는 채로 있는 것 자체가 문제다.
의심의 중요성
이 건은 “중국 서버라니 찝찝한데”라는 생각에서 시작됐다. 그냥 넘겼으면 설치만 겨우 되고 설정은 그대로 남았을 것이다. 찝찝함은 무시할 신호가 아니라 확인할 신호다.
재사용 가능한 팁
npm 설치 실패 시 진단 방법
무슨 에러든 이 세 줄부터 돌려보면 범위가 확 줄어든다.
Open optionsauto
npm config get registry # 어디서 받아오는지 ← 여기가 제일 자주 범인
npm config get userconfig # 설정 파일이 어디 있는지
npm config list # 지금 걸려 있는 설정 전부
복사registry가 https://registry.npmjs.org가 아니면 일단 의심한다.
설정 복구 방법
Open optionsauto
npm config delete registry --location=user
npm cache clean --force
npm config get registry # registry.npmjs.org 나오면 성공
복사검문소 3개
npm install 하나에 284개 패키지가 딸려온다. 전부 읽는 사람은 없다. 목표는 “전부 이해하기”가 아니라 어디서 한 번 멈출지 아는 것이다.
언제 | 확인할 것 |
|---|---|
설치할 때 | 이게 뭐고 왜 필요한지 한 줄로 설명할 수 있나 |
설정이 바뀔 때 | 어느 파일에 뭐가 적히는지 ← 제일 잘 새는 구멍 |
밖으로 나갈 때 | 공개·배포·전송 직전에 뭐가 나가는지 |
오늘 걸린 건 2번이었다. 그리고 2번은 아무도 안 알려준다.
마무리
배포하려다 만난 사고였는데, 정작 배포보다 이게 더 남았다.
내 컴퓨터인데 내가 모르는 설정이 있었다는 사실. 그리고 그걸 발견한 계기가 대단한 실력이 아니라 “좀 찝찝한데”라는 한마디였다는 것.
도구를 늘려갈수록 이런 게 쌓인다. 전부 막을 수는 없지만, 어디를 봐야 하는지는 알아둘 수 있다. 오늘은 그 한 곳(npm config get registry)을 알았다.




알고 보니 중국 미러 서버를 보고 있었다는 걸 발견했을 때는 진짜 황당하셨을 것 같아요. 설치 실패 사례인데 읽고 나니
npm config get registry는 꼭 기억해둬야겠다는 생각이 듭니다.