zx 的 Shell 集成机制：Bash 与 PowerShell 的协作、切换与底层实现

本文围绕 zx 官方文档 Shell 指南 展开：zx 并非要用 JavaScript 取代 Bash，而是在 Bash 之上补齐并行执行、数据变换、异常处理与循环逻辑等脚本能力。读完本文，你将掌握 zx 三种切换 Shell 的方式（useBash/usePwsh/usePowerShell 函数、JS API、CLI 参数与环境变量）、默认 Shell 的初始化机制，以及参数引用（quoting）在不同 Shell 下的差异，并能编写可复制运行的多仓库并行克隆等实战脚本。

定位：增强 Bash，而不是替代 Bash

Bash 是 Unix 生态的基石，提供了丰富的内置命令、运算符与进程控制原语，也是脚本与自动化任务的事实标准。它本身就具备精细调优的能力：命令别名（aliases）、上下文预设、自定义函数、环境变量注入等。

zx 的设计目标很明确——不替代 bash，而是用 JavaScript 的能力增强它。文档列出的四项增强正是 Shell 脚本的长期痛点：

增强能力	Shell 脚本中的对应痛点
并行执行（Parallel execution）	Bash 原生并行需依赖 & + wait，结果难以收集
数据变换（Data transformations）	依赖 awk/sed 拼接，可读性差
异常处理（Exception handling）	只能靠 $? 判断退出码
条件逻辑与循环（Conditional logic and loops）	if/for 语法繁琐，难以表达复杂数据结构

实战示例：并行克隆多个仓库

以下示例完整继承自 docs/shell.md，演示了如何用 zx 并行克隆多个仓库、收集失败项、并将每个进程的输出落盘：

#!/usr/bin/env zx
import { $ } from 'zx'

$.nothrow = true

const repos = ['zx', 'webpod']
const clones = repos
  .map(n => $`git clone https://github.com/google/${n} ${n}-clone`)

const results = await Promise.all(clones)
const errors = results.filter(o => !o.ok).map(o => o.stderr.trim())
console.log('errors', errors.join('\n'))

for (p of clones) {
  await p.pipe`cat > ${p.pid}.txt`
}

逐段解析这段脚本，可以看到 zx 对 Bash 能力边界的具体延伸：

1. $.nothrow = true：默认情况下子进程非零退出会让 zx 抛出异常；置为 nothrow 后进程失败只体现在 ProcessOutput.ok === false 上，适合"批量执行 + 事后汇总"的场景。nothrow 是 $ 对象的全局选项之一，定义在 src/core.ts 的 Options 接口中。
2. $ 模板字符串即 Promise：repos.map(n => $git clone ...) 一行就会同时发起所有克隆——Shell 里 & 后台执行无法做到这种"结果可收集"的并行，而 zx 中每条 $ 调用返回一个 ProcessPromise，天然可被 Promise.all 聚合。
3. 结构化错误收集：results.filter(o => !o.ok).map(o => o.stderr.trim()) 用一行 JS 替代了 Shell 中"逐个判断退出码 + 解析 stderr"的繁琐逻辑；stderr、ok 都是 ProcessOutput 的标准字段。
4. p.pipe 管道：await p.pipecat > ${p.pid}.txt`` 将该进程的输出（含 stderr）通过管道交给另一条命令，p.pid 则用于为每个仓库生成独立的输出文件名。

默认 Shell：模块加载时自动切换为 Bash

从源码看，zx 对"默认使用 Bash"这件事有显式的初始化逻辑。在 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) {}

模块加载时 zx 先调用 useBash() 建立 Bash 预设，再把用户在加载前已配置好的 shell/prefix/postfix 恢复回去。这意味着：

• 若你通过 环境变量 在进程启动前设置了 ZX_SHELL，$ 的初始值会来自 process.env，useBash() 不会覆盖它；
• 若 which.sync('bash') 找不到 bash 二进制（例如精简容器），try/catch 会静默吞掉错误，$.shell 保持默认值 true（见 src/core.ts 中 defaults.shell = true），此时需要用户显式指定 Shell，否则执行命令会抛出 shell 相关的错误——test/core.test.js 中有对应的断言用例：$.shell = undefined 后执行命令会抛出匹配 /shell/ 的异常。

useBash 与 PowerShell 切换函数集中定义在 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 存的是解析后的二进制绝对路径（如 /bin/bash、C:\...\pwsh.exe），而不是命令名字符串。这也解释了为什么直接赋值 $.shell = '/bin/zsh' 可以工作——它就是一个 spawn 时使用的可执行文件路径。
• Bash 预设的 prefix：useBash() 会设置 $.prefix = 'set -euo pipefail;'，即每条命令实际以 set -euo pipefail; <cmd> 的形式执行。set -e（出错即停）、set -u（使用未定义变量报错）、set -o pipefail（管道中任一命令失败则整体失败）——这正是资深 Bash 用户的"严格模式"惯例，zx 替你自动加上了。
• PowerShell 预设的 postfix：'; exit $LastExitCode' 用于修正 PowerShell 的一个重要差异——很多 PowerShell 命令失败时并不改变 $? 退出码（只写入 $LastExitCode），zx 通过在每条命令后显式 exit 该变量，保证 zx 拿到的进程退出码与命令真实结果一致。

这三个函数对应的行为在 test/core.test.js 的 "shell presets" 测试组中被逐条验证：usePwsh() 后 $.shell === 'pwsh'、$.prefix === ''、$.postfix === '; exit $LastExitCode'、$.quote === quotePowerShell；useBash() 后 $.prefix === 'set -euo pipefail;'、$.quote === quote。

参数引用（quoting）：Bash 与 PowerShell 的另一处差异

setShell 中切换的 $.quote 决定了模板字符串插值（如 $`echo ${path}`）中变量如何被转义成合法的 Shell 参数。两种实现都在 src/util.ts：

export function quote(arg: string): string {
  if (arg === '') return `$''`
  if (/^[\w/.\-+@:=,%]+$/.test(arg)) return arg

  return (
    `$'` +
    arg
      .replace(/\\/g, '\\\\')
      .replace(/'/g, "\\'")
      .replace(/\f/g, '\\f')
      .replace(/\n/g, '\\n')
      .replace(/\r/g, '\\r')
      .replace(/\t/g, '\\t')
      .replace(/\v/g, '\\v')
      .replace(/\0/g, '\\0') +
    `'`
  )
}

export function quotePowerShell(arg: string): string {
  if (arg === '') return `''`
  if (/^[\w/.\-@:=,+%]+$/.test(arg)) return arg

  return `'` + arg.replace(/'/g, "''") + `'`
}

• Bash 的 quote() 使用 POSIX 的 ANSI-C 引用语法 $'...'：对空字符串返回 $''，对只含 \w/.\-+@:=,% 的安全字符直接原样输出，否则转义反斜杠、单引号与各类控制字符（\f \n \r \t \v \0）；
• PowerShell 的 quotePowerShell() 则使用单引号字符串语义，内部单引号按 PowerShell 规则双写为 ''。

$.quote 是可替换的选项（src/core.ts 中 quote?: typeof quote），test/util.test.js 对两者的边界行为（空串、特殊字符、安全字符集合）有直接断言。

切换 Shell 的三种方式

docs/shell.md 给出的三种方式在优先级和适用场景上各有不同。

方式一：预设函数（适合脚本内按需切换）

import { $, usePwsh } from 'zx'

usePwsh() // 或 usePowerShell() / useBash()
await $`Get-ChildItem`

• useBash()：切换回 bash（并恢复 set -euo pipefail; 前缀）；
• usePowerShell()：使用 Windows PowerShell（powershell.exe，v5）；
• usePwsh()：使用 pwsh（PowerShell v7+，跨平台）。

这三个函数同时被暴露到全局环境（src/globals.ts），因此在使用 zx 命令执行脚本时可以不导入直接调用。

方式二：JS API 直接赋值（最灵活）

$.shell = '/bin/zsh'

赋任意可执行路径即可——zsh、dash、fish 或自编译的 Shell 都可以。由于 $.shell 就是传给子进程 spawn 的 Shell 路径（见 src/core.ts 中 shell: isString($.shell) ? $.shell : true 的选项组装逻辑），任何能被当前系统直接执行的 Shell 二进制都可行。

方式三：CLI 参数与环境变量（不改代码）

zx --shell /bin/zsh script.js

ZX_SHELL=/bin/zsh zx script.js

--shell 在 src/cli.ts 中被声明为字符串类型参数，随后在 main() 中写入 $.shell = argv.shell；--prefix/--postfix 同样是命令行可配置项（src/cli.ts）。按 docs/cli.md 的约定，所有 CLI 选项均可用 ZX_ 前缀环境变量替代，因此 CI 中可以这样写：

steps:
  - name: Run script
    run: zx script.mjs
    env:
      ZX_VERBOSE: true
      ZX_SHELL: '/bin/bash'

docs/cli.md 的 "Environment variables" 一节正是这个 YAML 示例的出处；--shell 本身的用法与 ZX_SHELL 用法在 docs/cli.md 中有说明。test/cli.test.js 中 supports --shell flag 用例验证了该参数确实生效（--verbose 模式下 stderr 会打印出脚本内的 $.shell 值）。

Windows 环境的注意事项

docs/setup.md 的 "Bash" 一节明确说明：zx 依赖 bash 作为默认执行环境，若在 Windows 上使用，建议安装 Windows Subsystem for Linux（WSL）或 Git Bash 以提供 bash 二进制；也可以直接调用 usePowerShell() 或 usePwsh() 切换到 PowerShell 预设。这与上文源码分析一致——usePwsh()/usePowerShell() 会同时切换 shell、postfix 与 quote 三项，保证 Windows 下退出码传递与参数转义都符合 PowerShell 的语义。

小结：zx = bash + js

• 默认路径：模块加载时自动执行 useBash()，解析 bash 二进制并注入 set -euo pipefail; 严格模式前缀（src/core.ts）；
• 增强点：$ 返回的 ProcessPromise 让 Bash 命令具备 Promise 语义，天然支持 Promise.all 并行、try/catch 异常处理、循环与数据变换，这是纯 Shell 脚本难以企及的表达力；
• 切换手段：脚本内用 useBash()/usePwsh()/usePowerShell()，或赋值 $.shell；不改代码时用 zx --shell=<path> 或 ZX_SHELL 环境变量；
• 跨 Shell 正确性：由 $.prefix/$.postfix/$.quote 三件套保证——Bash 侧注入严格模式，PowerShell 侧补上 exit $LastExitCode 修正退出码，参数引用则分别走 quote()（ANSI-C 引号）与 quotePowerShell()（单引号双写），相关行为均有测试覆盖（test/core.test.js、test/util.test.js、test/cli.test.js）。

正如 docs/shell.md 结尾所总结的："No compromise, take the best of both"——把 Bash 的执行引擎与 JavaScript 的编程能力拼在一起，是 zx 在脚本工具中的核心取舍。