npm install 시간 초과가 발생하는 이유
Clash를 켠 상태에서 npm install이 멈추거나 ETIMEDOUT, ECONNRESET, EAI_AGAIN 오류를 반복한다면, 원인을 곧바로 노드 속도로 단정하지 않는 것이 좋습니다. npm 패키지 설치는 레지스트리에서 패키지 정보를 조회한 다음, tarball 파일을 내려받고 의존성을 확인하는 여러 단계로 이루어집니다. 이 과정 중 어느 한 단계라도 연결이 끊기면 설치가 오래 멈춘 것처럼 보일 수 있습니다.
특히 터미널이 Clash의 프록시를 사용하지 않는 경우, Clash 규칙에서 npm 도메인을 잘못된 그룹으로 보내는 경우, npm에 오래된 프록시 주소가 저장된 경우를 자주 확인해야 합니다. 반대로 레지스트리까지 연결되는데 특정 패키지만 실패한다면, 패키지 서버의 일시적인 문제나 프로젝트의 의존성 문제일 수도 있습니다. 아래 순서대로 범위를 좁히면 불필요하게 노드와 설정을 한꺼번에 바꾸지 않아도 됩니다.
먼저 확인할 점
오류가 발생한 터미널, 사용 중인 Clash 클라이언트, 현재 프록시 포트를 기록해 두세요. 설정을 하나씩 변경하고 같은 명령으로 다시 시험해야 어떤 조치가 효과가 있었는지 알 수 있습니다.
1Clash 모드와 npm 규칙 확인
브라우저에서 사이트가 열리는 것만으로 터미널의 npm 트래픽도 프록시를 통과한다고 보장할 수는 없습니다. 시스템 프록시만 켠 상태에서는 앱이나 셸이 시스템 설정을 따르지 않을 수 있고, TUN 모드가 꺼져 있으면 일반적인 시스템 프록시를 지원하지 않는 프로그램은 직접 연결을 시도할 수 있습니다. Clash Verge 또는 Clash Verge Rev에서는 먼저 연결 상태와 모드를 확인한 뒤, Clash 대시보드의 연결 목록에서 설치 중인 트래픽이 실제로 표시되는지 살펴보세요.
- Global 모드에서 성공하고 Rule 모드에서 실패: npm 도메인에 적용되는 규칙이나 규칙 순서가 원인일 가능성이 큽니다.
- 브라우저는 되지만 터미널은 실패: 터미널의 프록시 환경 변수, npm 프록시 설정 또는 TUN 모드를 확인하세요.
- 모든 연결이 느리거나 끊김: 선택한 노드의 상태와 지연 시간을 확인하고, 다른 정상 노드로 비교 시험을 진행하세요.
Rule 모드를 사용한다면 레지스트리 도메인이 예상한 프록시 그룹에 도달하는지 확인합니다. 구독 설정을 직접 수정하기 어렵다면 클라이언트의 연결 화면에서 registry.npmjs.org 요청을 찾아 어떤 규칙과 프록시가 선택됐는지 확인하는 편이 안전합니다.
여기서 PROXY는 예시일 뿐입니다. 실제 설정에 존재하는 프록시 그룹 이름으로 바꾸어야 하며, 규칙을 추가할 수 없는 관리형 구독이라면 임의로 원본 설정을 덮어쓰지 마세요. 또한 DIRECT와 프록시 중 어느 쪽이 빠른지는 네트워크 환경마다 다릅니다. 한쪽을 정답으로 가정하지 말고, 대시보드에 표시되는 실제 연결 경로와 테스트 결과를 기준으로 선택하세요.
2레지스트리와 연결 오류 분리
npm이 어느 레지스트리를 사용 중인지부터 확인합니다. 프로젝트의 .npmrc, 사용자 설정, 환경 변수에서 레지스트리나 프록시 값이 지정되면 기본값과 다르게 동작할 수 있습니다. 터미널에서 다음 명령을 실행해 현재 설정을 확인하세요.
일반적인 공개 레지스트리를 사용할 때 주소는 보통 https://registry.npmjs.org/입니다. 회사나 팀에서 별도의 사설 레지스트리를 지정했다면 그 주소가 정상인지 관리자에게 확인하세요. 설정을 바꿔도 효과가 없다면 프로젝트 폴더의 .npmrc에 별도 값이 있는지 살펴보되, 인증 토큰이나 비밀번호를 로그나 공개된 글에 붙여 넣지 마세요.
npm ping이 바로 실패하면 레지스트리 접근, DNS 또는 프록시 경로를 우선 점검합니다. ping은 성공하지만 설치 중 특정 패키지에서 멈춘다면, 레지스트리가 안내한 tarball 주소로의 연결이나 해당 패키지의 배포 상태가 문제일 수 있습니다. 오류 종류도 단서가 됩니다. ETIMEDOUT은 응답을 기다리다 시간이 끝난 경우, ECONNRESET은 연결이 중간에 닫힌 경우, EAI_AGAIN은 일시적인 DNS 조회 실패에서 자주 나타납니다.
레지스트리를 무작정 바꾸지 마세요
임의의 미러 주소로 바꾸면 패키지 출처와 잠금 파일의 일관성이 달라질 수 있습니다. 사내 레지스트리나 팀에서 지정한 주소가 있다면 이를 우선 사용하고, 공개 레지스트리로 바꿀 때는 프로젝트 요구 사항을 확인하세요.
3터미널 프록시 설정을 단계별로 점검
중간 단계에서는 Clash가 실행 중인 상태에서 터미널이 프록시를 실제로 사용하는지 확인합니다. 로컬 프록시 포트는 설치 환경에 따라 다르므로 7890이라고 가정하지 말고, Clash 클라이언트의 포트 설정에서 HTTP 또는 mixed-port 값을 확인하세요. SOCKS 포트와 HTTP 포트는 서로 다를 수 있으며, npm에 프로토콜이 맞지 않는 주소를 지정하면 연결이 실패할 수 있습니다.
- 현재 값 확인: macOS 또는 Linux에서는
env | grep -i proxy, PowerShell에서는Get-ChildItem Env:*proxy*를 실행해 프록시 환경 변수를 확인합니다. - 임시 프록시 지정: 실제 HTTP 프록시 포트가 7890인 경우에만 아래 예시를 사용합니다. 본인의 포트에 맞게 주소를 바꾸세요.
- 연결 결과 비교: 같은 터미널에서
npm ping을 실행하고, Clash 연결 화면에 해당 요청이 보이는지 확인합니다. - 시험 후 정리: 임시 환경 변수만 사용했다면 터미널을 닫으면 적용이 끝납니다. 셸 설정 파일에 영구 등록했다면 시험 후 필요 여부를 다시 검토하세요.
※ 위 주소의 포트는 예시입니다. Clash 설정에서 실제 HTTP 또는 mixed-port를 확인하고, SOCKS 전용 포트를 HTTP 프록시 주소로 잘못 지정하지 마세요.
환경 변수를 지정한 뒤 성공하고 지정하지 않았을 때 실패한다면, 터미널이 시스템 프록시 설정을 따르지 않는 것이 원인일 수 있습니다. 반대로 환경 변수를 지정해도 실패한다면 포트 오입력, Clash의 프록시 수신 설정, 네트워크 방화벽 또는 선택한 규칙 그룹을 확인하세요. npm 설정 자체에 예전 프록시가 남아 있는 경우에는 현재 값을 확인한 다음 필요할 때만 정리합니다.
4시간 초과와 캐시 문제 해결
연결은 되지만 느린 노드에서만 설치가 오래 걸린다면, 프록시 그룹에서 다른 노드를 선택해 같은 명령을 비교합니다. 일부 노드는 웹 페이지 접속에는 괜찮아도 패키지 파일처럼 용량이 큰 다운로드에서 속도 변동이나 연결 재설정이 발생할 수 있습니다. 노드를 바꿀 때는 한 번에 하나만 변경하고, Clash 로그와 npm 오류 메시지를 함께 확인하세요.
npm의 재시도와 대기 시간을 조정하면 일시적인 흔들림을 견디는 데 도움이 될 수 있지만, 잘못된 규칙이나 끊어진 프록시를 고쳐 주지는 않습니다. 먼저 안정적인 연결을 확인하고 필요한 경우에만 제한적으로 조정하세요. 설치가 무한정 늦어지지 않도록 시간 초과 값을 과도하게 크게 설정하는 것은 권장하지 않습니다.
npm cache clean --force를 습관처럼 실행할 필요는 없습니다. 캐시가 손상되었는지 의심된다면 우선 npm cache verify로 확인하세요. 또한 설치를 빠르게 하려고 strict-ssl=false를 설정하면 TLS 인증서 검증이 비활성화되어 보안 위험이 생깁니다. 인증서 오류가 있다면 프록시의 TLS 처리, 시스템 시간, 사내 인증서 설정을 확인하고 검증을 끄는 방식으로 해결하지 마세요.
원인 판별 기준
같은 프로젝트를 다른 정상 네트워크에서도 설치해 보세요. 다른 네트워크에서는 성공하고 Clash 사용 중에만 실패하면 규칙·노드·터미널 프록시를 우선 점검하고, 어디서나 같은 패키지에서 실패하면 프로젝트 설정과 패키지 배포 상태를 확인하세요.
5재발 방지를 위한 점검 순서
문제가 해결된 뒤에는 정상 동작했던 조건을 간단히 기록해 두면 다음 설치 실패 때 시간을 절약할 수 있습니다. 사용한 Clash 모드, 선택한 프록시 그룹, 레지스트리 주소, 터미널 프록시 환경 변수, 오류 코드와 발생 시점을 함께 적어 두세요. 특히 여러 프로젝트에서 같은 문제가 반복되는지, 한 프로젝트에 한정되는지도 구분하면 원인 범위를 빠르게 좁힐 수 있습니다.
- 설치 전에: Clash가 실행 중인지, 선택한 노드가 정상인지, npm 레지스트리 값이 의도한 주소인지 확인합니다.
- 실패 직후: 오류 코드와 마지막으로 다운로드한 URL을 확인하고, Clash 연결 목록에서 해당 요청의 규칙 및 경로를 찾습니다.
- 설정을 변경할 때: 프록시 변수, 규칙, 레지스트리 중 하나씩만 바꾸고
npm ping과 설치를 다시 시험합니다. - 팀 프로젝트에서는:
package-lock.json을 임의로 삭제하거나 갱신하기 전에 팀의 설치 절차와 Node.js, npm 버전을 확인합니다.
Clash는 npm 전용 가속기가 아니라 요청을 규칙에 따라 전달하는 프록시 도구입니다. 따라서 모든 시간 초과를 프록시 모드 하나로 해결하려 하기보다, 레지스트리 연결 여부와 터미널의 실제 경로를 먼저 확인하는 편이 효과적입니다. 이 과정을 따르면 네트워크 문제와 프로젝트 문제를 구분하고, 보안 설정을 불필요하게 낮추지 않으면서 안정적인 설치 환경을 만들 수 있습니다.