为何Yarn在package.json指定^0.22.0时仍安装cheerio 1.0.0？

我的package.json内容如下：

{
  "scripts": {
    "examples": "docusaurus-examples",
    "start": "docusaurus-start",
    "build": "docusaurus-build",
    "publish-gh-pages": "docusaurus-publish",
    "write-translations": "docusaurus-write-translations",
    "version": "docusaurus-version",
    "rename-version": "docusaurus-rename-version"
  },
  "devDependencies": {
    "docusaurus": "^1.14.7",
    "cheerio": "^0.22.0"
  },
  "dependencies": {
    "react-treebeard": "^3.2.4"
  }
}

执行yarn install时触发如下错误：

error cheerio@1.0.0: The engine "node" is incompatible with this module. Expected version ">=18.17". Got "16.20.2"
error Found incompatible module.

我当前使用Node.js 16.20.2，cheerio 1.0.0确实提升了Node.js最低版本要求，这点符合预期。但升级Node.js后执行yarn build会报错，因此只能停留在16版本。

令人困惑的是，我已经明确指定安装cheerio 0.22.0（试过^0.22.0、~0.22.0和0.22.0三种写法），为什么yarn仍尝试安装1.0.0？如果是Docusaurus的某个依赖要求cheerio 1.0.0，我应该收到“需求不兼容”的错误，而非现在的Node版本不兼容错误？

核心原因 #

1. 依赖链的版本宽松声明
   Docusaurus 1.14.7的某个间接依赖（比如内部构建插件、工具库）可能对cheerio声明了宽松的版本要求，比如cheerio: "*"或cheerio: "^0.22.0 || ^1.0.0"。当cheerio 1.0.0发布后，yarn的版本解析器会优先选择满足所有依赖的最高可用版本——只要没有完全互斥的版本要求，它就会默认拉取最新版，而非你指定的旧版本。

2. 版本冲突检测的特殊情况
   只有当两个依赖对同一个包的版本要求完全互斥时（比如一个要求<=0.22，另一个要求>=1.0），yarn才会抛出“需求不兼容”错误。如果Docusaurus的依赖只是允许兼容多版本，yarn会认为1.0.0可以满足你的^0.22.0（注：语义化版本中主版本号为0时，^本应只允许小版本更新，但部分新版yarn的解析逻辑可能存在例外，或是间接依赖的版本声明覆盖了你的指定），进而尝试安装1.0.0，最终因Node版本不兼容报错。

解决办法 #

1. 强制锁定cheerio版本
   在package.json中添加resolutions字段，强制yarn忽略所有依赖的版本要求，安装指定的0.22.0版本：

   {
     // 保留原有字段内容
     "resolutions": {
       "cheerio": "0.22.0"
     }
   }
   

   添加后重新执行yarn install即可生效。

2. 排查冲突来源
   执行yarn why cheerio命令，查看所有依赖cheerio的包及其版本要求：

   yarn why cheerio
   

   输出结果会明确显示哪个包要求了cheerio 1.0.0，帮助你定位冲突根源。

3. 降级yarn版本（可选）
   如果是新版yarn的解析逻辑导致的问题，可以尝试降级到yarn 1.x稳定版（如1.22.19），旧版yarn对语义化版本的解析更严格，会优先遵循你指定的^0.22.0要求，不会自动升级到1.0.0版本。

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