升级Node.js至v20.9.0时遭遇sinon-chai依赖解析失败问题

问题描述 #

原项目使用Node.js v16.14.2，升级至v20.9.0后执行npm install时出现以下依赖冲突错误：

npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR! 
npm ERR! While resolving: sinon-chai@2.14.0
npm ERR! Found: sinon@6.1.3
npm ERR! node_modules/sinon
npm ERR!   dev sinon@"6.1.3" from the root project
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer sinon@"^1.4.0 || ^2.1.0 || ^3.0.0 || ^4.0.0" from sinon-chai@2.14.0
npm ERR! node_modules/sinon-chai
npm ERR!   dev sinon-chai@"^2.8.0" from the root project
npm ERR! 
npm ERR! Conflicting peer dependency: sinon@4.5.0
npm ERR! node_modules/sinon
npm ERR!   peer sinon@"^1.4.0 || ^2.1.0 || ^3.0.0 || ^4.0.0" from sinon-chai@2.14.0
npm ERR!   node_modules/sinon-chai
npm ERR!     dev sinon-chai@"^2.8.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!

尝试单独升级相关包未成功，且sinon-chai最后一次更新在3年前，寻求替代包或其他解决方案。

解决方案 #

1. 临时绕过依赖校验（快速解决） #

使用npm提供的--legacy-peer-deps参数跳过peer依赖校验，这是最直接的临时方案：

npm install --legacy-peer-deps

该参数会让npm回到v4至v6版本的peer依赖处理逻辑，忽略版本冲突。但需注意，这可能隐藏潜在兼容性问题，后续需逐步验证项目功能是否正常。

2. 替换为维护活跃的替代包 #

由于sinon-chai已停止维护，推荐以下替代方案：

• @sinonjs/referee-sinon：Sinon官方推荐的断言库，由Sinon团队维护，兼容最新版本Sinon，API设计与sinon-chai类似，迁移成本低。
  • 安装命令：

    npm uninstall sinon-chai && npm install --save-dev @sinonjs/referee-sinon
    

  • 代码迁移示例：
    原sinon-chai用法：

    expect(spy).to.have.been.calledOnce;
    

    替换为referee-sinon：

    const { assert } = require('@sinonjs/referee-sinon');
    assert.calledOnce(spy);
    

• 直接使用Sinon内置断言：Sinon本身提供完整的断言方法，无需额外依赖，例如：

  sinon.assert.calledOnce(spy);
  sinon.assert.calledWith(spy, 'expected-argument');
  

3. 降级Sinon到兼容版本 #

如果暂时不想替换依赖，可将Sinon降级到sinon-chai@2.14.0支持的最高版本（v4.x）：

npm install --save-dev sinon@^4.5.0

但此方案会无法使用Sinon新版本特性，长期仍面临依赖过时问题，仅作为临时过渡方案。

4. 手动适配sinon-chai（进阶） #

如果项目对sinon-chai的API依赖极深，可尝试forksinon-chai仓库，修改其peer依赖声明为兼容更高版本Sinon（例如^1.4.0 || ^2.1.0 || ^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0），然后将项目依赖指向fork后的仓库地址。但需自行维护该分支的兼容性，成本较高。

内容的提问来源于stack exchange，提问作者Mayank Soni