Hardhat依赖安装失败：ERESOLVE依赖树冲突问题求助

问题场景 #

先执行npm i hardhat安装成功，随后误输入npx hardahat完成项目配置，系统提示需安装示例项目依赖，但我只装了hardhat，补装完整依赖时执行以下命令：

npm install --save-dev "hardhat@^2.17.1" "@nomicfoundation/hardhat-toolbox@^3.0.0"

触发了依赖冲突错误，日志如下：

npm install --save-dev "hardhat@^2.17.1" "@nomicfoundation/hardhat-toolbox@^3.0.0"
npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: tracking@0.1.0
npm ERR! Found: ethers@5.7.2
npm ERR! node_modules/ethers
npm ERR!   ethers@"^5.7.2" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer ethers@"^6.1.0" from @nomicfoundation/hardhat-ethers@3.0.4
npm ERR! node_modules/@nomicfoundation/hardhat-ethers
npm ERR!   peer @nomicfoundation/hardhat-ethers@"^3.0.0" from @nomicfoundation/hardhat-toolbox@3.0.0
npm ERR!   node_modules/@nomicfoundation/hardhat-toolbox
npm ERR!     dev @nomicfoundation/hardhat-toolbox@"3.0.0" from the root project
npm ERR!   peer @nomicfoundation/hardhat-ethers@"^3.0.0" from @nomicfoundation/hardhat-chai-matchers@2.0.2
npm ERR!   node_modules/@nomicfoundation/hardhat-chai-matchers
npm ERR!     peer @nomicfoundation/hardhat-chai-matchers@"^2.0.0" from @nomicfoundation/hardhat-toolbox@3.0.0
npm ERR!     node_modules/@nomicfoundation/hardhat-toolbox
npm ERR!       dev @nomicfoundation/hardhat-toolbox@"3.0.0" from the root project
npm ERR!
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.
npm ERR!
npm ERR!
npm ERR! For a full report see:
npm ERR! C:\Users\\AppData\Local\npm-cache\_logs\2023-08-24T20_39_45_411Z-eresolve-report.txt

npm ERR! A complete log of this run can be found in: C:\Users\liamr\AppData\Local\npm-cache\_logs\2023-08-24T20_39_45_411Z-debug-0.log
PS C:\Users\liamr\tracking>

解决方法 #

1. 升级 ethers 到 v6 版本（优先推荐） #

错误核心是当前项目依赖的ethers@5.7.2和@nomicfoundation/hardhat-toolbox@3.0.0要求的ethers@^6.1.0不兼容，直接升级 ethers 即可：

npm install ethers@^6.1.0 --save

升级完成后重新执行原安装命令：

npm install --save-dev "hardhat@^2.17.1" "@nomicfoundation/hardhat-toolbox@^3.0.0"

2. 使用--legacy-peer-deps跳过依赖检查 #

如果暂时不想升级 ethers，可添加该参数让 npm 采用旧的 peer 依赖解析规则：

npm install --save-dev "hardhat@^2.17.1" "@nomicfoundation/hardhat-toolbox@^3.0.0" --legacy-peer-deps

⚠️ 注意：此方法可能埋下兼容性隐患，仅作为临时方案使用。

3. 重置依赖环境（适合新手） #

如果前两种方法无效，可彻底清理现有依赖后重新安装：

• 删除项目根目录下的node_modules文件夹
• 删除package-lock.json文件
• 重新执行完整安装命令：

npm install --save-dev "hardhat@^2.17.1" "@nomicfoundation/hardhat-toolbox@^3.0.0"

内容的提问来源于stack exchange，提问作者Liam Ryan