ERESOLVE unable to resolve dependency tree の原因と解決策

概要

ERESOLVE unable to resolve dependency tree は、npm 7以降でパッケージの依存関係に競合がある場合に発生するエラーです。異なるパッケージが同じ依存関係の異なるバージョンを要求している場合に発生します。

エラーメッセージ

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: my-project@1.0.0
npm ERR! Found: react@18.2.0
npm ERR! node_modules/react
npm ERR!   react@"^18.2.0" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^17.0.0" from some-library@1.0.0
npm ERR! node_modules/some-library
npm ERR!   some-library@"^1.0.0" from the root project

原因

peer依存関係の競合: パッケージが異なるバージョンを要求
メジャーバージョンの不一致: React 17とReact 18など
古いパッケージ: 最新の依存関係に対応していないライブラリ
npm 7以降の厳格化: npm 6以前より厳格なチェック

解決策

1. –legacy-peer-depsオプションを使用

1
2
3
4
5
6
7
8
# インストール時
npm install --legacy-peer-deps

# または
npm install some-package --legacy-peer-deps

# ci時
npm ci --legacy-peer-deps

.npmrcに設定:

1
legacy-peer-deps=true

2. –forceオプションを使用

1
npm install --force

注意: –forceは依存関係の問題を無視するため、実行時エラーが発生する可能性があります。

3. 依存関係のバージョンを調整

package.json:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "dependencies": {
    "react": "^17.0.2",
    "some-library": "^1.0.0"
  },
  "overrides": {
    "some-library": {
      "react": "^18.2.0"
    }
  }
}

4. overridesで依存関係を上書き（npm 8.3+）

1
2
3
4
5
6
{
  "overrides": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  }
}

特定パッケージの依存のみ上書き:

1
2
3
4
5
6
7
{
  "overrides": {
    "some-library": {
      "react": "$react"
    }
  }
}

5. node_modulesとpackage-lock.jsonを削除して再インストール

1
2
3
4
5
6
7
8
# クリーンインストール
rm -rf node_modules package-lock.json
npm install

# キャッシュもクリア
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

6. 競合パッケージのバージョンを確認

1
2
3
4
5
6
7
8
9
# 依存関係ツリーを表示
npm ls react
npm ls react-dom

# 全依存関係を確認
npm ls --all

# 競合を確認
npm explain some-package

7. パッケージを最新版に更新

1
2
3
4
5
6
7
8
9
# 更新可能なパッケージを確認
npm outdated

# パッケージを更新
npm update some-library

# メジャーバージョン含め最新に
npx npm-check-updates -u
npm install

8. 代替パッケージを検討

問題のあるパッケージが更新されていない場合:

1
2
3
4
5
6
# フォーク版を使用
npm install @forked/some-library

# 類似の代替パッケージを使用
npm uninstall old-library
npm install new-alternative

9. peerDependenciesをdevDependenciesに追加

1
2
3
4
5
6
{
  "devDependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  }
}

10. npm 6にダウングレード（最終手段）

1
2
3
4
5
# npm 6を使用
npm install -g npm@6

# 元に戻す場合
npm install -g npm@latest

npm vs yarn vs pnpm

1
2
3
4
5
# yarn（peer依存関係が緩い）
yarn install

# pnpm（厳格だが高速）
pnpm install

予防策

package.jsonでバージョンを固定

1
2
3
4
5
6
{
  "dependencies": {
    "react": "18.2.0",
    "react-dom": "18.2.0"
  }
}

package-lock.jsonをコミット

1
2
git add package-lock.json
git commit -m "Lock dependencies"

engines フィールドでNode.jsバージョンを指定

1
2
3
4
5
6
{
  "engines": {
    "node": ">=18.0.0",
    "npm": ">=9.0.0"
  }
}

デバッグ情報

1
2
3
4
5
# 詳細なログを出力
npm install --loglevel verbose

# デバッグモード
npm install --loglevel silly

概要