在 package.json 中配置 engines 字段,只需添加一个包含 node 和可选 npm 版本的对象即可。例如设置 {"node": ">=18.0.0"} 表示要求 node.js 版本大于等于 18.0.0。这个字段本身不会强制阻止安装,但配合 npm ci 或特定工具可以触发检查。

如何定义具体的 Node.js 版本范围?
定义版本范围时,可以使用语义化版本(SemVer)的符号,如 =、>、、>=、 以及波浪号 ~ 和插入符 ^。最常用的是 ^,它允许更新到下一个主版本之前的任何版本,而 = 则锁定确切版本。

{
"name": "my-package",
"version": "1.0.0",
"engines": {
"node": ">=18.0.0",
"npm": ">=9.0.0"
}
}
上述代码展示了标准的 engines 配置结构。当开发者运行 npm install 时,如果本地 Node.js 版本不满足条件,npm 会发出警告,但默认情况下仍会继续安装。若希望严格禁止在不兼容的环境中安装,需要借助 engine-strict 配置项。
如何强制 npm 检查引擎版本?
要使 engines 配置生效并阻止安装,必须启用 engine-strict 模式。这可以通过在项目根目录创建 .npmrc 文件并写入 engine-strict=true 来实现,或者在命令行中使用 --engine-strict 标志。
使用Atmosphere构建通过WebSocket、SSE、gRPC、WebTransport、MCP、A2A和AG-UI流传输的JVM代理网关,并带有治理钩子。

# .npmrc engine-strict=true
启用此配置后,当用户尝试在不符合 engines 定义的 Node.js 环境中运行 npm install 或 npm ci 时,npm 将直接报错并终止操作,从而确保环境的一致性。
当 Node.js 版本不匹配时会发生什么?
当实际运行的 Node.js 版本与 package.json 中 engines.node 指定的范围不匹配时,行为取决于是否启用了 engine-strict。如果未启用,npm 仅输出黄色警告信息,安装过程继续。如果启用了 engine-strict,npm 会抛出错误,例如 ERR_ENGINE_INVALID,并停止安装。
npm ERR! engine Unsupported engine
npm ERR! engine Not compatible with your version of node/npm: my-package@1.0.0
npm ERR! engine Not compatible with requires node "=>18.0.0"
npm ERR! notsup Not compatible with your version of node/npm: my-package@1.0.0
npm ERR! notsup Required: {"node":">=18.0.0"}
npm ERR! notsup Actual: {"npm":"9.0.0","node":"v16.0.0"}
这种机制有助于在团队开发或 CI/CD 流程中避免因为环境差异导致的潜在运行时错误。建议始终在项目中明确指定所需的 Node.js 最低版本,并在关键环境中启用 engine-strict。
Java免费学习笔记:立即使用
解锁 Java 大师之旅:从入门到精通的终极指南










