pip·conda 글과 무엇이 다른가
pip·conda·PyPI·Anaconda CDN 가이드가 파이썬 쪽 패키지 메타와 휠·conda 패키지 바이너리를 나눈다면, 여기서는 Node.js의 npm·pnpm·yarn 계열이 쓰는 npm registry 축만 집중합니다. 공식 퍼블릭 레지스트리는 패키지 버전을 가리키는 JSON과 실제 .tgz 아카이브를 한 레이어에서 제공하는 경우가 많지만, 기업 미러·지역 미러(npmmirror 등)·사내 Verdaccio·그리고 git+https://github.com/… 종속이 섞이면 클라이언트 한 번 실행 안에도 도메인이 최소 세 갈래로 퍼집니다. 그 상태에서 FINAL 규칙 한 줄이 전부 DIRECT로 새거나 반대로 느린 단일 프록시에만 몰리면, GUI 브라우저는 나쁘지 않은데 터미널 pnpm install만 멈춘 것처럼 보입니다.
pnpm는 콘텐츠 주소 가능 저장소와 하드 링크 설계 때문에 동일 tarball을 여러 프로젝트에서 재사용하지만, lockfile에 박힌 resolved URL이 레지스트리·미러·GitHub 중 어디를 가리키는지에 따라 Clash에서 맞춰야 할 SNI 이름이 갈라집니다. npm 역시 npm view로 보는 메타데이터 호스트와 실제 GET이 가는 위치가 사용자의 .npmrc·레지스트리 설정에 의해 바뀝니다. 따라서 「npm registry 느리다」는 말을 실제 로그의 호스트 문자열로 바꿔 적는 것부터가 Clash 분류의 출발점입니다.
자주 나오는 증상 패턴
첫째, 메타데이터는 빠른데 tarball만 0% 근처에서 멈춘다는 패턴입니다. DNS는 풀리는데 특정 노드에서만 대용량 TLS 스트림이 끊기거나, 회사 회선이 긴 RTT 구간에서만 타임아웃이 날 때 흔합니다. 둘째, 공식 registry.npmjs.org만 쓰는데도 간헐적으로 실패한다면, 실패 시점의 URL이 정말로 그 호스트인지(302·리다이렉트 후보, 미러 프리픽스, 캐시 프록시) 로그를 펼쳐 봐야 합니다. 셋째, GitHub에서만 git 종속 설치가 무너진다면 github.com과 codeload.github.com, objects.githubusercontent.com 등이 서로 다른 규칙 행에 잡히고 있지 않은지 의심합니다. 넷째, 미러로 바꾼 뒤에만 증상이 바뀐다면 새 미러 도메인이 광범위한 GEOIP,CN,DIRECT 같은 앞줄에 먼저 걸려 「미러는 직통인 줄 알았는데 실제로는 다른 그룹을 탄」 경우가 많습니다.
로그에서 봐야 할 호스트 묶음
아래 이름은 기준점일 뿐이며, 실패 직후 npm install --verbose·pnpm의 디버그 출력·Clash 연결 목록에 찍힌 실제 SNI를 최우선으로 하세요.
- NPM-REGISTRY: 공식이라면
registry.npmjs.org와 팀이 지정한 사내 레지스트리 FQDN. 메타데이터·일부 tarball GET이 여기로 이어질 수 있어, 미러를 쓰지 않는 구성에서는 이_suffix 하나에 트래픽이 몰리기도 합니다. - NPM-MIRROR:
registry.npmmirror.com등 합법적으로 선택한 미러 전용 호스트. 공식과 다른 인증서·경로를 쓰므로 규칙 행도 별도 그룹으로 두는 편이 디버깅에 유리합니다. 팀 정책과 라이선스 범위 안에서만 사용해야 합니다. - NPM-TARBALL-LARGE: lockfile의
resolved가 가리키는 별도 호스트가 있다면(예: 일부 배포가 CDN 도메인으로 분리된 경우) 그 이름을 여기에 둡니다. npm 생태에서는 tarball이 레지스트리와 동일 도메인에 있는 경우가 많아, 이 그룹이 비어 있을 수도 있습니다. 비어 있다면NPM-REGISTRY에서 노드만 갈아도 충분한지 먼저 실험합니다. - GH-ASSETS:
github.com,codeload.github.com,objects.githubusercontent.com, 때로는raw.githubusercontent.com까지. scoped 패키지가 Release tarball을 붙여 두었거나git+https종속이 있을 때 필수 축입니다. - NODE-DIST(선택):
nodejs.org등 런타임 바이너리를 같이 깔 때만 별도 그룹을 고려합니다. 터미널 셸 프록시와 묶이면 증상이 겹쳐 보입니다.
Clash는 대개 도메인·IP 단위로만 라우팅하므로, 동일 호스트에서 메타와 tarball을 모두 처리할 때는 서로 다른 proxy-group으로 “경로 분리”는 불가합니다. 이때는 노드 품질·대역 제한·미러 정책으로 운영 문제를 푸는 쪽이 맞고, 반대로 호스트가 실제로 갈라진 경우에만 이 글의 분류 이득이 큽니다.
예시 YAML: 이름은 구독에 맞게 교체
전역에 넓은 DIRECT나 GEOIP가 앞서 있으면 아래 블록은 호출되지 않습니다. 더 구체적인 DOMAIN 행을 위쪽에 두는 패턴을 잊지 마세요.
# Example — replace proxy names; order is global
proxy-groups:
- name: NPM-REGISTRY
type: select
proxies:
- 🇰🇷 Domestic-low-latency
- ♻️ Auto
- DIRECT
- name: NPM-MIRROR
type: select
proxies:
- 🇯🇵 Stable
- DIRECT
- name: NPM-TARBALL-LARGE
type: select
proxies:
- 🇸🇬 High-bandwidth
- ♻️ Auto
- DIRECT
- name: GH-ASSETS
type: select
proxies:
- Stable-github
- DIRECT
rules:
- DOMAIN-SUFFIX,npmmirror.com,NPM-MIRROR
- DOMAIN-SUFFIX,registry.npmmirror.com,NPM-MIRROR
- DOMAIN,registry.npmjs.org,NPM-REGISTRY
- DOMAIN-SUFFIX,github.com,GH-ASSETS
- DOMAIN-SUFFIX,codeload.github.com,GH-ASSETS
- DOMAIN-SUFFIX,objects.githubusercontent.com,GH-ASSETS
- DOMAIN-SUFFIX,raw.githubusercontent.com,GH-ASSETS
# If lockfile shows a separate tarball CDN host, add a DOMAIN row above GENERIC rules
# and point it to NPM-TARBALL-LARGE
원격 규칙 세트를 쓰는 프로필이라면 Rule Providers 안의 순서와 로컬 덮어쓰기 위치가 충돌하지 않는지 확인합니다. 한 줄이라도 더 위에서 예기치 않은 그룹에 매칭되면 rule hit 로그만 보고는 원인을 놓치기 쉽습니다.
npmrc·pnpm 설정과 터미널 프록시
많은 IDE·CI 스텝은 macOS·Windows의 시스템 프록시를 따르지 않습니다. Clash TUN을 켜면 대부분의 프로세스가 같이 묶이지만, 회사 VPN·split tunnel과 겹치면 예외가 남습니다. export HTTPS_PROXY=http://127.0.0.1:7890 같은 변수를 한 번에 하나만 바꿔 가며 재현해 보고, NO_PROXY에 실수로 레지스트리 도메인이 들어가 있지 않은지도 봅니다.
.npmrc의 registry=, always-auth, 사내 Artifactory URL을 바꿨다면 그 FQDN이 Clash 규칙표에도 같은 그룹으로 들어왔는지 맞춥니다. pnpm는 ~/.npmrc와 프로젝트 로컬 설정을 함께 읽으므로, 팀원마다 미러 행이 다르면 “같은 저장소인데 나만 깨짐”이 나옵니다. Windows에서 WSL2를 쓸 때는 호스트 IP·포트 포워딩이 어긋나 터미널만 레지스트리에 닿지 않는 경우가 있어, Node 문제인지 경계 문제인지 먼저 가릅니다.
DNS·TUN과 DIRECT 오매칭
fake-ip를 쓰면 터미널 Resolver와 Mihomo의 해석 결과가 갈라져 TLS가 이상하게 끊길 수 있습니다. 연결은 되는데 앱만 실패할 때 글의 순서를 같이 적용하세요. QUIC이 앞줄에서 막혀 HTTP/3 클라이언트만 재시도 루프에 빠지는 경우도 있으니, 패키지 클라이언트 버전에 따라 스택이 달라질 수 있다는 점만 기억해 둡니다. TUN 모드는 시스템 프록시를 무시하는 프로세스까지 한데 묶어 주지만, DNS hijack 순서가 어긋나면 오히려 registry 호스트만 NXDOMAIN처럼 보일 수 있습니다.
검증 체크리스트
- 실패 직후 verbose 로그에서 실제 GET URL과 호스트를 한 줄로 복사합니다.
- 동일 시각 Clash 대시보드에서 해당 연결의 policy·rule name을 적어, 생각한 proxy-group이 맞는지 봅니다.
HTTPS_PROXY단독 테스트: 환경 변수만 바꿔 동일 패키지를 한 번 더 설치해 봅니다.- 레지스트리·미러·GitHub 그룹을 각각 바꿔 보고 어느 축을 움직일 때만 증상이 따라오는지 표로 남깁니다.
- 미러를 켠/끈 상태에서
npm config get registry와 pnpm의 effective 설정을 비교합니다. - 규칙 파일 상단의 광범위한
DIRECT·광고 필터가 패키지 호스트 이름을 건드리지 않았는지 검색합니다.
이 표만 있어도 팀 슬랙에 올릴 때 「레지스트리 그룹만 DIRECT 오매칭」처럼 구체적인 가설으로 바뀌고, 재시도 시간을 줄일 수 있습니다.
정리
npm registry와 tarball CDN·미러 도메인·GitHub 자산이 한 번의 pnpm install에 동시에 붙을 때, 단일 선택형 프록시 그룹만 바꿔서는 「가끔 되고 가끔 안 되는」 상태가 길어집니다. Clash 분류는 호스트 축을 먼저 쪼갠 뒤 노드를 실험 변수로 삼는 작업이라, 실제 로그의 SNI를 적어 두는 습관이 가장 큰 이득입니다. 같은 팀에서 Python 패키지 레지스트리와 Node 레지스트리를 나란히 운영한다면, proxy-group 이름만 맞춰도 인시던트 대응이 훨씬 단순해집니다.
그래도 같은 FQDN에서 메타와 tarball이 모두 처리된다면, 이 글에서 말한 「축 분리」 대신 대역이 버티는 노드·회선·미러 정책 쪽을 우선 조정하는 것이 맞습니다. 장기적으로는 Rule Providers로 패키지용 도메인 목록을 갱신하고, 로컬 YAML에는 팀에 필요한 좁은 규칙만 남기면 유지보수가 쉬워집니다.
이 과정을 거치면 브라우저용 일반 프록시보다 규칙 기반으로 트래픽을 나누는 도구가 장시간 다운로드와 짧은 API 왕복을 동시에 다룰 때 훨씬 수월하다는 점을 체감하게 됩니다. 설치·업데이트 경로를 안정적으로 맞추려면 Clash를 무료로 내려받고 같은 프로필로 터미널·IDE까지 정렬해 보기