npm install のタイムアウトは、Clash か npm かを先に切り分ける

Clash を起動しているのに npm install が進まない場合、原因は「Clash が動いていない」とは限りません。npm がプロキシを参照していない、Clash のルールが registry.npmjs.org を意図しない経路へ送っている、選択中のノードから npm registry までの通信が不安定、といった複数の段階で同じような待ち時間が発生します。エラー表示も ETIMEDOUT、ECONNRESET、ENOTFOUND、TLS 関連の警告などに分かれますが、メッセージだけを見て npm のキャッシュや証明書を変更すると、本来の原因を残したまま設定だけ複雑になることがあります。

まず、失敗する端末とシェルを特定してください。ブラウザは Clash のシステムプロキシを使っていても、ターミナルや IDE、WSL、コンテナは同じ設定を引き継ぐとは限りません。また、シェルで npm install が成功しても、IDE のターミナルが別の環境変数や別の Node.js を使っていれば、IDE から実行したときだけ失敗することがあります。Clash の接続ログを開き、失敗を再現した時刻に registry.npmjs.org や、ログに表示された tarball 配信先への接続が現れているか確認すると、通信が Clash に届いているかを切り分けやすくなります。

ここで確認するのは「Clash の画面に接続先が表示されたか」だけではありません。どのルールに一致し、どのプロキシグループを通り、選択したノードから接続が完了したかを見ます。接続がログにまったく現れないなら、npm がローカルの mixed-port に接続していない可能性があります。ログには出るものの失敗する場合は、ルール、出口ノード、DNS、または上流側の応答を次に調べます。

ℹ 最初の確認：ブラウザの表示だけで npm の疎通を判断せず、失敗したのと同じユーザー、同じシェル、同じネットワーク環境からテストしてください。エラー全文と発生時刻を控え、診断中に複数の設定を一度に変えないことが大切です。

Clash のプロキシモードとターミナルの接続先を確認する

Clash の Rule モードは、ルールに応じて通信先を振り分けます。Global モードは、構成によって異なりますが、通常は広い範囲の通信を選択中のプロキシグループへ送ります。まず現在のモードと選択中のグループを GUI で確認し、失敗中に対象ホストへの接続がログへ出るかを観察してください。原因の切り分け目的で一時的に Global モードへ変更する場合も、通信が改善するかだけを確かめたら元のモードへ戻し、最終的には必要な宛先だけを適切なルールで処理する構成にします。

ターミナル型のプログラムは、OS のシステムプロキシを自動利用しない場合があります。Clash がローカルで待ち受けるポート番号はクライアントや設定で異なるため、画面に表示されている HTTP または mixed-port を確認してください。以下の 7890 は説明用の例であり、自分の Clash の実際のポートに置き換えます。SOCKS 専用ポートを HTTP プロキシとして指定すると接続できないため、ポートの種類も合わせる必要があります。

npm が現在参照している設定は、次のコマンドで確認できます。意図しない社内プロキシや、過去に試した別のポートが残っていないかも見てください。出力に認証情報を含むプロキシ URL がある場合は、ログを共有する前にユーザー名やパスワードを必ず伏せます。 

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

npm の設定値が空でも、環境変数を通じてプロキシが指定されていることがあります。macOS／Linux では env | grep -i proxy、Windows PowerShell では Get-ChildItem Env:*proxy* を使い、HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、NO_PROXY の値を確認します。NO_PROXY に registry のドメインが含まれていると、ほかの通信はプロキシ経由でも npm の接続だけが除外される場合があります。一方、企業ネットワークでは管理者指定のプロキシや証明書設定が必要なこともあるため、許可なく組織の設定を上書きしないでください。

端末単位で試すなら、シェルの環境変数として正しい mixed-port を指定し、同じシェルから疎通を確認する方法が手軽です。macOS／Linux の例では次のように設定できます。Windows PowerShell では同じ変数名を $env:HTTPS_PROXY の形式で設定します。新しいターミナルを開くと値が引き継がれないこともあるため、設定と実行は同じセッション内で行ってください。 

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
npm ping --registry=https://registry.npmjs.org/

npm の設定に恒久的なプロキシを保存する方法もありますが、Clash のポートを変更したときに古い値だけが残る原因になります。環境変数で成功するかを先に試し、恒久設定が必要な場合にだけ npm config set を検討してください。テスト後に不要な値を残さないことも重要です。パソコン上の npm 設定を変更しても、Docker コンテナやリモートサーバー内で実行される npm にその設定が自動で適用されるわけではありません。

コマンドと Clash のログで段階的に検証する

ここでは「プロキシが待ち受けているか」「npm registry へ到達できるか」「個別のパッケージ取得だけ失敗するか」の順に、変更箇所を一つずつ絞ります。テスト中は Clash のログ画面を開き、各コマンドを実行した直後の接続先とルールを確認してください。表示されたポリシー名やノード名は手元の構成で異なります。以下は一般的な確認例なので、ポート番号、registry、パッケージ名は実環境に合わせて読み替えます。

  1. Clash の待ち受けポートを確認する。GUI の設定で HTTP／mixed-port が有効か、表示された番号が npm の環境変数や npm 設定と一致するかを見ます。Clash が停止中、またはポート番号が違うと、ターミナルからの接続は失敗します。

  2. registry の応答を確認する。まず npm ping --registry=https://registry.npmjs.org/ を実行します。続けて、必要なら curl -I --proxy http://127.0.0.1:7890 https://registry.npmjs.org/ を試し、HTTP 応答の有無を見ます。curl のオプションやビルドによってプロキシ指定の挙動は異なるため、接続先とエラーも併せて確認してください。

  3. npm のメタデータ取得を分けて試す。対象パッケージが決まっている場合は npm view パッケージ名 version を実行します。これが成功してインストールだけ止まるなら、依存パッケージの tarball、ロックファイルに記録された別 registry、または一部の CDN など、取得の次の段階を疑います。

  4. ログを短い時間幅で照合する。最後に npm install --verbose を実行し、npm の出力と Clash の接続ログを時刻で照らし合わせます。特定のホストへの接続が DIRECT になっているか、意図したプロキシグループを通っているか、失敗が DNS 解決前か TLS 接続後かを記録します。Verbose ログには環境によってパスや設定情報が含まれるため、公開する場合は内容を確認してください。

あるテストだけ成功して別のテストが失敗する場合、その差が重要な手掛かりになります。たとえば curl は成功するのに npm の ping が失敗するなら、npm 固有のプロキシ設定、実行中の Node.js／npm の違い、または npm の設定ファイルを見直します。ping は成功して特定のパッケージだけ止まるなら、npm install --verbose に現れる取得先を調べ、registry 本体と tarball のホストを同一視しないようにします。社内ミラーを利用している場合は、ロックファイルやプロジェクト設定が公式 registry とミラーを混在させていないかも確認してください。

ETIMEDOUT は応答が規定時間内に返らない状態、ECONNRESET は接続が途中で切られた状態として手掛かりになります。ENOTFOUND が出る場合は DNS やホスト名、DNS フィルタリングを重点的に調べます。ただし、エラー名だけで原因を断定するのは避けてください。同じエラーでも、プロキシの誤指定、上流ノード、DNS 設定、ネットワーク側の制限などが関与し得ます。複数の設定を同時に変更すると、どの変更が効いたのか判断できなくなります。

ルール・ノード・registry を確認し、安易な回避策を避ける

Rule モードで接続ログに registry.npmjs.org が現れるなら、その接続がどのルールに最初に一致したかを確認します。Clash のルールは通常、上から順に評価されるため、広い DOMAIN-SUFFIX、地域判定、広告・プライバシー向けルールなどが先に一致すると、後から追加したルールまで到達しないことがあります。必要な場合は、実際にログで観測したホストに対応するルールを、広いルールより前へ置きます。設定例を流用するのではなく、自分のプロファイルに存在するポリシー名とログの結果を使ってください。

npm registry を特定のプロキシグループへ送るなら、設定例としては DOMAIN-SUFFIX,registry.npmjs.org,利用するグループ名 のような形になります。これは考え方を示す例で、グループ名をそのまま貼り付けても動くとは限りません。ルールを追加して再読み込みした後、接続ログで一致ルールと実際の出口が変わったかを確認します。設定を購読プロファイルへ直接書き込むと更新時に消えることがあるため、クライアントが提供するオーバーライドやローカル設定の仕組みを使うか、編集前にバックアップしてください。

ノードを切り替えるときは、レイテンシ表示だけで判断せず、同じ npm コマンドを使って比較します。遅延測定が短くても、registry への TLS 接続や大きな tarball のダウンロードが安定するとは限りません。ひとつのノードでのみ成功するなら、ノードの経路品質や出口側の制限を疑う材料になります。どのノードでも同じホストだけ失敗する場合は、ルール、プロキシ設定、DNS、ローカルの証明書設定など、共通する部分を優先して調べます。

npm config get registry が想定外の URL を返した場合は、ユーザー設定だけでなくプロジェクト内の .npmrc や組織の設定も確認してください。地域ミラーや社内 registry は、それぞれ許可されたネットワークや認証方法が異なります。取得先を変更する前に、組織やプロジェクトの方針と、ロックファイルに保存された resolved URL を確認しましょう。無関係なミラーへ一時的に切り替えると、メタデータは取得できても tarball が別の場所から取得され、症状が変わらないことがあります。

⚠ 避けたい対処：strict-ssl=false にして TLS 検証を無効化したり、原因を調べずにロックファイルや npm キャッシュを削除したりするのは推奨できません。証明書エラーが明示される場合は、企業の TLS 検査、信頼済み CA、Node.js の証明書設定を管理者の案内に沿って確認してください。認証情報を含む .npmrc を共有するのも避けます。

再発を減らすための設定整理

復旧後は、成功した条件を短く記録しておくと次回の調査が容易になります。たとえば、使用した npm registry、Clash のモード、mixed-port、対象ホストに一致したルール、選択したグループ、成功したテストコマンドを残します。ノード名や接続先のログを外部へ共有するときは、購読 URL、認証情報、社内ドメイン、IP アドレスなどが含まれていないか必ず確認してください。ログを記録する目的は構成の再現であり、秘密情報を保存することではありません。

また、プロキシ設定はどこで管理するかを決めます。Clash 側のルールで端末の通信を処理するのか、npm の設定や環境変数で明示的にローカルプロキシへ送るのかを整理し、同じ接続に複数の古い設定を重ねないようにします。開発用のシェルだけに環境変数を設定すれば、ブラウザやほかのアプリへの影響を抑えられます。一方、CI、Docker、WSL、SSH 先はそれぞれ実行環境が異なるため、必要な場所で個別にプロキシを設定し、Clash が稼働するホストへ到達できるかを確かめます。

npm のキャッシュ削除は、プロキシ疎通が正常で、特定のキャッシュ破損を示すエラーがあるときに限って検討するのが安全です。タイムアウトのたびに npm cache clean --force を実行しても、ネットワーク経路が直るわけではありません。反対に、同じノード、同じポート、同じ registry で npm ping と対象パッケージの取得を再現できれば、原因の範囲はかなり狭まります。変更は一項目ずつ行い、成功したら余分な一時設定を戻してください。

OS のシステムプロキシだけに依存する一般的な GUI クライアントでは、ブラウザは通るのに npm や IDE のターミナルだけが直結する状況を見落としやすく、手作業で複数の設定を追う負担もあります。Clash V.CORE なら、プロファイル、モード、接続ログをまとめて確認しながら、npm の通信先に合わせたルールやノードを整理できます。クライアントごとに異なる設定画面を行き来するより、今回の切り分け手順を継続して使える環境を整えたい方は、Clash V.CORE のダウンロードページから対応するバージョンを確認してください。