npmのレジストリがブロックされた場合のプロキシ設定

```html

npmレジストリが利用できない - プロジェクトのビルドが停止しました。企業ネットワーク、アクセス制限のある地域、または厳格なファイアウォールを通じて作業している開発者にとっては、よくある状況です。このガイドでは、ミラーへの切り替えから.npmrcでのプロキシの微調整まで、すべての実行可能な方法を検討します - npm installが再びエラーなしで動作するようにします。

なぜnpmレジストリがブロックされ、何が起こるのか

公式のnpmレジストリはhttps://registry.npmjs.orgにあります。これはグローバルCDNですが、いくつかの理由で利用できなくなることがあります。それぞれに異なるアプローチが必要です。

レジストリが利用できない主な理由

企業ファイアウォール - 会社が外部リポジトリへの直接リクエストをブロックし、内部プロキシサーバーを介してのみトラフィックを許可します。これは銀行、政府機関、大手IT企業での標準的な慣行です。
地理的ブロックまたは地域制限 - 一部の国や地域では、npmjs.orgへのアクセスがインターネットプロバイダーまたは政府のファイアウォールのレベルで制限されています。
インターネットへの直接アクセスがないオフィスネットワーク - 隔離されたネットワークセグメントの作業マシンは外部リソースへの直接アクセスがなく、すべてのトラフィックが企業ゲートウェイを通過します。
強制プロキシのVPNトンネル - 企業VPNがすべてのトラフィックをリダイレクトし、npmがレジストリに直接アクセスできません。
SSL検査の問題 - 企業プロキシがHTTPSトラフィックを傍受し、証明書を置き換えるため、SELF_SIGNED_CERT_IN_CHAINやUNABLE_TO_VERIFY_LEAF_SIGNATUREのようなエラーが発生します。

ブロックされたレジストリでの一般的なエラー

npm ERR! code ECONNREFUSED
npm ERR! errno ECONNREFUSED
npm ERR! network request to https://registry.npmjs.org/react failed

npm ERR! code ETIMEDOUT
npm ERR! network This is a problem related to network connectivity.

npm ERR! code CERT_HAS_EXPIRED
npm ERR! code SELF_SIGNED_CERT_IN_CHAIN

これらのエラーコードのそれぞれは異なる問題を示しています：ECONNREFUSED - 接続がファイアウォールによって拒否されました、ETIMEDOUT - リクエストが応答なしでブロックされています、証明書エラー - SSL検査の問題です。原因を理解することで、解決策の範囲がすぐに絞り込まれます。

npmレジストリのミラー：プロキシなしでの迅速な回避

ブロックを回避する最も簡単な方法は、npmを代替のレジストリミラーに切り替えることです。ミラーは公式レジストリと同じパッケージを含んでいますが、異なるサーバーやドメインにあります。これは、registry.npmjs.orgドメインがブロックされている場合に機能しますが、すべてのHTTPSトラフィックがブロックされているわけではありません。

ミラー	URL	特徴
Taobao / npmmirror	`https://registry.npmmirror.com`	10分ごとに同期、アジアからの良好な速度
Yarn Berryミラー	`https://registry.yarnpkg.com`	Yarnチームによってサポートされており、npmクライアントと互換性があります
Verdaccio (自己ホスト)	`http://localhost:4873`	キャッシュ機能付きの独自のレジストリ、隔離されたネットワークで動作します
Nexusリポジトリ	`http://nexus.company.local/npm`	企業向けソリューション、パッケージをプロキシおよびキャッシュします
JFrog Artifactory	`https://artifactory.company.com/npm`	エンタープライズレベル、依存関係の監査、アクセス制御

レジストリの切り替え方法

コマンドごとの切り替え（グローバル設定を変更せずに）：

# 代替レジストリを介しての一時的なインストール
npm install react --registry https://registry.npmmirror.com

# 現在のユーザー用にグローバルに設定
npm config set registry https://registry.npmmirror.com

# 現在のレジストリを確認
npm config get registry

# 公式レジストリに戻す
npm config set registry https://registry.npmjs.org

重要な点：プロジェクト内でコマンドを使用してミラーに切り替える場合は、リポジトリのルートにある.npmrcファイルに固定するのが良いでしょう。そうすれば、チームの全メンバーがプロジェクトをクローンする際に自動的に正しい設定を取得できます。

# プロジェクトのルートにある.npmrc
registry=https://registry.npmmirror.com

.npmrcを介したプロキシ設定：完全な構文

ミラーが役に立たない場合（たとえば、すべての外部HTTPSトラフィックがブロックされている場合）、npmにプロキシサーバーのアドレスを明示的に指定する必要があります。.npmrcファイルはnpmの主要な設定ファイルであり、プロキシ設定が保存されます。

.npmrcファイルの場所

npmは、複数の場所で設定を探します - 優先順位の順に（高いものから低いものへ）：

プロジェクト固有 - /path/to/project/.npmrc - このプロジェクトにのみ適用されます
ユーザー固有 - ~/.npmrc - システムの現在のユーザーに適用されます
グローバル - $PREFIX/etc/npmrc - npmの全インストールに適用されます
組み込み - /path/to/npm/npmrc - npm自体のデフォルト設定

.npmrcでのプロキシ設定の構文

# HTTPトラフィック用のプロキシ
proxy=http://proxy.example.com:8080

# HTTPSトラフィック用のプロキシ（レジストリへのほとんどのリクエストで使用されます）
https-proxy=http://proxy.example.com:8080

# 認証付きプロキシ（URLにログイン:パスワード）
proxy=http://username:[email protected]:8080
https-proxy=http://username:[email protected]:8080

# 例外 - プロキシを回避するアドレス
noproxy=localhost,127.0.0.1,internal.company.com

⚠️ HTTPSプロキシに関する重要な注意事項

注意してください：https-proxyパラメータは、npmがHTTPSリクエストを行うために使用するプロキシサーバーのアドレスを示します。プロキシのアドレスはhttp://で始まることがあります - これは正常です。ほとんどの企業プロキシはHTTP接続を受け入れますが、CONNECTメソッドを介してHTTPSをトンネリングすることができます。

npm configコマンドを介したプロキシの設定

ファイルを手動で編集する代わりに、npm config setコマンドを使用できます。これにより、設定がユーザーの~/.npmrcに自動的に書き込まれます：

# プロキシを設定
npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080

# 現在のプロキシ設定を確認
npm config get proxy
npm config get https-proxy

# プロキシ設定を削除（直接接続に戻す）
npm config delete proxy
npm config delete https-proxy

# npmの全設定を表示
npm config list

npmの環境変数を介したプロキシ

npmは、プロキシ用の標準的なシステム環境変数を自動的に読み取ります。これは、CI/CDパイプライン、Dockerコンテナ、および設定がファイルではなく環境レベルで指定されるシステムで便利です。

標準環境変数

# Linux / macOS - 現在のセッションで設定
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1

# 小文字のバリエーション（npmは両方を理解します）
export http_proxy=http://proxy.example.com:8080
export https_proxy=http://proxy.example.com:8080

# Windows (コマンドプロンプト)
set HTTP_PROXY=http://proxy.example.com:8080
set HTTPS_PROXY=http://proxy.example.com:8080

# Windows (PowerShell)
$env:HTTP_PROXY = "http://proxy.example.com:8080"
$env:HTTPS_PROXY = "http://proxy.example.com:8080"

npmの設定優先順位

npmは、プロキシを決定する際に次の優先順位を使用します（高いものから低いものへ）：

コマンドラインフラグ：--proxy http://...
npm_config_プレフィックス付きの環境変数：たとえば、npm_config_proxy
プロジェクトの.npmrc
ユーザーの~/.npmrc
グローバル$PREFIX/etc/npmrc
標準環境変数HTTP_PROXY / HTTPS_PROXY

.npmrcにプロキシが設定されている場合でも、環境変数が別のアドレスを指している場合は、.npmrcが優先されます。これはCI/CDシステムでの混乱の一般的な原因です。

CI/CDでの設定（GitHub Actions、GitLab CI）

# GitHub Actions - jobまたはstepのenvセクションに追加
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: http://proxy.example.com:8080
      HTTPS_PROXY: http://proxy.example.com:8080
      NO_PROXY: localhost,127.0.0.1
    steps:
      - uses: actions/checkout@v3
      - run: npm install

# GitLab CI - プロジェクトの変数または.gitlab-ci.ymlに
variables:
  HTTP_PROXY: "http://proxy.example.com:8080"
  HTTPS_PROXY: "http://proxy.example.com:8080"

認証とSSL検査を伴う企業プロキシ

企業プロキシサーバーは最も複雑なケースです。単にトラフィックをリダイレクトするだけでなく、認証を要求し、しばしばSSL検査（HTTPSトラフィックの傍受と復号化）を実行します。これにより、npmがデフォルトで対処できない特定の証明書エラーが発生します。

NTLM/Basic認証付きプロキシ

企業プロキシがログインとパスワード（Basic Auth）を要求する場合、それらをURLに直接渡すことができます。しかし、NTLM認証（Windowsドメイン）の場合は、npmがNTLMをネイティブでサポートしていないため、より複雑です。この場合は中間ツールを使用します。

# Basic Auth - URLにログインとパスワード
npm config set proxy http://user:[email protected]:8080
npm config set https-proxy http://user:[email protected]:8080

# パスワードに特殊文字が含まれている場合は、URLエンコードする必要があります
# @ → %40, # → %23, : → %3A
# 例：パスワード "p@ss#word" → "p%40ss%23word"
npm config set proxy http://user:p%40ss%[email protected]:8080

NTLM認証には、cntlmユーティリティを使用します - これはローカルで実行され、通常のHTTPリクエストを受け取り、企業プロキシとのNTLMハンドシェイクを実行します。npmにとっては、認証なしの通常のプロキシのように見えます：

# cntlmを設定した後、localhost:3128でリッスンします
npm config set proxy http://localhost:3128
npm config set https-proxy http://localhost:3128

SSL検査の問題を解決する

SSL検査を伴う企業プロキシは、サイトの証明書を企業の証明書に置き換えます。npmは信頼の連鎖を確認し、そのような証明書を拒否します。以下の3つのアプローチがあります：

方法1（推奨）：企業CA証明書を信頼されたものに追加する

# IT部門から企業証明書を取得する（.crtまたは.pemファイル）
# npmの設定で指定する
npm config set cafile /path/to/corporate-ca.crt

# または、cafileを介して複数の証明書を追加する
# 複数のCAを1つのPEMファイルにまとめることができます

方法2（一時的で安全でない）：SSL検証を無効にする

# 診断用の一時的な解決策としてのみ使用してください！
npm config set strict-ssl false

# または、1つのコマンドのために
npm install --legacy-peer-deps --no-strict-ssl

⚠️ セキュリティ警告

strict-ssl falseパラメータは、SSL証明書の検証を完全に無効にします。これにより、MITM攻撃に対して接続が脆弱になります。この方法は診断用にのみ使用し、プロダクション環境や常時使用しないでください。正しい解決策は、cafileを介して企業CA証明書を追加することです。

npmのためのSOCKS5プロキシ：ヘルパー・ユーティリティを介した設定

npmはネイティブでHTTP/HTTPSプロキシのみをサポートしています。SOCKS5プロキシ（たとえば、レジデンシャルプロキシのプロバイダーからのもの）がある場合、npmの設定ファイルに直接指定することはできません。中間層が必要です - npmからのHTTPリクエストを受け取り、それをSOCKS5経由でリダイレクトするユーティリティです。

方法1：proxychains（Linux/macOS）

# proxychainsのインストール
# Ubuntu/Debian:
sudo apt-get install proxychains4

# macOS:
brew install proxychains-ng

# /etc/proxychains4.confの設定
[ProxyList]
socks5 proxy.example.com 1080 username password

# proxychainsを介してnpmを実行
proxychains4 npm install

方法2：ローカルHTTPからSOCKS5への変換ツール

privoxyまたはpolipoユーティリティは、SOCKS5経由でトラフィックをトンネリングするローカルHTTPプロキシを作成します。起動後、npmはlocalhostで通常のHTTPプロキシを認識します：

# privoxyのインストール
sudo apt-get install privoxy  # Ubuntu/Debian
brew install privoxy          # macOS

# /etc/privoxy/configに追加：
forward-socks5 / proxy.example.com:1080 .

# Privoxyはデフォルトでlocalhost:8118でリッスンします
# npmにこのアドレスを使用するように指定：
npm config set proxy http://localhost:8118
npm config set https-proxy http://localhost:8118

方法3：SOCKS5プロキシとしてのSSHトンネル

インターネットにアクセスできるリモートサーバーにアクセスできる場合、SSH SOCKS5トンネルを作成し、npmのトラフィックをそれを通じて送信できます。これは、アクセス制限のある企業ネットワークで作業する際に特に便利です：

# ローカルポート1080でSSH SOCKS5トンネルを作成
ssh -D 1080 -f -C -q -N [email protected]

# 次にprivoxyまたはproxychainsを使用してHTTPに変換
# または、環境変数を介して直接（Node.jsは一部のライブラリを介してSOCKSを理解します）

# テストとしてcurlを使用する代替手段：
curl --socks5 localhost:1080 https://registry.npmjs.org/react/latest

プロキシの代替としての独自のプライベートレジストリ

企業や隔離された環境では、各開発者のためにプロキシを設定するのではなく、ネットワーク内に独自のnpmレジストリを展開することが最良の解決策であることがよくあります。このようなレジストリは、公開のnpmjs.orgからパッケージをキャッシュし、内部ネットワークから提供します。開発者はインターネットへのアクセスを必要とせず、すべてがローカルレジストリを介して機能します。

Verdaccio：10分での迅速なスタート

Verdaccioは、プロキシとキャッシュをサポートするオープンソースのnpmレジストリです。npmパッケージとしてインストールされ、独立したサービスとして動作します：

# Verdaccioをグローバルにインストール
npm install -g verdaccio

# 起動（デフォルトでhttp://localhost:4873でリッスン）
verdaccio

# ローカルレジストリを使用するようにnpmを設定
npm config set registry http://localhost:4873

# ローカルレジストリにパッケージを公開
npm adduser --registry http://localhost:4873
npm publish --registry http://localhost:4873

Verdaccioの設定（~/.config/verdaccio/config.yaml）では、npmjs.orgからパッケージをダウンロードするための外部プロキシを介したプロキシ設定が可能です：

# config.yaml - プロキシを持つuplinkの設定
uplinks:
  npmjs:
    url: https://registry.npmjs.org/
    # Verdaccio自体がプロキシの背後にある場合：
    agent_options:
      http_proxy: http://proxy.company.com:8080
      https_proxy: http://proxy.company.com:8080
      no_proxy: localhost,127.0.0.1

packages:
  '@*/*':
    access: $all
    publish: $authenticated
    proxy: npmjs
  '**':
    access: $all
    publish: $authenticated
    proxy: npmjs

隔離環境のためのソリューションの比較

ソリューション	難易度	キャッシュ	適している
ミラー (npmmirror)	低い	いいえ	地理的ブロック、npmjs.orgへの遅いアクセス
.npmrcのHTTPプロキシ	低い	いいえ	企業ネットワークでのHTTPプロキシ
SOCKS5 + proxychains	中程度	いいえ	レジデンシャル/モバイルプロキシ、VPN
Verdaccio	中程度	はい	チーム、隔離されたネットワーク、CI/CD
Nexus / Artifactory	高い	はい	エンタープライズ、依存関係の監査

一般的なエラーの診断と修正

正しいプロキシ設定を行った後でも、問題が発生することがあります。以下は、診断のための体系的なアプローチと、最も一般的なエラーのリストとその解決策です。

ステップ1：現在のnpm設定を確認

# すべてのnpm設定を表示（プロキシを含む）
npm config list

# プロキシ設定のみを表示
npm config get proxy
npm config get https-proxy
npm config get registry
npm config get strict-ssl

# 診断のために詳細な出力を有効にする
npm install react --verbose
npm install react --loglevel verbose

ステップ2：レジストリへの直接アクセスを確認

# curlを介してレジストリの可用性を確認
curl -v https://registry.npmjs.org/react/latest

# プロキシを介して確認
curl -v --proxy http://proxy.example.com:8080 https://registry.npmjs.org/react/latest

# pingを確認（HTTPSには常に有益ではありません）
ping registry.npmjs.org

# DNS解決を確認
nslookup registry.npmjs.org

一般的なエラーとその解決策

エラー	原因	解決策
ECONNREFUSED	プロキシが接続を受け入れないか、ポートが無効です	プロキシのアドレスとポート、プロキシサーバーの可用性を確認してください
ETIMEDOUT	リクエストがファイアウォールによって応答なしでブロックされています	プロキシを設定するか、ミラーに切り替えてください
SELF_SIGNED_CERT	企業プロキシのSSL検査	`cafile`を介して企業CAを追加してください
407 Proxy Auth	プロキシが認証を要求しています	プロキシのURLにログイン：パスワードを追加してください
ENOTFOUND	DNSがレジストリまたはプロキシの名前を解決できません	DNS設定を確認し、名前の代わりにIPを使用してください
E403 Forbidden	プロキシがnpmjs.orgへのリクエストをブロックしています	ミラーを使用するか、ネットワーク管理者に連絡してください

すべてのプロキシ設定をリセット

# ユーザー設定からすべてのプロキシ設定を削除
npm config delete proxy
npm config delete https-proxy
npm config delete noproxy

# レジストリを公式にリセット
npm config set registry https://registry.npmjs.org

# strict-sslを元に戻す（無効にした場合）
npm config set strict-ssl true

# 最終的な設定を確認
npm config list

ブロックされたレジストリでのpnpmとYarnの使用

代替のパッケージマネージャーを使用している場合、プロキシの設定は似ていますが、構文が少し異なります：

# pnpm - npmと同じ.npmrcを使用
# 追加でpnpm configを介して設定できます：
pnpm config set proxy http://proxy.example.com:8080
pnpm config set https-proxy http://proxy.example.com:8080
pnpm config set registry https://registry.npmmirror.com

# Yarn Classic (v1) - 独自の.yarnrcファイル
yarn config set proxy http://proxy.example.com:8080
yarn config set https-proxy http://proxy.example.com:8080
yarn config set registry https://registry.npmmirror.com

# Yarn Berry (v2+) - .yarnrc.ymlファイル
# httpProxy: "http://proxy.example.com:8080"
# httpsProxy: "http://proxy.example.com:8080"
# npmRegistryServer: "https://registry.npmmirror.com"

特定のスコープパッケージのためのプロキシ設定

時には、異なるパッケージに異なるレジストリを使用する必要があります：たとえば、公開パッケージは公式のnpmjs.orgから取得し、企業の@company/*は内部のNexusから取得します。これは、.npmrcでスコープ固有のレジストリを介して設定できます：

# .npmrc - 異なるスコープに対する異なるレジストリ
registry=https://registry.npmjs.org

# 企業パッケージ@companyは内部のNexusを介して
@company:registry=http://nexus.company.local/repository/npm-hosted/

# @myorgパッケージはVerdaccioを介して
@myorg:registry=http://localhost:4873/

# 特定のレジストリのための認証
//nexus.company.local/repository/npm-hosted/:_authToken=YOUR_TOKEN_HERE

結論と最終的な推奨事項

npmのプロキシ設定は、特に企業環境や制限されたネットワークでの開発において重要です。適切な設定を行うことで、開発者はスムーズに作業を進めることができます。ここで紹介した手法を参考にし、必要に応じて適切な方法を選択してください。

npmのレジストリがブロックされた場合のプロキシ設定方法：ミラー、.npmrc、制限の回避