Fix(cli) Proposal: 让入口守卫在 Node 24.0–24.1 上失败可见，并把它们移出 engines 范围

[wyklq]

标题：fix(cli): 让入口守卫在 Node 24.0–24.1 上失败可见，并把它们移出 engines 范围

关联讨论：#4047（build 静默跳过）、#5082（Node < 24.2 下 build 静默退出、退出码 0）、#5100（残留目录导致误导性
MISSING_EXPORT）、以及社区帖 #5084 相邻的 loader shape 问题
。

---

摘要

仓库在 423412b7bf（fix(runtime): simplify executable entry dispatch，2026-09-03）把入口判定统一换成了
import.meta.main，共 14 处。该 API 在 Node 24.0.0–24.1.x 上求值为 undefined（既不是 true 也不是 false），
而 engines.node 声明为 ^22.19.0 || >=24.0.0 —— 这些版本声明支持、却不满足任何入口守卫。后果是进程零输出、退出
码 0，pnpm run build 与 pnpm dsh web 都表现为"没有任何报错，直接退出"。

影响

入口	Node 24.0–24.1 上的行为
pnpm dsh web	静默退出 0，服务不启动，无任何输出
pnpm dsh --profile headless "..."	同上
pnpm run build	静默退出 0，不生成任何构建产物（build:lib / build:web 从未执行）
dsh（npm 全局安装，bin → lib/bin.js）	同上，用户侧完全不可用
name-server（subprocess-local/lib/runner.js）	同上

二次伤害：pnpm run build 静默成功会留下"看似已构建"的残缺工作区（缺 packages/*/*/lib/client.js），后续启动才报
client bundles not found，把排查引向错误方向。

复现

fnm install 24.1.0 && fnm use 24.1.0
pnpm install && pnpm run build     # exit 0，无输出，无产物
pnpm dsh web                        # exit 0，无输出，服务未起

---

根因与实测

1) import.meta.main 的版本行为（本机实测，非文档推断）

Node	import.meta.main（.mjs / .ts 经 tsx 加载）
22.19.0	true
24.0.0	undefined
24.1.0	undefined
24.2.0	true
24.3.0 / 24.4.0 / 24.9.0 / 24.19.0	true
26.8.1	true

即 24.x 行的分界是 24.2.0。（未找到对应的 Node release note，以上为实测结论；若维护者掌握上游出处，欢迎补充。）

2) 同一棵构建产物在不同 Node 上的表现（同一份 apps/cli/lib/bin.js）

Node      | esm (.mjs)  | 源码启动 (tsx) | 已构建 dsh 入口
----------+-------------+---------------+------------------
22.19.0   | true        | true          | 0.1.5-rc.2
24.0.0    | undefined   | undefined     | (无输出)
24.1.0    | undefined   | undefined     | (无输出)   ← 复现用户报告
24.2.0    | true        | true          | 0.1.5-rc.2
24.3.0    | true        | true          | 0.1.5-rc.2
24.9.0    | true        | true          | 0.1.5-rc.2
24.19.0   | true        | true          | 0.1.5-rc.2
26.8.1    | true        | true          | 0.1.5-rc.2

3) 受影响的 14 处源码入口

apps/cli/src/bin.ts:64
apps/desktop-host/src/index.ts:584
apps/desktop/scripts/prepare-package-set.ts:172
packages/subprocess/subprocess-local/src/bin.ts:18
scripts/build.ts:53
scripts/run-gates.ts:99
scripts/benchmark-next-package-dependency.ts:264
scripts/benchmark-npm-resolution.ts:544
scripts/verify-cordis-config.ts:60
scripts/verify-doc-site-fragments.ts:181
scripts/verify-npm-install-layout.ts:213
scripts/verify-package-dependencies.ts:863
scripts/verify-package-readme-summaries.ts:64
scripts/verify-runtime-closure.ts:101

其中随包发布、直接影响下游的 3 个产物：apps/cli/lib/bin.js（@deepseek-ai/dsh 的 bin）、
apps/desktop-host/lib/index.js、packages/subprocess/subprocess-local/lib/runner.js。

为什么 CI 没有拦住

两处叠加：

1. 兼容性矩阵不含 24.0–24.1。.github/workflows/ci.yml 的版本矩阵是 22.19 / 24.9 / 26（24.9 是刻意钉住的，注
   释说明 24.0–24.11.1 携带 v1 内部 loader），主 CI 跑 PRIMARY_NODE_VERSION: '24' = 最新 24。24.0–24.1 从未被任何一条
   腿执行到，而它们又恰好落在 engines.node 声明范围内。
2. 这些版本上 pnpm install 不会失败（24.1 满足 >=24.0.0），所以"声明范围"与"实际可用范围"的缺口没有任何信号
   。

另外，源码启动路径（node --import tsx/esm apps/cli/src/bin.ts）与已构建入口在 24.1 上同样静默，因此 pnpm dsh
和 dsh 都不能作为对照。

关于"为什么当初改掉旧守卫"

不能简单回退。423412b7bf 把旧的

const invokedPath = process.argv[1]
if (invokedPath !== undefined && import.meta.url === pathToFileURL(resolve(invokedPath)).href) {

换成了 import.meta.main，同时新增了 apps/cli/tests/built-bin.e2e.ts 的 runs through an installed-style symlink 用例 —— 即旧写法在 npm/pnpm 全局安装的符号链接场景下不可靠，而 import.meta.main 能正确处理（并且它本来就是
为了让 runCli 可被 python/sdk-runtime/runtime-bootstrap.mjs 直接 import 调用）。所以修复必须同时满足：符号链接
下正确 + 24.0–24.1 上可诊断。

---

建议修复

A. 收紧 engines.node（必做，最小改动）

把声明范围与实测可用范围对齐，排除 24.0–24.1：

// package.json
"engines": { "node": "^22.19.0 || >=24.2.0" }

理由：^22.19.0 上 import.meta.main 已可用（实测 true），24.x 行自 24.2.0 起可用。若维护者希望 24.x 下界取更高
、更整洁的值（例如与兼容矩阵 24.9 对齐），我按你们的判断调整。

B. 入口守卫失败要可见（必做，防止同类回归）

import.meta.main 在 undefined 时静默不执行，这是本次事故的放大器。建议在共享位置（或各入口）加一条 fail-loud
断言，把"版本不被支持"从零输出变成明确报错：

// import.meta.main 在 Node < 24.2 上为 undefined；静默跳过入口会让
// `dsh` / `pnpm run build` 以退出码 0 什么都不做。
if (import.meta.main === undefined) {
  throw new Error(
    `dsh: Node ${process.version} does not provide import.meta.main; use Node 22.19+ or 24.2+`,
  )
}

C. 补一条落在缺口里的 CI 腿（建议）

在兼容矩阵加 24.1（或 24.0）一条最小腿，跑 pnpm run build + apps/cli/lib/bin.js --version。这条腿会直接复现"
退出码 0 且无输出"，是本次缺口唯一的自动化防护。注意 24.0–24.1 与已钉住的 24.9 一样属于 v1 loader 区间
，DSH_GATE_FAIL_FAST / gate 并发等设置需按现有约定处理。

D. 断言层（可选，但推荐）

在 apps/cli/tests/built-bin.e2e.ts 已有的 built-bin 用例旁，加一条"入口必须真的执行"的断言（例如 --version 必须
有非空 stdout），而不是只断言 exitCode === 0。当前 24.1 下 exitCode 恰好是 0，只用退出码判定会漏掉这个缺陷。

同步文档：.agents/notes/implemented/process/2026-07-06-node-engine-floor.md 记录了引擎下限的推导
（node:sqlite、原生类型剥离、pi-ai 依赖下限）。若采纳 A，该 Note 的"24.x 分支保持 >=24.0.0"一句需同步更新并补充
import.meta.main 这一条新增约束（按仓库约定，同一 PR 内更新）。

不推荐的方案

• 回退到 argv[1] + pathToFileURL 字符串比较：会重新引入 423412b7bf 修掉的符号链接问题。若要走这条路，必须
  改成 realpathSync 规范化后再比较，并保留现有的 symlink e2e 用例。
• 只加 B（fail-loud）不改 engines：仍然声明支持 24.0–24.1 却直接报错，属于把"静默不可用"换成"启动即失败"，用户仍
  需自行猜测版本。
• 只改 A 不加 B：同类"守卫失效即静默"的回归会在下一次 Node 行为变化时再次发生。

---

验证方式

# 每个版本上：非 24.0–24.1 必须打印版本号，24.0–24.1 必须失败可见
for v in 22.19.0 24.0.0 24.1.0 24.2.0 24.9.0 26.8.1; do
  echo -n "node $v -> "
  npx -y node@$v apps/cli/lib/bin.js --version || echo "(fails loud, as intended)"
done

修复后预期：22.19.0 / 24.2.0 / 24.9.0 / 26.8.1 输出 0.1.5-rc.2；24.0.0 / 24.1.0 输出明确的 does not provide import.meta.main 错误并返回非零。

---

附：本次报告者的原始现象

Node v24.1.0 上：

$ pnpm run build
$ tsx scripts/build.ts        ← 到这里结束，无产物，exit 0

$ pnpm dsh web
$ node --import tsx/esm apps/cli/src/bin.ts web
                              ← 到这里结束，无输出，exit 0

切到 Node 24.21.0 后同一工作区：pnpm run build → build: recorded 234 client artifact(s)，pnpm dsh web → dsh web: http://127.0.0.1:3080/?token=... 并正常常驻。这与上表完全一致。

（另：排查过程中还遇到 #5100 描述的残留目录问题 —— 已从仓库删除但无 package.json、不被 pnpm run clean 识别的
packages/host/apiproxy、packages/session/session-persistence-sqlite 会让 tsdown 报误导性的 MISSING_EXPORT。删除
后构建才通过。此事已在 #5100 单独记录，本 PR 不重复处理。）

两点说明：

- 数据来源：上表的每个数字都是我在本机真实跑出来的（逐一装了 Node 22.19.0 / 24.0.0 / 24.1.0 / 24.2.0 / 24.3.0 / 24.4.0
  / 24.9.0 / 24.19.0 / 26.8.1 对比同一份产物），不是从 changelog 推断的。import.meta.main 的 24.2 分界我没找到上游
  release note，文中已如实标注，避免误导维护者。
- 本建议基于 DeepSeek/DeepSeek-v4.1-Flash 模型产出

[Robin1987China]

独立复验：我在已发布的 npm 包上确认了同一结论 —— 与你测的仓库构建（tsx）路径是不同表面，结论一致。

1) 端用户侧同样成立

用真实 Node 二进制直接跑 @deepseek-ai/dsh@0.1.5-rc.1 的 lib/bin.js：

Node	import.meta.main	lib/bin.js --version
24.1.0	undefined	（无输出，exit 0）
24.2.0	true	0.1.5-rc.1

分界同样落在 24.2.0。所以 npx @deepseek-ai/dsh web 的静默退出与你的构建侧是同一根因。

2) 一处需要修正的细节：发布包根本没有 engines

你写 engines.node 为 ^22.19.0 || >=24.0.0 —— 那是仓库根 package.json。
但已发布的 @deepseek-ai/dsh@0.1.5-rc.1 的 package.json 里 engines 是 undefined：

$ node -e "const p=require('@deepseek-ai/dsh/package.json'); console.log(p.engines)"
undefined

所以「把它们移出 engines 范围」在消费侧还差一步 —— 那里没有 engines 可移，需要先加上。
这与 #6115 里「apps/cli/package.json 完全没有 engines」的观察一致，也解释了为什么
npm install 全程无任何告警。

3) 这也确认了守卫是端用户侧的唯一阻塞点

入口已经导出 runCli()，而 runCli() 读 process.argv.slice(2)。我用这一点做了个桥：
import 同一个入口、自己调用 runCli()，参数原样透传。

• 24.1.0：先打印诊断，然后正常输出 0.1.5-rc.1
• 24.2.0 / 26.7.0：完全静默，无噪音
• 不会重复执行：启动器是主模块时，bin.js 看到的 import.meta.main 是 false

桥：npx dsh-node-compat web · https://github.com/Robin1987China/dsh-node-compat
（它只让今天的部署可用，不是修复 —— 修复仍在入口守卫本身。）

我完全支持这个提案

尤其是「让失败可见」这一半：静默 exit 0 是这次问题里最贵的部分 —— 它把定位成本从
「读一行错误」推高到「二分法猜」。另外你那句二次伤害的观察很关键：pnpm run build
静默成功会留下看似已构建的残缺工作区，把后续排查引向错误方向。