zx 已知问题深度解析：子进程输出截断与颜色失效的成因及修复方案

zx（A tool for writing better scripts）通过 await $cmd`` 在 JavaScript 中直接执行 Shell 命令，但命令的执行发生在 Node 进程派生的子进程里，I/O 行为与交互式终端存在差异。本文基于仓库文档 known-issues.md 中记录的两个典型问题展开：子进程输出被截断、子进程不显示颜色。读完你会理解这两个现象的底层机制，并掌握 process.exitCode、临时文件中转、FORCE_COLOR 环境变量、zx 的 stdio 配置等具体修复手段。

问题一：子进程输出被截断

现象与成因

这是 Node.js 中 console.log() 的已知行为（对应上游 issue nodejs/node#6379）：console.log() 写终端（TTY）和写文件（pipe 等）的缓冲策略不同。当被 zx 捕获的子进程通过管道输出时，console.log() 的写入是有缓冲的；如果该进程在缓冲尚未刷新时直接调用 process.exit()，进程会立即终止，缓冲区里未刷出的输出就被截断丢失。

结合 zx 的默认配置可以更好地理解为什么这个问题在 zx 场景中容易触发：在 src/core.ts 中，zx 的默认选项将 stdio 设为 'pipe'（第 142 行），并且该值在 ProcessPromise.run() 中直接传给底层 spawn 调用（src/core.ts）。也就是说，await $cmd`` 的子进程默认就不持有 TTY，其 stdout/stderr 全部以管道形式回流给 zx 做采集与日志（on.stdout / on.stderr 回调，见 src/core.ts）。因此"管道输出 + process.exit() 提前退出"恰好构成截断的两个必要条件。

方案一：用 process.exitCode 替代 process.exit()

官方文档给出的首选修复：不要在业务进程里直接 process.exit(1)，而是设置 process.exitCode = 1，让进程在事件循环自然排空、缓冲正常刷新后再自行退出。文档同时提到，对于无法改动业务代码的场景，可以使用类似 npm 包 exit 的工具，它在退出前主动刷新 stdout 缓冲。

这条建议在本仓库自身就有实证：测试夹具 test/fixtures/exit-code.mjs 正是通过 process.exitCode = 42 来传递退出码，而 test/cli.test.js 验证了 zx 侧能正确读取到该退出码：

const p = await $`node build/cli.js test/fixtures/exit-code.mjs`.nothrow()
assert.equal(p.exitCode, 42)

在 zx 中读取退出码也很直接：ProcessPromise 暴露了 exitCode getter（src/core.ts），命令失败时也可配合 .nothrow() 拿到 ProcessOutput.exitCode，用于判断是"预期失败"还是"异常失败"。

方案二：写临时文件中转

当无法控制子进程内部行为（例如第三方工具在 process.exit() 前必然截断输出）时，文档给出的 workaround 是把输出重定向到临时文件，绕开进程退出时的缓冲竞争：

const tmp = await $`mktemp` // 创建临时文件
const { stdout } = await $`cmd > ${tmp}; cat ${tmp}`

原理是：cmd 的 stdout 写入文件时由内核负责落盘，不经过进程内存缓冲；cmd 退出后再用 cat 把文件内容读出来，此时 zx 捕获到的 stdout 就是完整的。模板字符串中的 ${tmp} 会经过 zx 的引号处理安全注入，mktemp 的输出（文件路径）作为下一段命令的参数被自动传递。

排查建议

• 若某个 await $`` 命令的输出偶尔缺尾部内容，优先检查该命令内部是否存在 process.exit()` 调用；
• 将 process.exit(code) 替换为 process.exitCode = code，是最无侵入的修复；
• 无法改动命令实现时，使用临时文件中转；对输出较大的场景注意 cat 一次性读入内存的开销。

问题二：子进程不显示颜色

现象与成因

很多 CLI 工具（如 git、tsc、构建工具）会检测输出流是否为 TTY：是终端就输出带 ANSI 颜色码的输出，是管道就输出纯文本。由 src/core.ts 可以看到，zx 默认 stdio: 'pipe'，子进程的 stdout 是管道而非终端，所以这些工具自动关闭了颜色——你在终端直接运行 cmd 看到的彩色输出，在 await $cmd`` 中就不复存在了。

这属于正常行为而非 bug：颜色是否输出由子进程自行决定，zx 只是忠实地把管道内容收集起来。

方案一：FORCE_COLOR 强制着色

大多数支持颜色检测的 CLI 工具都提供强制开启颜色的环境变量。文档给出的通用做法：

process.env.FORCE_COLOR = '1'
await $`cmd`

在 zx 中，zx 的默认 env 就是 process.env（见 src/core.ts），子进程会继承当前进程的环境变量，因此只需在调用前设置即可生效。如果只想对个别命令生效，也可以用 zx 的选项方式传入：await $({ env: { ...process.env, FORCE_COLOR: '1' } })cmd``，避免污染全局环境。

方案二：改用 inherit，让子进程直连终端

从源码结构看，zx 的 stdio 选项支持 Node.js ChildProcessOptions['stdio'] 的完整取值，并且 ProcessPromise 提供了链式的 stdio() 配置器（src/core.ts）：

stdio(stdin, stdout = 'pipe', stderr = 'pipe')

该配置值最终透传给底层 spawn（src/core.ts）。因此可以推断，将输出切回 'inherit' 可以让子进程直接继承父进程的终端描述符，颜色自然恢复：

// stdout 继承终端，stderr 仍由 zx 捕获
await $`cmd`.stdio('inherit', 'inherit', 'pipe')

需要注意的权衡：inherit 之后 zx 不再捕获该路输出，{ stdout, stderr } 解构将拿不到对应内容，日志回放、.json() 解析等能力也随之失效。所以实际取舍通常是：

• 需要解析或校验命令输出 → 保持默认 pipe，用 FORCE_COLOR 让子进程"以为"自己在终端里；
• 纯粹为了给用户看彩色过程输出（如交互式安装器）→ 使用 stdio('inherit', 'inherit', 'inherit') 直接透传终端。

小结与排查路径

现象	根因	首选修复	备选方案
`await $`` 输出缺尾部内容	管道输出有缓冲，子进程 process.exit() 提前终止	子进程内改用 process.exitCode	临时文件中转：mktemp + 重定向 + cat
子进程无颜色	默认 stdio: 'pipe'，子进程检测不到 TTY	设置 FORCE_COLOR 环境变量	stdio('inherit') 透传终端（代价是丢失输出捕获）

两个问题的共同根源都在于：await $cmd`` 的子进程运行在"管道 I/O"环境中，与交互式终端的 I/O 语义不同。理解这一点后，遇到类似"输出不完整""行为与终端不一致"的问题时，可以按"检查子进程退出方式 → 检查 TTY 依赖的行为（颜色、进度条、交互提示）"的顺序排查，并在 src/core.ts 中对照 stdio、env 等默认选项确认 zx 侧的实际透传行为。更多 zx 的 API 细节可参考 process-promise.md 与 shell.md。