npm install が「ERESOLVE unable to resolve dependency tree」で失敗する

要約

npm ERR! ERESOLVE unable to resolve dependency tree は、依存パッケージ同士が要求する peerDependencies のバージョンが食い違っている ときに出る。
npm 7 以降は peer 依存を厳格に解決するため、npm 6 では警告で済んでいた不整合がインストールを止めるエラーになった。
正攻法は衝突元の依存を更新すること。
急ぐ場合は --legacy-peer-deps で一時回避する。

よくある原因

1. peer の衝突: パッケージ A が react@^17、パッケージ B が react@^18 を要求し両立できない
2. npm のバージョン差: npm 7 以降の厳格化により、以前は通っていた構成がエラーになる
3. 追従漏れ: 本体ライブラリをメジャー更新したのに、対応していない古いプラグインを併用している
4. lock 破損: 競合解決の途中で package-lock.json が中途半端な状態のまま残っている

解決策

1. 衝突元を特定する

npm install 2>&1 | grep -A3 peer
npm ls react

エラーメッセージの Could not resolve dependency と Conflicting peer dependency の行に、要求元のパッケージと要求バージョンが出る。
まずどのパッケージがどのバージョンを求めているかを確定させる。
解決アルゴリズムの詳細は npm install 公式ドキュメント を参照。

2. 原因パッケージを更新する

npm install plugin-foo@latest

古いプラグイン側が新しい peer に対応したバージョンを出していれば、それを入れるのが最も健全。
対応版が無ければ代替ライブラリを検討する。

3. 一時的に回避する

npm install --legacy-peer-deps

npm 6 相当の「peer は警告のみ」に戻す。
CI を止めたくないときの応急処置で、根本解決ではない点に注意する。--force は壊れたツリーをそのまま許容してしまうため避ける。

4. overrides で固定する

{
  "overrides": {
    "react": "18.3.1"
  }
}

package.json の overrides で依存ツリー全体のバージョンを強制的に揃える。
回避策より明示的で再現性も高い。
最後に rm -rf node_modules package-lock.json && npm install でツリーを作り直す。