踩坑实录：为什么 `pnpm run` 会偷偷帮你装依赖？—— 浅析 pnpm 与 npm run 的底层差异
Node.js 有不同的包管理器（npm、Yarn 或 pnpm），每个包管理器也都能运行 package.json 中定义的脚本。多数情况下，npm run dev 和 pnpm run dev 看起来没有任何区别，都能跑对应的 Command。
但最近在使用 pnpm 生成 SBOM 时，我就遇到了那小部分的情况。对于同一个脚本，npm run 执行成功了，而 pnpm run 却陷入了无限报错的死循环。
这一差异引起了我的好奇心，我带着疑问便借助 AI 的分析扒一扒这背后隐藏着 pnpm 和 npm 在脚本执行机制上的巨大差异。
案发现场：一个神奇的 Bug
起因是需要对一个管理所有服务类型的 Monorepo 仓库做 SBOM。由于使用 git submodule 的方式，各个服务的 pnpm 版本不同，直接使用 pnpm install 会导致报错。
而 pnpm sbom 命令允许 lockfile-only 模式，为此我使用 pnpm install --ignore-scripts 来安装依赖生成用于分析的 lockfile。我便在 package.json 中加了一个 sbom 脚本：
{
"scripts": {
"sbom": "pnpm sbom --sbom-format cyclonedx --lockfile-only"
}
}神奇的事情发生了：
- 我执行
npm run sbom，瞬间执行成功，拿到了报告。 - 我执行
pnpm run sbom，终端却疯狂输出日志，它居然在后台重新触发了pnpm install！随着一行行依赖安装的日志出现，最终因为一个 C++ 编译错误崩溃退出：
...
Packages: +123 -0
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
...
gyp ERR! build error
gyp ERR! stack Error: `make` failed with exit code: 2
gyp ERR! System Darwin 25.4.0
...我不信邪，又尝试了几次，结果都是这样。这就激起了我的好奇心：为什么 pnpm run sbom 会“自作主张”地去安装依赖？
深度剖析：npm run 的“无情” vs pnpm run 的“智能”
要理解这个现象，我们需要回到官方文档和工具的底层设计哲学。
1. npm run：一个纯粹的命令执行器
在 npm 的世界里，npm run-script <command>（简写为 npm run）的定位非常纯粹。根据 npm 官方文档，它的核心工作机制只有两步：
- 将当前项目的
node_modules/.bin临时加入到系统的PATH环境变量中。 - 将
package.json中对应的字符串原封不动地交给 Shell 去执行。
npm 是“无情”的。 它不会去关心你的 node_modules 是否完整，也不会去检查你的 package-lock.json 是否和当前安装的包一致。只要脚本能跑，它就跑；跑不通报错，那是脚本自己的事。
所以在我的例子中，npm run sbom 直接执行了 pnpm sbom --lockfile-only。而这个底层的 pnpm 内置命令确实不需要完整的 node_modules 就能运行，于是大获成功。
2. pnpm run：极其严格的依赖状态检查（Auto-install）
pnpm 的设计哲学一直以严格（Strictness）和正确性（Correctness）著称。这种哲学不仅体现在它的软链接（symlink）和幽灵依赖防护上，同样体现在它的脚本执行机制上。
在较新的 pnpm 版本（如 v11）中，当您执行 pnpm run <script> 时，pnpm 并不只是简单地抛给 Shell。在实际执行脚本之前，pnpm 会在底层调用一个名为 runDepsStatusCheck 的前置检查机制（该行为受配置项 verifyDepsBeforeRun 控制）。
简单来说，它的核心作用是自动核对你当前的 node_modules 是否与 lock 文件保持同步。这个机制会做以下事情：
- 状态校验：对比
pnpm-lock.yaml、package.json以及实际的node_modules目录状态。 - 自动修复（Auto-install）：如果 pnpm 发现
node_modules处于未同步、不完整或损坏的状态（比如我之前因为编译失败而中断的安装），它会认为“在损坏的依赖环境下执行脚本是不安全的”。 - 触发安装：为了保证脚本执行环境的绝对正确，pnpm 会自动在后台触发一次
pnpm install，试图帮开发者修复依赖。
这就是为什么 pnpm run sbom 会重新安装依赖的原因。它太“智能”了，发现了我的 node_modules 是残缺的，于是好心办坏事，一头撞上了那个我还没解决的 C++ 编译错误。
扩展：为什么直接执行 pnpm sbom 不会触发检查？
虽然理解了 pnpm run 会触发检查，但既然 pnpm 这么严格，为什么 npm run sbom 底层调用的 pnpm sbom 却没有触发依赖检查呢？
这是因为 sbom 是 pnpm 的内置 CLI 命令（Built-in Command），而不是用户定义的脚本（User Script）。
- 内置命令（如
pnpm add,pnpm store,pnpm sbom）有自己独立的生命周期和执行逻辑，它们知道自己需要什么。比如pnpm sbom --lockfile-only明确声明了只读 lockfile，自然不会去管node_modules。 - 用户脚本（通过
pnpm run执行）对 pnpm 来说是黑盒。pnpm 不知道你的脚本到底依赖了什么，为了安全起见，它只能强制要求整个node_modules必须是健康且完整的。
总结与实战建议
在 AI 和官方文档的帮助下，这类问题很快就得到了解答。总结一下的话有以下几点：
npm run是“瞎子”：它只管执行，不问环境。适合在环境不完整时强行执行某些不依赖node_modules的独立脚本。pnpm run是“管家”：它在执行前会进行严格的依赖状态检查（runDepsStatusCheck）。如果依赖不同步，它会自动触发install。- 排错与配置指南：
- 如果你在使用 pnpm 时发现某个脚本莫名其妙地卡在依赖安装上，请先检查你上一次的
pnpm install是否真正 100% 成功了。只要node_modules状态不健康，pnpm run就会一直试图修复它。 - 如果你觉得这种“自动安装”太烦人，想要关掉它，可以在项目根目录的
.npmrc或pnpm-workspace.yaml中配置verifyDepsBeforeRun=false（或者设置为prompt让它每次询问），这样pnpm run就不再自作主张了。
- 如果你在使用 pnpm 时发现某个脚本莫名其妙地卡在依赖安装上，请先检查你上一次的
了解这些底层机制，能让我们在面对构建流报错时少走很多弯路。工具的“智能”是为了在 99% 的场景下保护我们，而理解它的机制，则是为了在剩下 1% 的极端场景下驾驭它。