npm 설치 시간 초과가 Clash 문제처럼 보이는 이유
npm install이 멈추거나 패키지 의존성을 내려받는 과정에서 ETIMEDOUT, ECONNRESET, socket hang up 같은 오류가 반복되면 먼저 npm 레지스트리 자체의 장애를 의심하기 쉽습니다. 하지만 같은 명령이 다른 네트워크에서는 정상적으로 끝나고, 브라우저는 잘 열리는데 터미널에서만 실패한다면 npm보다 Clash와 Node.js 프로세스 사이의 연결 경로를 먼저 확인하는 편이 빠릅니다.
npm은 한 번의 요청만 보내지 않습니다. 기본 레지스트리에서 패키지 메타데이터를 조회한 뒤 tarball을 내려받고, 의존성마다 새로운 HTTPS 연결을 만들며, 때로는 Git 저장소나 별도 CDN에도 접속합니다. 따라서 첫 번째 레지스트리 주소는 열리더라도 특정 패키지의 파일 다운로드만 다른 규칙을 타면 설치가 중간에 멈출 수 있습니다. 화면에는 단순히 “시간 초과”라고 표시되지만 실제 원인은 잘못된 프록시 포트, DIRECT로 빠진 호스트, 불안정한 노드, DNS 지연 중 하나일 수 있습니다.
특히 Clash Verge Rev 또는 Mihomo를 켠 뒤 브라우저만 정상이고 npm install만 실패한다면, 브라우저는 시스템 프록시를 자동으로 사용하지만 현재 셸이나 Node.js HTTP 클라이언트는 그 설정을 모를 가능성이 큽니다. 반대로 TUN 모드를 켜 둔 상태에서 모든 연결이 느려졌다면 프록시 주입 문제가 아니라 가상 어댑터, IPv6, DNS 처리 순서가 충돌하는 상황일 수도 있습니다.
Clash 포트와 npm 프록시 설정부터 확인하기
가장 먼저 Clash의 혼합 포트 또는 HTTP 포트가 실제로 열려 있는지 확인합니다. Clash 계열 클라이언트의 기본 포트는 프로필과 실행 방식에 따라 달라질 수 있으므로 7890이라는 숫자를 무조건 사용하지 말고 UI의 포트 표시와 코어 로그를 기준으로 판단해야 합니다. HTTP 프록시 포트와 SOCKS 포트가 따로 있다면 npm에는 보통 HTTP 형식으로 접근할 수 있는 혼합 포트를 지정하는 것이 이해하기 쉽습니다.
셸에서 다음처럼 현재 npm 설정을 확인합니다.
npm config get registry
npm config get proxy
npm config get https-proxy
npm config get strict-ssl
proxy와 https-proxy에 예전에 사용하던 포트나 종료된 로컬 프록시 주소가 남아 있으면 Clash가 실행 중이어도 npm은 다른 곳으로 접속합니다. 필요하다면 현재 Clash 포트에 맞춰 값을 다시 지정합니다.
npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890
npm config set registry https://registry.npmjs.org/
포트 번호는 예시이므로 실제 Clash 설정으로 바꾸세요. 회사 네트워크나 보안 정책 때문에 npm에 프록시를 직접 넣고 싶지 않다면 기존 값을 제거하고 TUN 또는 셸 환경 변수 방식으로 통일할 수 있습니다.
npm config delete proxy
npm config delete https-proxy
환경 변수도 함께 확인해야 합니다. Windows PowerShell에서는 Get-ChildItem Env:HTTP_PROXY와 Get-ChildItem Env:HTTPS_PROXY를, macOS·Linux 셸에서는 다음 명령을 사용합니다.
echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $NO_PROXY
npm 설정에는 새 포트가 들어 있는데 환경 변수에는 오래된 포트가 남아 있으면, 실행 중인 패키지나 하위 프로세스가 서로 다른 경로를 사용할 수 있습니다. 진단할 때는 한 가지 방식을 선택하고 중복된 프록시 변수를 정리하는 것이 좋습니다. NO_PROXY에 레지스트리 도메인이 들어 있으면 의도와 달리 DIRECT 연결이 될 수 있으므로 registry.npmjs.org 같은 항목도 확인합니다.
직접 재현하며 규칙과 노드를 분리하는 순서
설정을 한꺼번에 바꾸면 어떤 조치가 효과가 있었는지 알 수 없습니다. 다음 순서는 npm, Clash 규칙, 노드, DNS를 하나씩 분리하는 실전 점검 방법입니다.
- 레지스트리 주소를 확인합니다. 사내 미러나 오래된 개인 레지스트리가 설정되어 있다면 잠시 공식 주소로 바꾸고, 문제가 특정 레지스트리에만 재현되는지 기록합니다.
- 작은 패키지로 테스트합니다. 큰 프레임워크 전체를 설치하기 전에 임시 디렉터리에서 가벼운 패키지의 메타데이터를 조회합니다.
- Clash 로그에서 호스트를 찾습니다.
registry.npmjs.org가 어떤 규칙과 아웃바운드 그룹으로 처리되는지 보고, 예상과 다른DIRECT또는 기본 그룹으로 빠지는지 확인합니다. - 같은 그룹의 다른 노드를 선택합니다. 노드를 바꿨을 때만 성공한다면 npm 설정이 아니라 해당 출구의 연결 품질, TLS 처리, 레지스트리 접근성이 원인일 가능성이 높습니다.
- 브라우저와 터미널을 비교합니다. 브라우저에서 레지스트리 주소가 열려도 npm이 같은 프록시를 쓴다는 뜻은 아닙니다. 터미널에서 verbose 로그를 함께 확인해야 합니다.
간단한 확인 명령은 다음과 같습니다.
npm view lodash version --verbose
npm ping --verbose
curl -I -v https://registry.npmjs.org/
Windows 환경에서 curl이 다른 프로그램으로 연결될 수 있다면 PowerShell의 Invoke-WebRequest도 비교해 볼 수 있습니다. npm ping은 성공하지만 실제 설치가 실패한다면 레지스트리의 기본 응답보다 tarball 다운로드나 의존성의 별도 호스트에서 문제가 생긴 것입니다. 이때는 설치 로그에 나타난 URL과 Clash의 연결 로그에 찍힌 도메인을 한 줄씩 대조해야 합니다.
반대로 npm ping부터 시간 초과라면 패키지 잠금 파일이나 특정 의존성의 문제가 아닙니다. 이 경우에는 포트가 열려 있는지, npm이 프록시를 실제로 사용하고 있는지, 규칙 모드에서 레지스트리 요청이 올바른 그룹에 들어가는지를 먼저 확인합니다.
규칙, DNS, TUN 모드를 조정하는 방법
npm 트래픽을 전부 전역 프록시로 보내면 빠르게 원인을 확인할 수 있지만, 장기 설정으로는 과할 수 있습니다. 사내 패키지 서버나 국내 미러를 무조건 해외 노드로 보내면 오히려 지연이 커지고 인증이 실패할 수 있기 때문입니다. 먼저 로그에서 실제 사용하는 호스트를 확인한 뒤 필요한 도메인만 같은 전략 그룹에 넣는 방식이 안전합니다.
# Example only — adapt the group name and order to your profile
rules:
- DOMAIN-SUFFIX,registry.npmjs.org,NPM-OUT
- DOMAIN-SUFFIX,npmjs.org,NPM-OUT
- DOMAIN-SUFFIX,github.com,NPM-OUT
- DOMAIN-SUFFIX,githubusercontent.com,NPM-OUT
- MATCH,GLOBAL
모든 설치가 GitHub를 사용하는 것은 아니므로 위 규칙을 그대로 복사하기보다 실제 로그에 나온 호스트만 추가하세요. 패키지의 package.json에 Git URL이 있거나 설치 스크립트가 바이너리를 별도로 내려받는 경우에만 GitHub 관련 도메인이 필요할 수 있습니다. 규칙은 위에서 아래로 평가되므로 넓은 DOMAIN-SUFFIX,com이나 외부 RULE-SET보다 구체적인 npm 규칙이 앞에 있어야 합니다.
DNS도 시간 초과의 중요한 원인입니다. Clash가 fake-ip 모드를 사용하고 있는데 Node.js, 운영체제, 다른 VPN 클라이언트가 서로 다른 DNS 응답을 캐시하면 레지스트리 호스트는 해석되지만 실제 연결 주소가 불안정해질 수 있습니다. 갑자기 모든 노드에서 같은 오류가 나거나, IPv6 환경에서만 멈춘다면 DNS 모드와 IPv6 우선순위를 함께 확인합니다. 설정을 바꾼 뒤에는 Clash 코어를 재시작하고 기존 Node 프로세스도 새로 실행해야 오래된 DNS 결과가 남지 않습니다.
TUN은 시스템 프록시를 인식하지 않는 Node.js 도구나 IDE 내장 터미널에 유용합니다. 그러나 이미 회사 VPN, 보안 에이전트, Docker 네트워크가 동작하는 컴퓨터에서 TUN을 바로 켜면 라우팅 우선순위가 바뀌어 문제가 더 복잡해질 수 있습니다. 권장 순서는 혼합 포트와 npm 설정 확인 → 시스템 프록시로 재현 → 환경 변수 주입 → 마지막으로 TUN 검토입니다. TUN을 켠 뒤 실패했다면 무조건 유지하지 말고, TUN을 끈 상태에서 같은 명령을 다시 실행해 변화 자체를 기록하세요.
오류별 원인과 안정적인 운영 기준
ETIMEDOUT은 일정 시간 안에 연결이나 응답이 완료되지 않았다는 뜻이지, 반드시 노드가 차단되었다는 의미는 아닙니다. 프록시 포트가 닫혀 있거나, DNS 응답이 늦거나, 선택된 노드가 연결은 되지만 큰 파일 전송에서 속도를 유지하지 못해도 같은 오류가 나타납니다. ECONNRESET은 중간 장비나 원격 서버가 연결을 끊은 경우가 많으므로 다른 노드와 직접 비교해야 합니다. UNABLE_TO_VERIFY_LEAF_SIGNATURE처럼 인증서 오류가 나오면 시간 초과와 달리 TLS 가로채기, 회사 인증서, 잘못된 시스템 시간이 관련될 수 있습니다. 진단을 위해 strict-ssl=false를 영구 적용하는 것은 권하지 않습니다.
설치가 중간에 멈췄을 때 캐시를 무작정 삭제하는 것도 좋은 첫 단계는 아닙니다. 먼저 어떤 URL에서 멈췄는지 로그를 보존한 뒤, 프록시와 규칙을 고친 다음 다시 시도하세요. 캐시를 삭제하면 재다운로드 양이 늘어나 네트워크 문제가 오히려 더 크게 드러날 수 있습니다. 특정 프로젝트에서만 실패한다면 package-lock.json에 기록된 Git 의존성, 사설 레지스트리, 설치 스크립트의 다운로드 URL을 점검하고, 모든 프로젝트에서 실패한다면 Clash 경로를 우선 의심합니다.
또한 npm의 동시 요청 수와 재시도 옵션을 과도하게 높이면 불안정한 노드에서 문제가 악화될 수 있습니다. 노드가 느린 상태에서 여러 tarball을 동시에 받으면 연결이 반복해서 끊기고, 사용자는 Clash가 전체적으로 고장 난 것으로 느낄 수 있습니다. 먼저 안정적인 노드를 선택하고 작은 패키지로 성공 여부를 확인한 뒤, 필요할 때만 npm의 타임아웃이나 재시도 값을 조정하는 편이 재현성과 유지보수에 유리합니다.
일부 전용 프록시 도구는 애플리케이션별 설정은 간단하지만 Node 하위 프로세스나 Git 의존성까지 일관되게 처리하지 못하고, 규칙을 세밀하게 나누기 어려운 경우가 있습니다. 반면 Clash는 npm 레지스트리·Git 호스트·사내 미러를 규칙별로 분리하고, 노드 그룹과 DNS·TUN 경로를 로그로 함께 확인할 수 있어 원인을 단계적으로 좁히기 쉽습니다. npm 설치 시간 초과를 포트, 규칙, 노드, DNS 순서로 점검하고 싶다면 Clash 클라이언트를 준비해 같은 명령을 다시 재현하는 것이 가장 자연스러운 다음 단계입니다.