npm install がタイムアウト？Clash で registry と tarball CDN を分流する実測手順（2026）

検索の意図：npm install が「ずっと待つ」「ETIMEDOUT」になる現場

2026 年現在も、フロントエンドとバックエンドの両方で npm エコシステムは前提になっています。社内ネットワークや特定地域の回線では、npm install／pnpm の install／yarn の add が進行バーで固まったままになり、ログに ETIMEDOUT や ENOTFOUND、英語のネットワークエラーだけが増えていく——という相談は開発者から非常によく聞きます。原因の多くは「registry.npmjs.org に届かない」単純な一枚岩ではなく、パッケージメタデータの JSON を取りに行く通信と、その中に記載された tarball（.tgz） 実体ファイルを落とす通信が、立て続けに別々の律速条件にさらされていることにあります。

本稿は、Docker Desktop からのビルドや大容量の Git LFSの記事と並べて読めるよう、JavaScript パッケージマネージャの公式レジストリ経路にフォーカスします。API 集約や IDE 向けのドメイン束とは対象が異なるため、MCP やツール用の開発者向け分流と役割分担してください。ルールの読み方自体はルール分岐の詳解と共通です。

npm が叩くホスト：registry メタデータと tarball の関係

既定の registry=https://registry.npmjs.org/ では、クライアントはパッケージ名とバージョンに応じて レジストリ API に HTTPS で問い合わせ、返ってきた JSON の dist.tarball に書かれた URL へ続けて GET します。多くの公開パッケージでは、その URL も 同じ registry.npmjs.org 名前空間に収まりますが、運用やリダイレクト、将来の CDN 構成変更で別ホスト名がログに現れることはあり得ます。だから「レジストリ用ルールを一行書いたつもり」でも接続ビューに出る実名を見ずに完了しないのが典型の抜け穴です。

pnpm はストアとハードリンクの設計が異なり、yarn（Berry 系と Classic で挙動差）はロックファイルとキャッシュの置き場所が違っても、出口側から見ればやはり「HTTPS でレジストリに問い合わせ、 tarball を取得する」連鎖に収束しがちです。チームで国内ミラーや社内プロキシを挟んでいる場合は、公式ドキュメントどおりのホストではなくミラーの FQDNが律速になるので、その名前をルールに混ぜないと期待と逆の経路になります。

Clash で「npm 専用グループ」を切る理由

購読が「海外サイトまとめて一つの select」だけだと、軽い読み物サイトと数百 MB に及ぶ tarball 連打が同じ出口に載り、レイテンシテストの数字は悪くなくても長接続が途中で切れるノードでは npm だけ異常に不安定に見えます。NPM_REGISTRY のような名前の独立プロキシグループを用意し、registry.npmjs.org 向けだけそこへ流すと、次のような運用がしやすくなります。

  • 大容量転送向きの出口へ固定しやすい（ストリーミング用の細いノードと分離）
  • 接続ログで「どの tarball リクエストがどのグループに乗ったか」追いやすい
  • ブラウザや社内 SaaS 用の出口選択と干渉しにくい

コピー用： npm 公式レジストリ周辺のサフィックス例

実務の出発点として、次の DOMAIN-SUFFIX を挙げます。npm 社側のインフラは変更され得るため、詰まっているときは必ず手元のログで上書き・追加してください。

  • コア：registry.npmjs.org（メタデータと tarball の多くがここに載る）
  • 関連名前空間：npmjs.org（一部のリダイレクトや将来のホストに遭遇したらログで補強）
  • 任意：パッケージページ閲覧だけ遅い場合は www.npmjs.com を検討（開発取得の本丸は上）

DOMAIN-KEYWORD,npm のような広すぎる書き方は、意図しないサブドメインまで同じ出口に載せる恐れがあるため、まずはサフィックス二～三行から始め、verbose ログに出た別名を DOMAIN で足す方が安全です。

注意：企業のコンプライアンス、利用規約、輸出管理、および勤務先のセキュリティ方針に反しないかはご自身で確認してください。本稿は技術的なトラフィック分類の整理であり、特定のサービス利用を推奨するものではありません。

評価順：npm 行を GEOIP,CN や MATCH より上へ

Clash 系の rules: は上から最初の一致で終了します。DOMAIN-SUFFIX,registry.npmjs.org,NPM_REGISTRY をファイル末尾に足したつもりが、手前の巨大 RULE-SET や緩い GEOIP に飲み込まれている——というのは定番のミスです。GEOIP と DIRECT の優先順位を直した直後でも、より具体的なドメイン行は大雑把な締め行より常に上です。保存したあと YAML の該当ブロックだけ目視で並び替えを確認してください。

国内サイトとミラーを誤ってプロキシに載せない

検索意図のうち「海外の公式レジストリだけ出口へ」「国内のミラーやポータルは直結」の二重化が同時に入ります。npm 公式へはプロキシ経由が必要でも、チームが npmmirror など国内 CDN をデフォルトにしている場合、そのホストを同じ海外向けグループへねじ込むとかえって遅くなる典型があります。ミラー用ドメインは DIRECT に残すか、別の国内最適化ルールに寄せ、registry.npmjs.org だけ NPM_REGISTRY と明示分割するイメージです。

また、社内の Verdaccio や Artifactory へ向かうトラフィックを誤ってグローバルプロキシに流すと、ゼロトラストのポリシーと衝突して認証だけ成功／取得だけ失敗、といった症状にもなります。困っている URL が社内ホストなら、海外ドメイン行よりさらに上に社内サフィックスの DIRECT か専用グループを置くのが安全です。

YAML の骨格例（概念サンプル）

インデントとキー名は利用中のコア・GUI に合わせてください。ここでは NPM_REGISTRY を参照するイメージだけ示します。

proxy-groups:
  - name: NPM_REGISTRY
    type: select
    proxies:
      - 🇸🇬 長転送向き
      - 🇯🇵 安定
      - 🌐 自動

rules:
  - DOMAIN-SUFFIX,registry.npmjs.org,NPM_REGISTRY
  - DOMAIN-SUFFIX,npmjs.org,NPM_REGISTRY
  # GEOIP CN → DIRECT や社内 DIRECT をこのブロックの前後で意図どおりに

このあとに社内向け DOMAIN-SUFFIX、GEOIP,CN,DIRECT、最後に MATCH などを続けます。実ログに別ホストが出たら、このブロックの直上付近に追記すると追いやすいです。

TUN と CLI：ブラウザとターミナルで経路が分岐するとき

多くの IDE 統合ターミナルや node プロセスは、OS のシステムプロキシ設定だけでは追従しません。TUN モードで OS 全体の仮想スタックへ載せるか、環境変数 HTTP_PROXY／HTTPS_PROXY を明示するかは環境次第です。概要はTUN モード完全ガイドを参照してください。コンテナ内の npm ci が別問題になる場合はDocker Desktop と Clashの節と合わせ、デーモン側のプロキシ設定まで揃えます。

pnpm と yarn のレジストリまわり（環境変数と設定ファイル）

pnpm は .npmrc や pnpm config、CI では npm_config_registry などでレジストリが上書きされます。yarn（Classic）は .yarnrc、Berry 系は .yarnrc.yml の npmRegistryServer が要点です。ルールは正しくてもクライアントが別 URL を見ていると一生噛み合いません。npm config get registry、pnpm config get registry、yarn config get registry（サブコマンドは版差あり）で実効値を一度ずつ確認し、Clash 側のドメイン行を実効ホストに合わせてください。

DNS・fake-ip で「ルールは合っているのに別経路」になる理由

ブラウザだけ Secure DNS をオンにしたまま、CLI はシステム解決——といった名前解決の二重化があると、YAML 上のドメインルールと実接続の SNI がずれ、挙動が説明しにくくなります。fake-ip を使う構成では、評価はドメインルール側、実転送は別レイヤーで結ばれるイメージを頭に置き、変更後は OS とブラウザの DNS キャッシュを flush してから再試行してください。

実測チェックリスト（そのまま試せる順序）

  1. npm install --verbose などで再現し、ターミナルに出る fetch URL と Clash の接続一覧を突き合わせる。
  2. 該当ホストが NPM_REGISTRY（または同等）に載っているか、意図しない DIRECT／別グループになっていないか確認する。
  3. 同一プロファイルのまま出口ノードだけ変え、ETIMEDOUT の再現性が変わるか比較する（長ファイル転送に弱い出口の切り分け）。
  4. rm -rf node_modules とロックファイル方針に従ったキャッシュクリアのうえ、回線が安定する時間帯でもう一度 npm ci 相当を試す。
  5. 国内ミラーを併用する場合は、ミラー側ドメインが DIRECT のままか、意図どおりかをログで再確認する。

早見：エラーメッセージに出たホスト名をそのまま検索エンジンに貼らず、まず Clash のログで 同一セッション内の前行後行を読むと、リダイレクトや証明書エラーの別因に早く辿り着けます。

よくある誤解

一行ルールだけで安心してしまう

registry 行は必要最低限ですが、 tarball 側が別名になった瞬間に漏れます。verbose と接続ログは省略しないでください。

GLOBAL を触れば npm も直る

上流のグローバル出口を変えると他アプリまで巻き込みます。開発トラフィックだけ切りたいなら、ドメイン行＋専用グループの方が安全です。

会社プロキシと二重プロキシになる

企業ゲートウェイの内側でさらに Clash を挟むと、CONNECT の段階でタイムアウトが二重化することがあります。IT 部門のポリシーと衝突しない範囲で、どのレイヤーで止まっているかをログの HTTP ステータスから切り分けてください。

まとめ

npm install のような日常コマンドが通じない日は、開発全体の生産性を落とします。registry.npmjs.org を軸に、tarball 取得まで含めてClash 分流で出口を安定化し、pnpm／yarn の実レジストリ設定とログの実名を突き合わせれば、原因が「単一ノードの ping」では説明できないケースでも切り分けが速くなります。国内向け直結を保ちつつ海外レジストリだけをプロキシへ寄せる順序は、他の開発者向け記事と設計思想を共有できます。

一方で、一つの巨大 GUI に「開発者モード」や「パッケージ取得の分流プリセット」まで入り込ませたクローズド製品は、表向きは簡単でも裏側のルール順や DNS の説明が薄く、トラブル時にログの読みどころが自分で見つけにくいことがあります。オープンな Mihomo／Clash 系では、同じ ETIMEDOUT でもドメイン単位で原因を積み上げられるため、本稿の手順とチュートリアル一覧を組み合わせると再現性が出やすいです。ClashSource はクライアント別の読み順とドキュメントを揃えているので、registry 行を足したあとも迷子になりにくい構成になっています。まだ手元のクライアントを決めていない方はダウンロードページから環境に合うビルドを選び、本文のチェックリストどおりに一度フルインストールを試してください。Clash 互換クライアントを無料ダウンロードして npm 取得の安定性を確認するのが早道です。