何が起きているのか
npm install を実行すると、こんなエラーが出る：
npm ERR! code EINTEGRITY
npm ERR! Verification failed while extracting lodash@4.17.21:
npm ERR! sha512-... integrity checksum failed when using sha512: wanted sha512-ABC... but got sha512-XYZ...
npm はパッケージをダウンロードした後、そのチェックサムを package-lock.json に保存されている値と照合する。値が一致しない場合、npm は即座に停止する——ファイルが転送中に破損したのか、改ざんされたのか、それともキャッシュの古いデータが当たったのかを判断できないからだ。そのため、処理を中断する。
根本原因
- npm キャッシュの破損——ほとんどの場合、これが原因だ。ディスクエラー、中断されたダウンロード、または書き込み中にウイルス対策ソフトがスキャンしたことで、キャッシュされた tarball が壊れてしまう。
- 古い
package-lock.json——ロックファイルに古いパッケージバージョンのハッシュが残っており、現在レジストリが配信しているものと一致しない。 - 不完全なダウンロード——ダウンロード中にネットワークが切断された。npm が壊れたファイルをキャッシュしてしまい、その後のインストールごとに使い回してしまう。
- レジストリの不一致——公開の npmjs.org レジストリとプライベートの Nexus や Artifactory ミラーを切り替えた。レジストリが異なると、ハッシュは単純に一致しない。
- 残留した
node_modules——以前のパッケージマネージャー実行による古いインストール成果物が、現在の解決と競合している。
手順ごとの修正方法
ステップ 1 — npm キャッシュをクリアする
まずここから始めよう。約 90% のケースでこれだけで解決する。
npm は Linux/macOS では ~/.npm 以下に、Windows では %APPDATA%\npm-cache にダウンロードした tarball をキャッシュする。破損したエントリが 1 つあるだけで、削除するまですべてのインストールに悪影響を及ぼす。
npm cache clean --force
次に、キャッシュが実際に空になったことを確認する：
npm cache verify
正常にクリアされると、次のように表示される：
Cache verified and compressed (~/.npm/_cacache):
Content verified: 0 (0 bytes)
Index entries: 0
Finished in 0.234s
もう一度 npm install を試してみよう。うまくいけば完了だ。
ステップ 2 — node_modules とロックファイルを削除する
キャッシュをクリアしてもエラーが続く場合は、ローカルのインストール状態を完全に消去しよう。
# Linux / macOS
rm -rf node_modules package-lock.json
# Windows (PowerShell)
Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
その後、新たにインストールし直す：
npm install
npm がレジストリから直接すべてを取得し、正しいハッシュを持つ新しい package-lock.json を書き出す。古いデータも不一致もない。
ステップ 3 — --prefer-online でインストールする
チームがロックファイルをコミットしているなど、ロックファイルを保持する必要がある場合は、何も削除せずにキャッシュをスキップしよう：
npm install --prefer-online
これにより、npm はローカルキャッシュではなく常にレジストリから取得するようになる。古い npm バージョンへのフォールバックとしては：
npm install --cache /tmp/empty-cache
ステップ 4 — レジストリを確認する
最近、社内レジストリと公開レジストリを切り替えた場合、ハッシュの不一致は想定内だ——レジストリごとにパッケージの署名方法が異なる。
npm config get registry
意図しない場所を指している場合は、リセットしよう：
npm config set registry https://registry.npmjs.org/
社内レジストリが必要な場合は、インフラチームに相談しよう。そのミラーに正しいインテグリティハッシュを公開してもらう必要がある。
ステップ 5 — 問題のあるパッケージだけを対象にする
エラーメッセージには問題のあるパッケージ名が表示される。1 つだけなら、すべてを削除する必要はない——そのパッケージだけを再インストールしよう：
npm install lodash@4.17.21 --prefer-online
またはアンインストールしてクリーンに追加し直す：
npm uninstall lodash
npm install lodash
ステップ 6 — npm 自体をアップデートする
npm のバージョン 8 未満にはインテグリティチェックに既知のバグがあった。まずバージョンを確認しよう：
npm --version
8 未満の場合はアップデートしよう：
npm install -g npm@latest
修正の確認
クリーンインストールを実行する：
npm install
エラーなしに added 847 packages（実際の数は環境による）と表示されれば問題ない。依存関係ツリーがきれいかどうかも確認しよう：
npm ls --depth=0
警告もなく、不足しているパッケージもなければ完了だ。
手動ハッシュ検証（オプション）
npm が実際に確認しているハッシュを確かめたい場合は、package-lock.json を開いて該当パッケージのエントリを探そう：
"lodash": {
"version": "4.17.21",
"resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz",
"integrity": "sha512-v2kDE..."
}
この integrity フィールドは base64 エンコードされた SHA-512 ハッシュだ。tarball を手動で検証したい場合、ToolCraft の Hash Generator はブラウザ上で MD5、SHA-256、SHA-512 ハッシュを計算できる——データが外部に送信されることはない。社内アーティファクトミラーをデバッグしていて、CLI ツールを使わずにハッシュを比較したいときに重宝する。
予防策
- 常に
package-lock.jsonをコミットする——すべての開発者と CI の実行で、検証済みハッシュを使って全く同じバージョンがインストールされる。 - CI では
npm installの代わりにnpm ciを使う。より厳格で、ロックファイルが存在しないか同期が取れていない場合はエラーになり、常にゼロからインストールする。予期しない動作が起きない。 - パッケージマネージャーを混在させない——同じプロジェクトで
yarnとnpmを交互に実行すると、ロックファイルがすぐに壊れる。 - CI のプリフライトに
npm cache verifyを追加する——パイプラインがビルド間で npm キャッシュをキャッシュしている場合、簡単な検証ステップを追加することで、インストールが壊れる前に破損を検出できる。
クイックリファレンス
# 修正 1: キャッシュをクリアする（まずこれを試す——90% のケースで解決）
npm cache clean --force && npm install
# 修正 2: 完全クリーン再インストール
rm -rf node_modules package-lock.json && npm install
# 修正 3: キャッシュをスキップし、レジストリから直接取得する
npm install --prefer-online
# 修正 4: 公開レジストリにリセットする
npm config set registry https://registry.npmjs.org/ && npm install
# 修正 5: npm をアップデートする
npm install -g npm@latest