zx v8 迁移指南：四项破坏性变更的完整拆解与源码级应对方案

zx 8.0.0 在带来大量特性与优化的同时引入了若干破坏性变更。本文基于官方迁移文档 docs/migration-from-v7.md，逐项讲解 $.verbose/$.quiet 日志行为变化、ssh API 移除、Windows 默认 Shell 调整与进程 cwd 同步关闭这四个变更点，并结合当前仓库（package.json 中版本为 8.9.0）的源码与测试用例，给出每项变更的底层实现原理、验证依据和可直接复用的 v7 兼容恢复配置，帮助你在升级后以最小改动让既有脚本继续运行。

破坏性变更总览

v8 的破坏性变更集中在四个方向，整体原则是"默认行为更克制，旧行为可通过显式开关恢复"：

#	变更点	v7 行为	v8 默认行为	恢复 v7 行为的方式
1	日志输出	$.verbose 默认为 true，命令执行过程全部打印	$.verbose 默认为 false，仅错误仍输出到 stderr	设置 $.verbose = true
2	远程执行	内置 ssh API	已移除	安装并使用独立的 webpod 包
3	Windows 默认 Shell	自动寻找 PowerShell	不再寻找 PowerShell，回退到 Node 默认 Shell（Windows 上为 cmd）	调用 usePowerShell() / usePwsh()
4	cwd 同步	$ 调用之间自动同步进程 cwd	默认关闭	调用 syncProcessCwd()

v7 目前处于维护模式，不再接收新特性增强，官方迁移文档明确建议升级到最新版本。下面逐项展开。

变更一：$.verbose 默认值反转与 $.quiet 的引入

行为变化

v7 中 $.verbose 默认开启，所有命令、输出都会回显到终端；v8 将默认值反转为 false。但注意：静默不等于吞掉错误——命令的 stderr（尤其是失败信息）依然会打印到终端，只有主动设置 $.quiet = true 才会完全关闭日志输出：

$.verbose = true // everything works like in v7

$.quiet = true   // to completely turn off logging

源码印证

默认值定义在 src/core.ts 的 defaults 对象中，可以确认 v8 的基线配置：

export const defaults: Options = resolveDefaults({
  [CWD]:          process.cwd(),
  [SYNC]:         false,
  verbose:        false,   // ← v7 中为 true
  ...
  quiet:          false,
  ...
})

verbose 与 quiet 的优先级关系由 src/core.ts 中的状态检查方法定义：

isQuiet(): boolean {
  return this._snapshot.quiet
}

isVerbose(): boolean {
  return this._snapshot.verbose && !this.isQuiet()
}

从源码结构看，quiet 的优先级高于 verbose：即使 verbose 为 true，只要 quiet 开启，isVerbose() 也返回 false，即"完全静默"是绝对约束。

实际输出路径在 src/core.ts 的执行回调中可以清楚看到三条通道的差异：

on: {
  start: () => {
    // 命令回显：受 verbose 控制
    $.log({ kind: 'cmd', cmd: $.cmd, cwd, verbose: self.isVerbose(), id })
  },
  stdout: (data) => {
    // stdout 回显：受 verbose 控制，且被 pipe 时不打印
    $.log({ kind: 'stdout', data, verbose: !self._piped && self.isVerbose(), id })
  },
  stderr: (data) => {
    // stderr：只要不 quiet 就打印 —— 这就是"错误仍输出到 stderr"的来源
    $.log({ kind: 'stderr', data, verbose: !self.isQuiet(), id })
  },
  ...
}

这解释了文档中"errors are still printed to stderr"的实现机制：stderr 通道只受 quiet 门控，不受 verbose 门控。

此外，这两个开关也可以按单次调用粒度使用（见 src/core.ts 的配置器方法），迁移时若只想静默个别命令而非全局静默，这是更精细的替代方案：

const out = await $.quiet() `huge-command`   // 仅本次调用静默
const dbg = await $.verbose() `make build`   // 仅本次调用回显

值得注意的还有 src/core.ts 中的 ENV_OPTS 集合同时包含 'verbose' 与 'quiet'，配合前缀常量 ENV_PREFIX = 'ZX_'，从源码结构看这两个选项也支持通过 ZX_VERBOSE / ZX_QUIET 环境变量预设，适合在 CI 环境中不改代码地调整日志行为。

变更二：ssh API 被移除，迁移到 webpod

v7 曾内置 ssh API 用于远程命令执行，v8 将其整体移除，官方方案是改用独立的 webpod 包。迁移文档给出的对照写法如下——除导入来源外，模板字符串调用风格基本保持一致：

// v7: import {ssh} from 'zx'  ↓ 移除

// v8: 改用 webpod
import {ssh} from 'webpod'

const remote = ssh('user@host')
await remote`echo foo`

迁移步骤：

1. 在项目中安装 webpod（npm 包名，仓库只读，此处仅说明安装方式）：npm install webpod；
2. 全局搜索 import {ssh} from 'zx' 或 require('zx').ssh，将导入来源改为 'webpod'；
3. ssh(host) 返回的仍是可调用模板字符串的执行器，remoteecho foo`` 这类远程执行代码无需改写。

这一变更的合理性可以从 v8 的整体方向推断：zx 的核心定位是"本机 shell 脚本引擎 + 进程管理"，远程 SSH 执行属于垂直能力，拆分为独立包（webpod 系列）后主包体积更小、边界更清晰——这也是官方在迁移文档中强调升级后体积大幅缩减的原因之一。

变更三：Windows 上不再自动寻找 PowerShell

v7 在 Windows 平台上会优先寻找 PowerShell 作为执行 Shell；v8 取消了这一自动探测，默认回退到 Node child_process 的默认 Shell（Windows 上即 cmd）。如果你依赖 PowerShell 语法（如 $LastExitCode、管道语义），需要显式启用。

三个 Shell 切换助手

官方提供三个助手函数覆盖不同目标（另见 docs/shell.md 的说明）：

import { usePowerShell, useBash } from 'zx'

usePowerShell() // 启用经典 PowerShell（powershell.exe）
useBash()       // 切换回 bash，v8 默认推荐

若你的环境已升级到现代 PowerShell v7+（跨平台的 pwsh），应使用 usePwsh()：

import { usePwsh } from 'zx'

usePwsh()

源码实现：一次调用切换四组配置

这三个助手的实现非常简短，集中在 src/core.ts：

export const useBash = (): void => setShell('bash', false)
export const usePwsh = (): void => setShell('pwsh')
export const usePowerShell = (): void => setShell('powershell.exe')
function setShell(n: string, ps = true) {
  $.shell = which.sync(n)
  $.prefix = ps ? '' : 'set -euo pipefail;'
  $.postfix = ps ? '; exit $LastExitCode' : ''
  $.quote = ps ? quotePowerShell : quote
}

从中可以读出三个关键细节：

• which.sync(n) 做路径解析：助手并非硬编码路径，而是动态定位可执行文件。若目标 Shell 不存在，这里会失败——测试用例 test/core.test.js 正是因此对 which.sync 做了打桩；
• PowerShell 分支追加 postfix：'; exit $LastExitCode' 保证 PowerShell 的退出码能正确传递回 zx 的进程退出码判断（PowerShell 不总是自动传播管道中最后一条命令的失败状态）；
• 引号函数成对切换：quote 与 quotePowerShell 分别对应不同 Shell 的转义规则，定义在 src/util.ts。bash 分支使用 $'...' 形式并转义反斜杠、单引号与控制字符；PowerShell 分支则用单引号包裹并将内部单引号翻倍为 ''。引号函数与 Shell 必须配套，这正是"切换 Shell 必须用助手而不是只改 $.shell"的原因——setShell() 保证了 shell/prefix/postfix/quote 四者原子性地一起切换。

模块加载时的默认行为在 src/core.ts：

try {
  const { shell, prefix, postfix } = $
  useBash()
  if (isString(shell)) $.shell = shell
  if (isString(prefix)) $.prefix = prefix
  if (isString(postfix)) $.postfix = postfix
} catch (err) {}

从源码结构看，v8 启动时先尝试 useBash() 建立基线，再尊重用户通过环境变量等渠道预设的 shell/prefix/postfix；若 bash 不存在则静默回退，配合 src/core.ts 中 shell: isString($.shell) ? $.shell : true 的判断——$.shell 保持 true 时最终交由 Node 默认 Shell 执行，这正是 Windows 上落到 cmd 的路径。

测试用例 test/core.test.js 固化了每个助手的预期结果，可作为升级后的行为基线：

test('usePwsh()', () => {
  usePwsh()
  assert.equal($.shell, 'pwsh')
  assert.equal($.prefix, '')
  assert.equal($.postfix, '; exit $LastExitCode')
  assert.equal($.quote, quotePowerShell)
})

test('useBash()', () => {
  useBash()
  assert.equal($.shell, 'bash')
  assert.equal($.prefix, 'set -euo pipefail;')
  assert.equal($.postfix, '')
  assert.equal($.quote, quote)
})

注意 useBash() 还会注入 set -euo pipefail; 作为 prefix，等价于 bash 的严格模式（出错即停、未定义变量报错、管道任一环节失败即失败），这是 v8 对 bash 场景的默认加固。

全局环境下的访问方式

如果脚本使用 import 'zx/globals' 风格，上述助手同样作为全局变量暴露，见 src/globals.ts：

var syncProcessCwd: typeof _.syncProcessCwd
...
var usePowerShell: typeof _.usePowerShell
var usePwsh: typeof _.usePwsh
var useBash: typeof _.useBash

此外 Shell 也可以不走助手直接指定，例如 $.shell = '/bin/zsh'，或通过 CLI/环境变量（ZX_SHELL）配置，详见 docs/shell.md 与 docs/cli.md。

变更四：进程 cwd 同步默认关闭

背景：v7 的隐式同步问题

v7 中，cd() 或 $.cwd 修改工作目录后，zx 会通过异步钩子持续把 Node 进程的 process.cwd() 拉回 zx 内部记录的值，使得后续任意 $ 调用"看起来"都在同一目录。这个隐式同步在并发场景下很危险：多个 within() 上下文并发执行时，共享的进程级 cwd 会互相干扰。v8 将其默认关闭，改为显式控制。

显式恢复 v7 行为

import { syncProcessCwd } from 'zx'

syncProcessCwd() // restores legacy v7 behavior

源码实现：基于 AsyncHook 的全生命周期钩子

实现位于 src/core.ts：

let cwdSyncHook: AsyncHook

export function syncProcessCwd(flag: boolean = true) {
  cwdSyncHook =
    cwdSyncHook ||
    createHook({
      init: syncCwd,
      before: syncCwd,
      promiseResolve: syncCwd,
      after: syncCwd,
      destroy: syncCwd,
    })
  if (flag) cwdSyncHook.enable()
  else cwdSyncHook.disable()
}

function syncCwd() {
  if ($[CWD] != process.cwd()) process.chdir($[CWD])
}

几个可确认的实现事实：

• 钩子挂在 Node async_hooks 的全部五个生命周期事件上（init/before/promiseResolve/after/destroy），即"在几乎每个异步操作边界都检查一次 cwd"，这是 v7 隐式同步的完整等价物；
• 钩子惰性创建（cwdSyncHook || createHook(...)），首次调用时才付出创建成本；
• syncProcessCwd 接受布尔参数，syncProcessCwd(false) 即可运行时关闭——这在测试清理中很常见，例如 test/core.test.js 的 finally 块就调用了 syncProcessCwd(false) 还原现场；
• syncCwd() 内部只在 $[CWD]（zx 记录的目录，由 src/core.ts 中 cd() 在 process.chdir 后更新）与 process.cwd() 不一致时才真正执行 process.chdir，避免无谓的系统调用。

测试用例 test/core.test.js（标题为 "does not affect parallel contexts"）验证了开启同步后，多个 within() 并发上下文的 cwd 互不污染：其中一个上下文 cd() 到子目录，另外两个并发上下文的 process.cwd() 保持不变——这正是该机制与 within() 隔离设计配合后的预期行为，也说明显式开启同步并不等于回到 v7 的并发隐患，因为 zx 的状态本身是上下文隔离的。

cd() 函数本身（src/core.ts）同时接受字符串和 ProcessOutput（如 cd(await $mktemp -d)），并会同步更新 zx 内部记录 $[CWD]，这是 cwd 同步钩子的数据源。

迁移检查清单

按顺序执行即可将 v7 脚本平滑升级到 v8（当前仓库代码库对应 package.json 中的 8.9.0，Node 要求 >= 12.17.0）：

1. 日志行为：若脚本依赖命令回显做人工审查，在入口加 $.verbose = true；若依赖完全静默（如作为库被调用），确认使用 $.quiet = true 而非仅关 verbose。
2. ssh 调用：全库检索 ssh 导入，改从 webpod 安装与导入，调用语法不变。
3. Windows 脚本：若命令含 PowerShell 专有语法（$env:、$LastExitCode、PowerShell 管道），在脚本顶部显式调用 usePowerShell() 或 usePwsh()；纯 POSIX 语法则保持默认即可，跨平台脚本建议 useBash() 保证严格模式前缀一致。
4. cwd 依赖：若脚本存在"在任意位置执行命令都默认落在 cd() 后的目录"的 v7 依赖，调用 syncProcessCwd() 恢复；否则建议显式使用 $.cwd 或每次 cd()，避免隐式全局状态。
5. 回归验证：可参考仓库测试基线——test/core.test.js 验证 Shell 助手副作用，test/export.test.js 验证 core/index 入口均导出 syncProcessCwd、useBash、usePowerShell、usePwsh，升级后可据此核对 API 完整性。

为什么值得升级

v7 已进入维护模式，不再获得新特性。官方迁移文档将 v8 概括为体积大幅缩减（其引用的发布说明称体积约为 v7 的 1/16）、更快、更安全，并适用于更广的实战场景。从本文源码走读也能印证这一方向：默认配置集中在 src/core.ts 一处统一管理，Shell 切换、cwd 同步、日志开关都被设计为"显式、原子、可测"的独立单元——这正是旧脚本升级后能获得的最大收益：行为更可预测，并发与静默场景下不再依赖隐式全局副作用。