npm installでERESOLVEが出たとき：AIの「--force」案を使う前に見る比較表

ERESOLVEは何が起きているのか

npm 7 以降は、peerDependencies（「このライブラリは、利用側が○○の特定バージョン範囲を入れている前提で動く」という宣言）を標準で自動インストールします。要求が衝突して依存の木を解決できない場合、ERESOLVE unable to resolve dependency tree で止まることがあります。npm公式の説明でも、peerDependencies の競合で解決に失敗する場合があるとされています。

次は説明用の例です。実際のログではなく、読み方を示すために作った架空のパッケージ名です。

npm error ERESOLVE unable to resolve dependency tree
npm error Found: react@18.3.1
npm error node_modules/react
npm error   react@"^18.0.0" from the root project
npm error Could not resolve dependency:
npm error peer react@"^17.0.0" from example-form-lib@2.1.0
npm error node_modules/example-form-lib
npm error   example-form-lib@"^2.1.0" from the root project

読む場所は3つです。

• Found：いま木に入っているもの（react 18）
• Could not resolve dependency / peer：要求しているもの（react 17 系を要求）
• from：要求している側（example-form-lib）

この例なら、react を下げるか、example-form-lib を react 18 対応の版に上げるか、別ライブラリに替えるのが「原因を直す」側の選択です。AIが追加したばかりのパッケージが原因なら、それを外すのが最も安く済みます。

選択肢ごとのリスク比較表

• A. バージョンを合わせる、やること：衝突元か相手を、互換のある版へ上げ下げする、直るもの：宣言の食い違い自体、残る問題：他の依存との再衝突、破壊的変更への対応、後で困る場面：メジャー更新に伴うコード修正が必要、戻しやすさ：package.json と lockfile、変更したコードを戻して再インストール
• B. 衝突元を外す・置き換える、やること：問題のパッケージを削除、または代替に変更、直るもの：衝突の原因、残る問題：機能の作り直し、後で困る場面：呼び出しコードの書き換え、戻しやすさ：コミット単位で戻せる
• C. overrides で版を固定、やること：ルートの package.json に依存先の解決版を書く、直るもの：解決の結果を明示できる、残る問題：peer の要求範囲を満たせるとは限らず、互換性の確認も必要、後で困る場面：固定を外し忘れ、更新が止まる、戻しやすさ：package.json と lockfile を戻して再インストール
• D. --legacy-peer-deps、やること：peerDependencies を無視して木を作る（npm 3〜6 と同様の扱い）、直るもの：peer の要求の衝突によるインストールの停止、残る問題：衝突は未解決。peer の不足や非互換が実行時に出る可能性、後で困る場面：同じ設定を使わない人や CI でエラーになる可能性、戻しやすさ：フラグを外し、package.json と lockfile を戻して再インストール
• E. --force、やること：ルートプロジェクトで競合する peerDependencies のインストールを許可する。効果は peer 以外にも及ぶ、直るもの：peer の競合によるインストールの停止を回避できる場合がある、残る問題：衝突は未解決。peer の要求範囲外の版で動く可能性、後で困る場面：動作が壊れても原因が見えにくい、戻しやすさ：package.json と lockfile を戻して再インストール

D と E は同じ働きではありません。npm公式の設定資料によると、D は peerDependencies を完全に無視し、E は競合する peer の許可に加え、Node.js・npm の要求バージョンに関する保護なども外します。

コマンドで付けたフラグは、その実行に対する指定です。特に D で作った lockfile は、npm ci の公式説明にあるとおり、CI でも同じフラグを指定しないとエラーになる可能性があります。プロジェクトの .npmrc に legacy-peer-deps=true と書いて共有するなら、理由を README やコミットメッセージに残してください。

C は使用中の npm が overrides に対応している場合に限ります。公式説明ではルートの package.json の指定だけが有効で、直接依存を上書きする場合は依存宣言と同じ指定にするなどの制限があります。単に固定すれば peer の競合が直るわけではありません。

使い分けの目安は次のとおりです。

• A か B が取れる → まずそちら
• 間接依存の解決版を調整でき、peer の要求範囲と動作の両方を確認できる → C を検討
• 原因調査の間、一時的に通したい → D か E を、退避した別ブランチだけで使う
• 本番ビルドの依存を決める案 → D と E は避け、A〜C に戻る

AIに渡す情報と依頼文

AIに「ERESOLVEを直して」とだけ送ると、--force を付ける案が返りがちです。次の情報を渡し、フラグ案を禁止し、リスクと戻し方まで出させます。

渡すもの：

• ERESOLVE のログ全体（Found から from まで）
• package.json の dependencies 系の部分
• node -v と npm -v の出力
• 追加・更新しようとしたパッケージ名
• 衝突パッケージの npm ls パッケージ名 の出力

渡さないもの：.npmrc のトークン、社内レジストリのURL、社外秘のパッケージ名。必要なら架空の名前に置き換えます。

npm install で次の ERESOLVE が出ました。
[ログを貼る]

package.json（dependencies と devDependencies）:
[貼る]

条件:
- --force と --legacy-peer-deps を使う案は、最後の選択肢としてだけ出してください。
- 先に、衝突しているパッケージ名・要求範囲・要求元を表で整理してください。
- 原因を直す案を2〜3個出し、各案で変わるファイル、必要なコード修正、リスクを書いてください。
- 各案の確認コマンドと、元に戻す手順も付けてください。
- 確実でない点は「未確認」と書いてください。

返ってきた案は、そのまま実行せず、次の退避手順を済ませてから試します。

lockfileを退避して元に戻す手順

以下は説明用の手順で、あなたのプロジェクトで実行する前提の雛形です。既存の package-lock.json があり、試行前の組み合わせで npm ci が通ることを前提にします。Git の手順では両ファイルが追跡済みであることも確認してください。Git を使っていない場合は、最初に下の cp 2行で退避し、復元時は .bak を使う手順へ進みます。コマンドの挙動は Git 公式ドキュメントの git restore、git stash、git diff の記述に沿っています。

1. 試す前に退避する

git status --short
git switch -c try-eresolve
cp package.json package.json.bak
cp package-lock.json package-lock.json.bak

git status で未コミットの変更が package.json や lockfile にあるなら、先にコミットするか、次のように対象を絞って stash します。

git stash push -- package.json package-lock.json

.bak ファイルは誤ってコミットしないようにしてください。

2. AIの案を試して、差分を見る

npm install
git diff --stat -- package.json package-lock.json
npm ls --all

見るのは次の点です。

• lockfile の変更量が想定より大きくないか（大きい場合は、依存の更新だけでなく形式やメタデータの変更も確認します）
• npm ls --all で、範囲外や不足を示す invalid・missing などの表示が出ていないか
• テストとビルドが通るか。D・E の案では、ここで初めて問題が出ることがあります

3. 元に戻す

Git で管理している場合、git restore は指定した元（--source）の内容でファイルを復元でき、--staged と --worktree を併用すると作業ツリーとインデックスの両方に効きます。次の手順は、試行中の変更をまだコミットしていない場合に使います。試行で変更したコードや .npmrc がある場合は、その変更も別途戻してください。

git restore --source=HEAD --staged --worktree -- package.json package-lock.json
rm -rf node_modules
npm ci

node_modules は通常 Git の管理外なので、lockfile を戻すだけでは中身が元に戻りません。再インストールが必要です。npm ci は lockfile を基準に入れ直し、package.json と lockfile の依存が食い違うと失敗します。この失敗は、戻し忘れの検知にも使えます。既存の node_modules は npm ci 自体が削除するため、上の手動削除は省略できます。元の lockfile の作成時に --legacy-peer-deps などを使っていた場合は、復元時にも同じ設定が必要です。

Git を使っていない場合は、.bak から戻します。

cp package.json.bak package.json
cp package-lock.json.bak package-lock.json
rm -rf node_modules
npm ci

Windows の PowerShell では rm -rf node_modules の代わりに Remove-Item -Recurse -Force node_modules を使います。stash で退避していた場合は、試行の変更を戻した後、git stash list で対象を確認して git stash pop で戻します。ほかの stash を追加した場合は対象を明示してください。pop は適用成功後に stash を消し、競合したときは消えません。競合があれば解消し、戻った package.json と lockfile に合わせて、必要な設定で再度 npm ci を実行してください。

AIの案を採用する前の確認項目

• フラグ付きの案なら、「なぜ衝突を直せないのか」の説明があるか
• 衝突元のパッケージの更新履歴や課題一覧に、新しい本体への対応状況が出ているか（AIの記憶ではなく、パッケージの公式ページで確認する）
• 変更が package.json、lockfile、コードのどこに及ぶのか、AIが列挙しているか
• 採用理由と、いつ見直すかをコミットメッセージに書けるか

最後の項目が書けない案は、いま通っても後で説明できなくなります。--force を使うなら、書けない部分を残したまま採用しない、という判断基準で十分です。