Execa 实战指南：在 Node.js 中优雅执行 Shell 命令
Execa 是 Node.js 执行子进程的最佳封装：Promise API、跨平台、详细错误报告、流式处理与管道。本文讲解核心用法、错误处理、流处理与同步模式。
Execa 用 Promise 封装子进程执行：await execa('git', ['status']) 返回结构化结果（stdout/stderr/exitCode），命令失败自动抛带完整上下文的错误。它修好了 child_process 的全部痛点：跨平台一致、参数数组防注入、输出自动捕获。
为什么不用原生 child_process
原生模块的问题：回调与流 API 绕口、Windows 行为不一致、错误信息简陋、容易写出命令注入（字符串拼接）。Execa 是社区打磨十年的答案——zx、npm 自己都在用。
基本用法
const { execa } = require('execa');
// 参数数组形式：天然防注入
const { stdout } = await execa('git', ['log', '--oneline', '-5']);
console.log(stdout);
// 模板字面量形式（更方便，注意变量自动转义）
const { stdout: branch } = await execa`git branch --show-current`;
参数永远用数组或模板字面量传递——用户输入拼进命令字符串是注入漏洞的经典入口，Execa 的 API 设计把正确做法变成默认路径。
返回值与错误处理
try {
const result = await execa('some-command', ['--flag']);
result.stdout; // 标准输出（已 trim）
result.stderr; // 标准错误
result.exitCode; // 退出码
result.command; // 完整命令（便于日志）
} catch (error) {
error.exitCode; // 非零退出码
error.stderr; // 失败时的错误输出
error.shortMessage; // 精简错误信息
error.isCanceled; // 是否被取消
}
非零退出即抛异常——配合 try/catch 的错误处理与正常流程彻底分离。
常用选项
await execa('node', ['script.js'], {
cwd: '/path/to/dir', // 工作目录
env: { NODE_ENV: 'production' }, // 附加环境变量
input: 'stdin 内容', // 写入 stdin
timeout: 5000, // 超时自动终止
maxBuffer: 10 * 1024 * 1024, // 输出缓冲上限
reject: false, // 非零退出不抛异常
shell: true, // 需要 shell 特性（管道符等）时开启
});
流式处理与管道
大输出不该攒在内存：
const subprocess = execa('ffmpeg', ['-i', 'in.mp4', 'out.mp4']);
subprocess.stdout.pipe(process.stdout); // 实时转发输出
await subprocess;
// 命令管道：前一个的输出接后一个的输入
const { stdout } = await execa('cat', ['app.log'])
.pipe('grep', ['ERROR'])
.pipe('wc', ['-l']);
同步模式
脚本场景（构建、发布工具）用同步版更直白：
const { execaSync } = require('execa');
execaSync('npm', ['run', 'build'], { stdio: 'inherit' });
stdio: 'inherit' 让子进程输出直接打到当前终端——跑构建命令时保持日志可见。
常见问题（FAQ）
Q：Execa 和 zx 怎么选？
zx 更偏"用 JS 写 shell 脚本"（内置 $cmd、cd、fetch 等便捷全局）；Execa 是纯粹的进程执行库，适合作为应用/工具的底层依赖。写一次性脚本 zx 更爽，写产品代码 execa 更稳。
Q：如何取消正在执行的命令？
const sub = execa(...); sub.kill() 或配合 AbortController：execa('cmd', { signal: abortController.signal })。超时场景直接用 timeout 选项自动取消。
Q：为什么我的命令在 execa 里找不到？
Execa 默认增强 PATH 解析（含 node_modules/.bin），但 GUI 启动的进程环境变量可能与终端不同。用 which 确认命令位置，或用绝对路径、preferLocal: true 显式使用本地安装的 CLI。
参考文档
本文依据公开文档整理，示例需按项目依赖版本验证；不将文档中的性能描述视为本项目实测结果。
