問題の概要
ワークフローを中断させる要因として、本番ビルド中の認証エラーほど厄介なものはありません。401 Unauthorized エラーは、レジストリが認証情報を認識できないことを示しています。npm クライアントが無効なトークンを送信しているか、あるいはトークンを全く送信していないかのどちらかです。
npm ERR! code E401
npm ERR! 401 Unauthorized - GET https://registry.npmjs.org/@scope/package - You must be logged in to install this package.
このエラーは通常、@mycompany/internal-tool のようなプライベートなスコープ付きパッケージを扱う際に見られます。しかし、ローカルセッションの期限が切れている場合や、.npmrc ファイルの設定が競合している場合には、パブリックパッケージでも発生することがあります。
ステップ1：現在のユーザー情報を確認する
まず、npm があなたを誰だと認識しているかを確認しましょう。ターミナルで次のコマンドを実行してください：
npm whoami
もしターミナルで 401 エラーが返されるか、「this command requires you to be logged in」と表示された場合は、セッションが切れています。間違ったユーザー名が表示された場合は、企業用アカウントではなく個人用アカウントにログインしている可能性があります。これは、開発者が複数のプロジェクトを掛け持ちしている際によくあるミスです。
ステップ2：セッションを更新する
最も確実な解決策は、ログインし直すことです。このプロセスにより古いトークンが破棄され、グローバル設定に新しいトークンが書き込まれます。多くのトークンは30日間操作がないと自動的に期限切れになるため、素早くリフレッシュするだけで問題が解決することがよくあります。
npm logout
npm login
GitHub Packages や Artifactory などのサードパーティ製レジストリを使用している場合は、レジストリフラグを含める必要があることに注意してください。例えば、GitHub の場合は次のように入力します：
npm login --registry=https://npm.pkg.github.com
ステップ3：.npmrc 設定を監査する
ログインしても解決しない場合は、設定ファイルが競合している可能性があります。npm は主に2つの場所で .npmrc ファイルを探します：ホームディレクトリとプロジェクトのルートディレクトリです。プロジェクトレベルの設定は、常に優先順位が高くなります。
グローバルな .npmrc
macOS または Linux では ~/.npmrc にあります。Windows ユーザーの場合は C:\Users\<Username>\.npmrc にあります。ファイルを開き、次のような行を探してください：
//registry.npmjs.org/:_authToken=npm_xxxxxxxxxxxx
重複がないか確認してください。同じレジストリに対して3つの異なるトークンがある場合、npm が誤ったトークンを送信している可能性があります。スコープ付きパッケージの場合は、マッピングが明示的であることを確認してください：
@mycompany:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=your-36-character-token
プロジェクトレベルの .npmrc
プロジェクトのルートにローカルの .npmrc がないか確認してください。このファイルが特定のレジストリを指しているにもかかわらず認証トークンが含まれていない場合、npm はグローバルの認証情報を無視します。その結果、グローバルでログインしていても 401 エラーが発生します。
ステップ4：CI/CD および自動化のエラーを修正する
GitHub Actions や GitLab CI などの自動化環境では、対話型のログインを処理できません。そのため、環境変数を使用する必要があります。よくある間違いは、いずれ期限が切れるトークンをハードコードしてしまうことです。
プロジェクトの .npmrc が環境から動的に読み取るように設定されていることを確認してください：
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
NPM_TOKEN が CI のシークレットに定義されていることを確認してください。変数が不足しているか空の場合、npm は文字通り "${NPM_TOKEN}" という文字列をサーバーに送信します。レジストリはこれを即座に拒否し、401 エラーを返します。
ステップ5：キャッシュをクリアして再インストールする
npm がローカルのメタデータキャッシュ内に未認証の状態を保持し続けることがあります。認証情報が正しいのにエラーが解消されない場合は、一度すべてをリセットしましょう。キャッシュを強制的にクリーンアップして、古いヘッダーを削除します：
npm cache clean --force
続けて、ローカルの生成物を削除してクリーンな状態にします：
rm -rf node_modules package-lock.json
npm install
修正を確認する方法
セットアップが正常であることを確認するために、次の3つのチェックを行ってください：
- ユーザー情報の確認：
npm whoamiを実行し、すぐにユーザー名が返されること。 - メタデータの確認：
npm view @scope/package-nameを試してください。バージョン番号を含む JSON オブジェクトが表示されれば、認証は成功しています。 - インストール：
npm installを実行します。CLI が「idealTree」フェーズを通過すれば、ハンドシェイクは完了です。
トラブルシューティングのヒント
- 2要素認証 (2FA)： npm CLI のバージョンが 9 以上であることを確認してください。古いバージョンでは 2FA のプロンプトが表示されず、サイレントに 401 エラーが発生することがあります。
- 企業用プロキシ： ファイアウォール内にいる場合、
npm config listのproxy設定によってAuthorizationヘッダーが削除されている可能性があります。ネットワークチームに確認してください。 - トークンのスコープ： 手動でトークンを生成する際は、「Read」権限があることを確認してください。「Publish only」に制限されたトークンは、通常の
npm install時に失敗します。