【构建兼容性问题】pnpm 11 下执行 build 失败，npm_execpath 被错误地作为 Node 脚本执行

[SnowAmberX]

问题描述

在使用 pnpm 11.7.0 和 Node.js 24.19.0 从源码构建 deepseek-harness 时，执行：

pnpm install
pnpm run build

构建失败。

环境：

• 操作系统：WSL2 Ubuntu Linux
• Node.js：v24.19.0
• pnpm：v11.7.0
• 架构：linux x64

错误信息：

SyntaxError: Invalid or unexpected token

file:///home/.../.local/share/pnpm/store/v11/links/@pnpm/exe/11.7.0/.../node_modules/@pnpm/exe/pnpm:1

ELF>

---

问题原因分析

问题应该出现在：

scripts/build.ts

中的代码：

const packageManager = process.env.npm_execpath

const result = spawnSync(process.execPath, [packageManager, 'run', script], {

这里假设 npm_execpath 指向的是一个 JavaScript 文件。

但是在 pnpm 11 中：

npm_execpath

可能指向：

.../node_modules/@pnpm/exe/pnpm

这个文件是 Linux ELF 可执行文件，而不是 JavaScript 文件。

当前代码实际执行：

node /path/to/pnpm run build:lib

于是 Node.js 会尝试解析 pnpm 二进制文件：

ELF>

最终导致：

SyntaxError: Invalid or unexpected token

---

补充说明

这个问题在旧版本 npm/pnpm 布局下可能不会出现，因为：

• 某些版本的 npm_execpath 指向 .js 文件；
• 旧版本 pnpm 可能使用 JavaScript launcher。

但是 pnpm 11 使用了 @pnpm/exe 二进制入口，因此不能再假设 npm_execpath 可以通过 Node 执行。

建议后续避免依赖 npm_execpath 是 Node 脚本这一假设，直接执行 package manager 可提高兼容性。

[SnowAmberX]

使用windows也同样具有此问题

> pnpm run build
$ tsx scripts/build.ts
node:internal/modules/esm/get_format:243
  throw new ERR_UNKNOWN_FILE_EXTENSION(ext, filepath);
        ^

TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".exe" for D:\pnpm\store\v11\links\@pnpm\exe\11.7.0\a254132c028a4f0368fb9ee996a0169a530281496d7f26c4b2de752a7553ec1c\node_modules\@pnpm\exe\pnpm.exe
    at Object.getFileProtocolModuleFormat [as file:] (node:internal/modules/esm/get_format:243:9)
    at defaultGetFormat (node:internal/modules/esm/get_format:283:36)
    at defaultLoadSync (node:internal/modules/esm/load:161:16)
    at #loadAndMaybeBlockOnLoaderThread (node:internal/modules/esm/loader:802:12)
    at #loadSync (node:internal/modules/esm/loader:834:53)
    at ModuleLoader.load (node:internal/modules/esm/loader:783:26)
    at ModuleLoader.loadAndTranslate (node:internal/modules/esm/loader:494:31)
    at #getOrCreateModuleJobAfterResolve (node:internal/modules/esm/loader:560:36)
    at afterResolve (node:internal/modules/esm/loader:607:52)
    at ModuleLoader.getOrCreateModuleJob (node:internal/modules/esm/loader:613:12) {
  code: 'ERR_UNKNOWN_FILE_EXTENSION'
}

Node.js v24.19.0
D:\Desktop\Code\github\deepseek-harness\scripts\build.ts:28
    throw new Error(`build: ${script} exited with ${String(result.status ?? result.signal)}`)
          ^

Error: build: build:lib exited with 1
    at runScript (D:\Desktop\Code\github\deepseek-harness\scripts\build.ts:28:11)
    at main (D:\Desktop\Code\github\deepseek-harness\scripts\build.ts:47:3)
    at <anonymous> (D:\Desktop\Code\github\deepseek-harness\scripts\build.ts:55:23)
    at ModuleJob.run (node:internal/modules/esm/module_job:439:25)
    at async node:internal/modules/esm/loader:643:26
    at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:101:5)

Node.js v24.19.0
[ELIFECYCLE] Command failed with exit code 1.

[linjiacheng]

MacOS 也有同样问题
arm64
Node 24.19.0
mise
pnpm 11.22.0
改为

- spawnSync(process.execPath, [packageManager, 'run', script], {
+ spawnSync(packageManager, ['run', script], {

正常。

[argszero]

linjiacheng 的直改已验证有效（Mac arm64 + Windows .cmd 均过），补一个家族视角 + 一个平台坑，让修复一次到位：

1. 这是家族级问题，不止 build.ts 一处

npm_execpath 被当作 Node 脚本执行的假设遍布 rc.8 5 个脚本：

• scripts/build.ts:17（本贴报错点）
• scripts/run-gates.ts:199（entrypoint = process.env.npm_execpath，同样 spawnSync(process.execPath, [entrypoint, ...])）
• scripts/run-coverage-partitions.ts:16
• scripts/run-web-snapshots.ts:13
• scripts/coverage-partitions.ts:50（注释直言 "pnpm JavaScript entrypoint from npm_execpath"）

pnpm 11 的 @pnpm/exe 把入口从 .js 换成 ELF（Linux）/ .exe（Windows），这 5 处全部会中招——只是 build.ts 是用户最先撞到的。只修 build.ts，CI 的 run-gates 会在同样的问题上倒下。而且 #3532（Mingze1208，同样错误）与本贴同根，家族 = 2 报告 + 5 调用点。

2. 直改 spawnSync(packageManager, ...) 在 Windows 有一个平台坑

pnpm 11 在 Windows 的 npm_execpath 是 pnpm.exe（ELF/.exe 直连没问题），但npm 7+ 的 npm_execpath 是 npm-cli.js（纯 JS）——用 spawnSync(packageManager, ...) 直跑 .js 文件在 Windows 上没有关联执行器会失败（EINVAL/UNKNOWN）。所以"直接执行入口"方案需要按扩展名分支：

// .js → 用 process.execPath 跑（npm 传统形态）；无扩展名/ELF/.exe/.cmd → 直接 spawn
const isJs = /\.c?js$/i.test(packageManager)
const result = spawnSync(isJs ? process.execPath : packageManager,
  isJs ? [packageManager, 'run', script] : ['run', script], ...)

这样 npm（.js）与 pnpm 11（ELF/.exe）两条路都通。spawnSync(packageManager, ...) 里包一层 shell: true 也能让系统解析 shebang/.cmd，但会引入引号/元字符语义变化（denial 在 #3532 已指出），扩展名分支更精确。

3. 建议收敛为共享 helper

5 处重复同样的 npm_execpath 解析，正好收敛成一个 runViaPackageManager(script, env) helper（放 scripts/ 共享模块），一处修好全家族受益——避免 5 处各自打补丁又漂移。这也和本仓库"run-gates 等脚本共享 launcher"的既有结构一致。

给官方：pnpm 11 已进 engines 支持范围（pnpm@11.7.0 在 #3510/#3583 里都是用户实测版本），这个 npm_execpath 假设的失效是跨 5 个脚本的 CI 兼容性债，值得一次共享修复 + 每入口回归。

[SnowAmberX]

补充一下对 scripts/build.ts Git 历史的排查结果。

从该文件的提交历史来看，scripts/build.ts 实际经历过一次 删除后重新引入：

1. ae2e08b：最初引入 scripts/build.ts
2. 630bbdd：在将 JS bundler 从 dumble 切换到 tsdown 时删除了该文件
3. 66a7081：重新引入了当前这版 scripts/build.ts

其中 66a7081 的变更说明中明确提到：

scripts/build.ts deleted; yarn build = tsc -b && tsdown.

因此，当前触发问题的这段逻辑并不是从旧版 scripts/build.ts 一直保留下来的，而是在 66a7081 中重新引入的：

const packageManager = process.env.npm_execpath

const result = spawnSync(process.execPath, [packageManager, 'run', script], {
  cwd: resolve(import.meta.dirname, '..'),
  env: environment,
  stdio: 'inherit',
})

所以从目前的提交历史来看，这个兼容性问题应该可以比较明确地追溯到 66a7081 中重新引入的 runScript() 实现，而不是早期 scripts/build.ts 的遗留行为。

建议可以考虑直接执行 npm_execpath，而不是假定它一定是一个可由 Node.js 执行的 JavaScript 入口，例如：

spawnSync(packageManager, ['run', script], {
  cwd: resolve(import.meta.dirname, '..'),
  env: environment,
  stdio: 'inherit',
})

[PerryLink]

已修复：scripts/build.ts 不再假设 npm_execpath 一定是 JS 入口——runScript 现在
经共享 helper pnpmInvocation() 构造正确的命令与参数
（scripts/build.ts:15、18-20；scripts/pnpm-invocation.ts），修复提交
89674ed（2026-08-21，"fix(build): support standalone pnpm entrypoints"），
已在当前 master（c291e7961a）上核实。

获取修复：更新到最新 master 后，pnpm 11（@pnpm/exe 的 ELF/.exe 入口）下
pnpm run build 正常，不再报 SyntaxError / ERR_UNKNOWN_FILE_EXTENSION。