在构建前端项目或 CI/CD 流水线时，我们常常会遇到依赖版本与当前 Node.js 环境不兼容的问题。本文将围绕一个典型的报错信息展开说明，并提供一种实用的解决方案。

一、问题

最近在一个 CI 构建任务中，执行 pnpm install 时报错如下：

error minimatch@10.0.3: The engine "node" is incompatible with this module.
Expected version "20 || >=22". Got "18.20.5"

这表示当前使用的 Node.js 版本为 18.20.5，但项目依赖的 minimatch@10.0.3 要求 Node.js 版本必须是 20.x 或更高（>=22），因此安装失败。

二、分析

1. minimatch 是什么？

minimatch是一个用于通配符匹配文件路径的 JavaScript 库，广泛被许多 npm 包依赖，例如 glob、eslint、jest 等。

2. 为什么会出现这个问题？

某些第三方库或工具可能依赖了最新版的 minimatch（如 v10），而该版本只支持 Node.js v20 及以上。如果你的环境只能使用 Node.js v18，那么就需要降级 minimatch 到兼容版本。

三、解决

1. 升级node至满足条件的版本；
2. 如果你不能升级 Node.js 版本（比如 CI 环境受限），可以通过修改 package.json 文件中的 resolutions 字段来强制指定某个依赖树下的子依赖版本。
3. 什么是 resolutions？
   在使用 pnpm 时，resolutions 字段允许你强制指定某个依赖的版本，无论其他依赖想要什么版本。

注意：resolutions 是 pnpm 和 yarn 支持的功能，npm 并不支持，npm可了解下overrides（overrides适用于 npm 8.3+)。

步骤如下：

• 查看minimatch历史版本
  

• 选择9x版本，例如9.0.5，在 package.json 中添加或修改 resolutions 字段：

{
  "resolutions": {
    "minimatch": "9.0.5"
  }
}

或者更精确地控制嵌套依赖中的版本（这样可以确保所有层级下的依赖都使用这个版本）：

{
  "resolutions": {
    "**/minimatch": "9.0.5"
  }
}

• 保存后重新运行安装命令：

pnpm install

或者使用 --strict 参数确保 resolutions 生效：

pnpm install --strict

这样，pnpm 就会强制所有依赖链中对 minimatch 的引用都使用 9.0.5 这个兼容 Node.js 18 的版本。

四、验证

安装完成后，可以通过以下方式确认使用的 minimatch 是否为你指定的版本：

pnpm ls minimatch

输出应类似如下内容：

minimatch@9.0.5

如果看到的是 10.0.3，说明 resolutions 没有生效，检查一下拼写或语法是否正确。

五、总结

当项目依赖的新版本模块与当前 Node.js 不兼容时，可以通过如下方式解决：

• 升级 Node.js 版本（优先推荐）。但是在一些公司内部环境中，升级 Node.js 版本可能涉及大量测试与审批流程，短期内不可行。此时临时降级依赖版本是快速解决问题的办法
• 使用 resolutions（Yarn）或 overrides（npm）锁定子依赖版本。minimatch@9.x 与 10.x 的主要差异在于对 Node.js 新特性的利用和性能优化，大多数情况下不会影响实际功能。
• 长期来看，可以逐步升级 Node.js 到 20 或更高版本，以保持生态兼容性和安全性。

六、扩展

如果使用的是npm，而非yarn、pnpm该怎么解决？

1. 安装yarn、pnpm，使用yarn、pnpm
2. 使用npm:

• 1.直接修改 package.json

直接编辑项目的 package.json 文件，手动调整 minimatch 或相关依赖的版本号为我们希望安装的版本（例如 “9.0.5”），然后运行 npm install 来更新依赖。

{
  "dependencies": {
    "minimatch": "9.1.0"
  }
}

• 2.使用 npm-force-resolutions

虽然 npm 本身没有提供类似于 resolutions 的功能，但是可以通过第三方工具如 npm-force-resolutions 实现类似的效果。首先需要安装这个工具：

npm install npm-force-resolutions --save-dev

然后，在 package.json 中添加一个预安装脚本和 resolutions 配置：

{
  "scripts": {
    "preinstall": "npx npm-force-resolutions"
  },
  "resolutions": {
    "minimatch": "9.0.5"
  }
}

注意：这里的 resolutions 字段仅对 npm-force-resolutions 工具有效，并不是标准的 npm 功能。

• 3.使用 overrides (适用于 npm 8.3+)

如果我们使用的 npm 版本是 8.3 或更高，可以利用 overrides 字段直接指定某个依赖包应该使用的版本：

{
  "overrides": {
    "minimatch": "9.0.5"
  }
}

这允许我们覆盖项目中任何地方对该包的依赖声明，强制使用特定版本。

---

【举一反三，安装其他依赖遇到类似问题，也可以类似解决】

---