Clash에서 npm install 시간 초과될 때 프록시 설정으로 해결하는 방법

npm install 시간 초과, Clash가 켜져 있는데도 실패하는 이유

Clash를 실행했는데도 npm install이 멈추거나 ETIMEDOUT, ECONNRESET, fetch failed 같은 오류를 낼 수 있습니다. 브라우저가 열리는 것과 터미널의 npm 요청이 프록시를 통과하는 것은 별개의 문제입니다. 브라우저는 운영체제의 시스템 프록시를 따를 수 있지만, Node.js와 npm은 셸 환경 변수나 npm 자체 설정을 참조하는 경우가 많습니다. 따라서 Clash 화면에 연결됨이라고 표시되어도 터미널 요청이 직접 연결로 나가거나, 아예 프록시 주소를 찾지 못할 수 있습니다.

npm 설치는 한 호스트에 한 번 연결하는 작업으로 끝나지 않습니다. registry.npmjs.org에서 패키지 정보와 버전을 조회한 뒤, 실제 패키지 파일을 별도 주소나 CDN에서 받기도 합니다. 메타데이터 요청은 성공했지만 tarball 다운로드가 다른 경로로 빠지면 진행률이 오래 멈춘 뒤 시간 초과가 발생할 수 있습니다. 의존성이 많은 프로젝트는 여러 호스트를 연속해서 요청하므로, 한 요청만 간헐적으로 실패해도 전체 설치가 중단된 것처럼 보입니다.

우선 노드를 계속 바꾸기보다 실패 시각의 Clash 연결 로그를 확인하세요. 로그에 npm 관련 호스트가 보이지 않는다면 터미널이 Clash 포트를 사용하지 않는 가능성이 큽니다. 로그에는 요청이 나타나지만 정책이 DIRECT라면 규칙이나 모드 문제를 의심하고, 프록시 그룹으로 연결됐는데도 실패한다면 노드 상태, DNS, 원격 서버의 응답을 차례로 확인합니다. 증상과 로그를 함께 비교하는 것이 무작정 레지스트리를 바꾸는 것보다 빠릅니다.

프록시 모드·노드·규칙을 먼저 점검하기

먼저 Clash 클라이언트에서 코어가 실행 중인지, 현재 프로필이 활성 상태인지 확인합니다. 구독 화면에 노드가 보여도 코어가 시작되지 않았거나 프로필을 전환한 뒤 설정이 적용되지 않았다면 실제 연결은 기대와 다를 수 있습니다. 이후 모드가 Rule인지 확인하세요. Global 모드는 진단할 때 잠시 비교할 수 있지만, 평상시에는 모든 요청을 한 정책으로 보내므로 내부 주소나 직접 연결이 필요한 환경에서 불필요한 영향을 줄 수 있습니다. 테스트가 끝나면 원래 모드로 되돌리는 것을 잊지 마세요.

다음으로 프록시 그룹에서 실제 선택된 노드가 정상인지 확인합니다. 지연 테스트 결과가 낮아도 npm 다운로드에 필요한 연결이 안정적이라는 뜻은 아닙니다. 노드를 선택한 뒤 간단한 웹 요청과 npm 요청을 각각 실행해 비교하면 문제가 특정 서비스에 한정되는지 구분하기 쉽습니다. Clash 연결 로그에서 요청 호스트, 매칭된 규칙, 선택된 정책 그룹, 최종 노드를 함께 확인하세요. 규칙 목록에서는 넓은 범위의 도메인이나 IP 규칙이 npm 호스트보다 먼저 매칭되는지 살펴봅니다. 더 구체적인 규칙을 추가하더라도 기존 규칙의 순서와 의미를 확인하고, 처음부터 광범위한 접미 규칙을 넣지는 않는 편이 안전합니다.

DNS 관련 오류도 시간 초과처럼 보일 수 있습니다. 도메인 이름이 해석되지 않는다면 노드를 바꾸기 전에 운영체제와 Clash 코어 중 어느 쪽에서 DNS 질의를 처리하는지 확인하세요. 같은 호스트에 대해 반복 실행할 때 IP가 계속 바뀌는 것만으로 장애라고 단정할 수는 없지만, 특정 네트워크에서만 이름 해석이 실패한다면 DNS 정책이나 사내 네트워크 제한을 살펴볼 이유가 됩니다. 회사나 학교 장비라면 승인되지 않은 프록시 설정을 적용하기 전에 관리자의 정책을 확인하세요.

터미널에서 Clash 프록시 연결을 확인하고 설정하기

npm이 Clash를 통과하는지 확인하려면 먼저 클라이언트에 표시된 HTTP 또는 mixed 포트 번호를 찾습니다. 기본 포트를 임의로 가정하지 말고 현재 프로필의 실제 값을 사용하세요. HTTP 프록시를 제공하는 포트라면 새 터미널 세션에서 환경 변수를 설정한 뒤 npm 명령을 실행할 수 있습니다. 아래 예시의 포트 번호는 설명용이므로 Clash 화면에 표시된 값으로 바꾸고, 셸 문법은 사용 중인 터미널에 맞춰 적용합니다.

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
npm ping
npm view <패키지명> version

Windows PowerShell에서는 같은 변수 설정 방식이 다르므로 bash 명령을 그대로 붙여 넣지 마세요. 또한 HTTP 프록시 포트와 SOCKS 포트는 용도가 다릅니다. SOCKS 포트를 HTTP 프록시 주소처럼 지정하면 연결이 실패하거나 예상과 다른 오류가 생길 수 있습니다. Clash에서 제공하는 포트 유형을 확인하고, Node.js와 npm이 지원하는 방식에 맞춰 설정하세요. mixed 포트는 여러 프록시 프로토콜을 받을 수 있지만, 실제 동작은 클라이언트와 코어 설정에 따라 다를 수 있습니다.

셸에서 프록시 변수를 적용한 뒤 npm ping이 성공하면 registry 연결의 기본 경로를 확인한 셈입니다. 이어서 문제가 있던 패키지를 조회하거나 설치해 보세요. npm ping은 성공하지만 설치만 멈춘다면 연결 로그에서 패키지 파일을 내려받는 호스트가 어떤 정책으로 처리되는지 확인합니다. 반대로 이 명령부터 실패하고 로그에도 요청이 보이지 않는다면 포트 번호, 프로토콜, 환경 변수의 적용 여부를 다시 점검합니다. 새 터미널을 열어야 셸 설정 파일의 변경이 반영되는 경우도 있습니다.

환경 변수를 한 번만 적용해 테스트하고 싶다면 현재 터미널 세션에서만 설정하세요. 셸 시작 파일이나 시스템 환경 변수에 영구 등록하면 다른 개발 도구까지 프록시를 사용하게 되어, 나중에 원인을 찾기 어려워질 수 있습니다. 특히 작업 네트워크를 바꾸거나 Clash를 종료한 뒤에도 프록시 변수가 남아 있으면 로컬 개발 서버와 패키지 설치가 함께 실패할 수 있습니다. 사용을 마친 뒤 변수 값을 확인하고, 필요하면 해당 세션을 닫거나 원래 값으로 복원하세요.

npm registry와 기존 프록시 설정을 안전하게 확인하기

현재 npm이 어떤 레지스트리와 프록시를 사용하고 있는지 확인하려면 먼저 설정값을 조회합니다. 프로젝트별 .npmrc, 사용자 홈 디렉터리의 설정 파일, 환경 변수는 서로 다른 값을 가질 수 있으므로 한 곳만 확인해서는 부족합니다. 아래 명령은 읽기 전용 조회이며, 출력에 인증 토큰이나 사용자 정보가 포함될 수 있으니 로그를 공유할 때는 민감한 값을 가리세요.

npm config get registry
npm config get proxy
npm config get https-proxy

registry가 조직의 사설 레지스트리나 승인된 미러로 지정되어 있다면, 곧바로 공용 주소로 덮어쓰기보다 해당 주소에 접근할 수 있는지 확인하세요. 프로젝트에서 정한 레지스트리를 임의로 바꾸면 의존성 정책, 잠금 파일, 내부 패키지 조회에 문제가 생길 수 있습니다. 반대로 개인 설정에 오래된 미러가 남아 있다면 관리자나 프로젝트 문서에서 공식 주소를 확인한 후 변경을 검토할 수 있습니다. 미러는 항상 더 빠르거나 더 안전한 것이 아니며, 출처와 운영 정책을 확인하지 않은 주소를 사용하지 않는 것이 좋습니다.

npm config set proxy 또는 npm config set https-proxy로 값을 기록하면 설정이 사용자나 프로젝트 범위에 남을 수 있습니다. 환경 변수로 일시 테스트한 뒤에도 계속 문제가 해결되는지 확인하고, 영구 설정이 꼭 필요할 때만 적용 범위를 정하세요. 기존에 프록시 값이 있었다면 변경 전에 기록해 두고, 작업 후 필요에 따라 원래 값으로 되돌립니다. npm의 인증 정보나 TLS 검증 설정을 끄는 방식은 시간 초과의 일반적인 해결책이 아닙니다. 특히 인증서 검증을 비활성화하면 연결 보안이 약해질 수 있으므로, 인증서 오류가 난 경우에는 회사 프록시 인증서나 시스템 인증서 구성을 별도로 확인해야 합니다.

설치가 중간에 멈춘 뒤에는 같은 명령을 무작정 여러 번 반복하기보다 오류가 발생한 시각과 패키지 이름을 남기세요. 프로젝트의 package-lock.json을 삭제하는 것도 첫 조치로 권장하지 않습니다. 잠금 파일은 의존성 버전을 고정하는 데 쓰이므로 삭제하면 설치 결과가 달라질 수 있습니다. 먼저 네트워크 경로를 수정하고, 캐시 문제를 의심할 근거가 있을 때만 npm 문서에 맞는 점검을 진행하세요. 사내 레지스트리나 CI 환경에서는 개인 PC의 설정을 복사하기보다 해당 환경의 공식 프록시 주소와 인증 절차를 따르는 것이 중요합니다.

설정 변경 후 재검증하고 원인을 기록하기

변경 후에는 테스트를 한 단계씩 진행합니다. 첫째, Clash가 켜져 있고 올바른 프로필과 노드가 선택됐는지 확인합니다. 둘째, 현재 터미널에서 프록시 주소와 포트가 실제 클라이언트 값과 일치하는지 확인합니다. 셋째, npm ping과 패키지 정보 조회를 실행하고, 마지막으로 문제가 있던 프로젝트에서 원래 설치 명령을 다시 실행합니다. 각 단계에서 성공 여부와 걸린 시간을 기록하면 어느 지점에서 해결됐는지 알 수 있습니다. 동시에 연결 로그를 확인하면 npm 요청이 의도한 정책 그룹과 노드를 사용하는지도 검증할 수 있습니다.

한 번 성공했다고 곧바로 모든 프로젝트에서 설정이 정상이라고 단정하지 마세요. 다른 저장소는 프로젝트별 .npmrc를 포함할 수 있고, 패키지마다 tarball을 제공하는 호스트도 다를 수 있습니다. 재현 조건에는 운영체제, 셸, Node.js와 npm 버전, Clash 클라이언트와 코어, 선택한 모드, 오류 메시지를 포함하되 구독 주소와 토큰은 절대로 기록하거나 공유하지 않습니다. 다음 업데이트에서 프로필이나 포트가 바뀌었다면 기존 환경 변수가 이전 포트를 가리키지 않는지도 확인합니다.

보안과 유지 관리도 함께 고려해야 합니다. 외부 패키지를 설치할 때는 프로젝트의 신뢰도와 의존성 변경 사항을 확인하고, 알 수 없는 스크립트를 관리자 권한으로 실행하지 마세요. 회사 네트워크에서 프록시 사용이 제한되어 있다면 우회 설정 대신 IT 담당자에게 승인된 레지스트리와 연결 방법을 문의해야 합니다. Clash 설정을 공유할 때는 노드 주소, 비밀번호, 구독 URL, API 키가 포함되지 않도록 먼저 검토합니다. 한 번에 규칙 여러 개와 npm 설정을 모두 바꾸면 어느 조치가 효과가 있었는지 알기 어려우므로, 한 항목씩 수정하고 결과를 남기는 것이 재발 방지에 도움이 됩니다.

레지스트리만 바꾸는 방식은 회사 미러나 tarball CDN처럼 서로 다른 호스트에서 생긴 문제를 해결하지 못할 수 있고, 다른 프록시 앱은 터미널이 시스템 프록시를 따르지 않는 상황에서 설정이 복잡해질 수 있습니다. 반면 Clash V.CORE에서는 프록시 상태와 연결 로그를 확인하고, 터미널의 실제 포트 설정과 라우팅 결과를 함께 점검할 수 있어 원인을 단계별로 좁히기 편리합니다. 사용하는 운영체제에 맞는 클라이언트를 확인하고 싶다면 다운로드 페이지에서 Clash V.CORE를 살펴보세요.