写脚本的时候最烦的其实不是业务逻辑，而是跨进程调用外部命令。以前用 Node 自带的 child_process，回调套回调不说，还得自己拼参数、处理超时、盯着 stderr 发呆。后来切到 npm 的 execa 包，整个体验完全不同：Promise 化、默认收集 stdout/stderr、参数数组传递不经过 shell、超时和错误信息都给你分类好。这篇文章我不打算做成文档翻译，而是用实际项目里经常遇到的场景，把 execa 的安装、基础调用、参数解析、高级用法和踩坑记录完整过一遍。适合写 CLI 工具、脚手架、构建脚本和批量处理程序的开发者参考，Node 新手也能跟着跑通。

execa 本质上是对 child_process 的再次封装，它让“执行命令”这件事变得跟调普通函数一样自然。你只需要 await 一下，就能拿到退出码、标准输出和标准错误。不用再去监听 close、error、exit 这些事件。而且它在保持 API 简洁的同时，把进程控制、流式输出、超时取消这些细节都做得很扎实。下面从它解决了什么问题讲起。

1. 先搞清楚：execa 到底解决了什么

1.1 原生 child_process 的痛点

在没有 execa 之前，最常见的写法是这样的：

const { exec } = require('child_process'); exec('git status --porcelain', (error, stdout, stderr) => { if (error) { console.error('执行失败：', error); return; } console.log(stdout); });

exec有一个最坑的地方：它是把整条命令丢给 shell 去解释的。你的命令里如果带了路径空格、引号、环境变量，很容易在字符串拼接阶段就出错，而且报错信息往往是些含含糊糊的 shell 语法错误，排查起来非常难受。比如想传一个带空格的文件名，你得人为地再去转义一层，写出来的代码既难读又难维护。

spawn好一些，参数可以数组传递，但它默认不经过 shell，又有另一套麻烦事：你要等 stream 结束、手动监听 error、拼装 stdout 缓冲、处理退出码，代码一多全是样板。更麻烦的是，spawn不会自动帮你在 Windows 上处理.cmd和.bat的执行差异，跨平台脚本往往在这里翻车。

1.2 execa 的解决思路

execa 的设计思路很直接：把spawn的底层能力保留下来，同时给出一套更现代的表层 API。它默认走 Promise，执行完返回一个 result 对象，里面直接挂着stdout、stderr、exitCode、failed、timedOut这些字段。你不用再手动去缓冲输出，也不用再写一堆事件监听，一个await全部搞定。

它默认情况下不需要 shell，命令和参数分开传，从根本上避免了转义和注入问题。只有当确实需要 shell 特性（比如管道、通配符）时，才通过shell: true或者execaCommand显式开启。这种“安全默认 + 显式放开”的设计，非常符合现代工具链的习惯。

另外 execa 还自动处理了跨平台问题。它内部使用了一套兼容层，在 Windows 上能正确识别常见命令的.cmd包装，避免很多 ENOENT 错误。这一点在使用 git、npm、ffmpeg 这类命令时特别明显，不用每个命令都去判断平台。

2. 装好包，跑通第一段代码

2.1 安装方式与版本坑

安装就一条命令：

npm install execa

但这里有个很现实的坑：execa 从 v6 开始是纯 ESM 包，不再支持 CommonJS 的require('execa')。也就是说，如果你的项目还在用module.exports+require那一套，直接装最新版会得到ERR_REQUIRE_ESM报错。

我建议分两种情况处理：

• 项目本来就是 ESM 或者用 Vite、Next.js 这类工具链：直接装新版，import { execa } from 'execa'即可。
• 项目还是 CommonJS：要么锁版本用npm install execa@5，要么在 CJS 文件里用动态import()：

// CJS 环境下的稳妥写法 const { execa } = await import('execa');

动态import()在 async 函数里用并不麻烦，但要注意它返回的是 Promise，不能直接在顶层require式地同步调用。如果项目里大量代码都是同步的，锁execa@5可能是更省心的方案。

2.2 最简单的调用

先看一段最基础的代码：

import { execa } from 'execa'; const result = await execa('echo', ['hello world']); console.log(result.stdout); // hello world

这里echo是命令名，['hello world']是参数数组。注意我完全没有写shell: true，execa 会直接在当前进程下以子进程方式运行echo，参数原样传递。返回值result里的字段非常直观：

最舒服的一点是：默认情况下，命令退出码非 0 时，execa 会直接抛异常，你不用每次手动检查exitCode。异常对象上同样挂载了stdout、stderr、exitCode这些字段，方便在 catch 里拿到失败现场。

2.3 常用参数：cwd、env、timeout、reject

实际使用中，这几个参数出现频率最高。

cwd指定工作目录，几乎所有封装命令的函数都会用到：

const result = await execa('git', ['status', '--porcelain'], { cwd: '/path/to/project' });

env可以附加环境变量，注意它会和process.env合并：

await execa('node', ['build.js'], { env: { ...process.env, NODE_ENV: 'production', MAX_WORKERS: '4' } });

timeout是超时时间，单位毫秒。一旦超过设定时间，execa 会终止子进程并抛异常，异常对象的timedOut属性是true：

try { await execa('npm', ['install'], { timeout: 60_000 }); } catch (error) { if (error.timedOut) { console.error('npm install 超时了'); } }

reject这个参数值得单独说。默认情况下false，进程失败时抛异常；如果你希望失败时不抛、而是拿到一个带failed: true的对象，可以传{ reject: false }。这在你只想执行命令、不关心结果是否成功，或者想把成败当成可预期流程的时候特别有用，比如批量清理临时文件。

3. 实战一：把高频命令封装成函数

3.1 获取 Git 仓库的改动文件

做 CLI 工具时最典型的需求：判断一个仓库当前有哪些改动。我用git status --porcelain加 execa 封装，实现起来非常干净：

import { execa } from 'execa'; async function getGitChanges(cwd = process.cwd()) { const result = await execa('git', ['status', '--porcelain'], { cwd }); if (result.failed) { throw new Error(`git status 失败：${result.stderr}`); } return result.stdout .split('\n') .filter(Boolean) .map((line) => ({ status: line.slice(0, 2).trim(), file: line.slice(3).trim() })); } const changes = await getGitChanges('./my-project'); console.log(changes);

这里注意execa会一下子把stdout全部读进内存。对于git status这种输出不会特别大的命令，完全没问题；但如果命令输出几百 MB，就别用这种全缓冲模式，第八章的流式处理会讲替代方案。

3.2 执行打包命令并捕获输出

构建工具里经常要调用其他打包命令。用 execa 处理的时候，最好把stdout和stderr分开看，避免错误信息被忽略：

async function runBuild() { try { const result = await execa('npm', ['run', 'build'], { cwd: './frontend', timeout: 120_000 }); console.log(result.stdout); } catch (error) { console.error('构建失败：'); console.error(error.stderr || error.message); process.exit(1); } }

如果不小心把stdout和stderr混在一起，或者只想统一打印，可以用all: true。开启后，result.all会按时间顺序合并两个流，出错时定位日志会轻松很多。

3.3 超时与主动取消进程

超时不只是设置一个数字那么简单。execa 在超时后默认发SIGTERM信号终止进程。但有些进程收到SIGTERM不一定会立刻退出，比如某些长时间运行的构建工具、交互式命令。这时候可以指定更硬的信号：

await execa('npm', ['run', 'watch'], { timeout: 10_000, killSignal: 'SIGKILL' });

SIGKILL是强制终止，进程无法捕获，适合确认要立刻结束的场景。不过平时我建议优先用默认的SIGTERM，给进程一个做清理工作的机会；如果发现超时后进程还挂在那，再改成SIGKILL。

手动取消也支持。execa返回的对象本身是一个子进程引用，你可以对它调用.kill()：

const subprocess = execa('npm', ['install']); setTimeout(() => { subprocess.kill('SIGTERM'); }, 5_000); try { await subprocess; console.log('安装完成'); } catch (error) { if (error.isCanceled) { console.log('安装被手动取消了'); } }

注意error.isCanceled和error.timedOut是不同概念：前者是手动 kill，后者是超时触发。手动 kill 不会把timedOut设成 true，排查问题时别搞混。

3.4 模板字符串调用方式

execa 提供了一种类似 shell 的模板写法，看起来非常直观：

const branch = 'feature/login'; await execa`git checkout ${branch}`;

这种写法会帮你自动转义branch里的特殊字符，保障安全。但它也有自己的适用边界：适合参数不多、可读性优先的场景。一旦参数复杂，我反而更推荐数组形式，因为模板形式中空白、引号的处理还是有一些隐蔽细节，不如数组传参直白可控。

4. 进阶：同步执行、流式输出与 stdin 输入

4.1 用 execaSync 做同步执行

在命令行工具里，有时候不想引入 async/await，或者处理流程就是线性执行，可以用同步版本：

import { execaSync } from 'execa'; const result = execaSync('ls', ['-la'], { cwd: './src' }); console.log(result.stdout);

同步版本会阻塞当前进程，所以只适合短命令。像我上面这种ls当然没问题，但如果在里面跑npm install，整个进程会卡到命令结束，体验很差。我的原则是：交互式 CLI 用异步版本，构建脚本里需要严格顺序且命令简单时，才考虑同步版本。execaSync同样支持timeout、cwd、env这些参数，也会在失败时抛异常。

4.2 让子进程输出直接打到终端

有时你希望命令的输出实时显示在终端上，而不是等全部执行完再一次性打印，尤其是npm run dev、jest --watch这种长时间运行命令。可以这样：

const subprocess = execa('npm', ['run', 'dev'], { stdout: 'inherit', stderr: 'inherit' }); await subprocess;

stdout: 'inherit'意味着子进程的输出直接继承父进程的 stdout/stderr。这样能实时看到日志，但要注意：开启 inherit 后，result.stdout和result.stderr会是undefined，因为数据没有被收集到缓冲区。如果你既想实时显示，又想事后拿完整日志，可以用流监听方式，或者把输出重定向到文件，再配合all: true看合并结果。

4.3 向子进程写入标准输入

不是所有命令都是“只读”的。有些命令需要从 stdin 读数据，比如sort、grep、各类转换工具。execa 提供了input选项：

const result = await execa('sort', [], { input: 'pear\napple\nbanana\n' }); console.log(result.stdout); // apple // banana // pear

input可以是字符串、Buffer 或者一个可读流。这个特性在自动化处理文本时很好用，不用真的去启动一个交互式终端再往里面灌数据。结合input和stdout，你就可以把 execa 当成一个“函数式管道”来用：给一个命令喂入内容、拿到输出，再喂给下一个命令。

4.4 处理超大输出的流式方案

全缓冲模式方便，但内存有上限。如果命令输出几十甚至上百 MB，比如读取一个大日志文件、导出数据库 dump，我更推荐走流式：

import { execa } from 'execa'; import { createWriteStream } from 'node:fs'; const subprocess = execa('mysqldump', ['-u', 'root', 'mydb'], { stdout: 'pipe' }); subprocess.stdout.pipe(createWriteStream('./backup.sql')); await subprocess;

这里stdout: 'pipe'其实是不写也默认的行为，但写出来可以明确表达意图：我想拿到子进程的 stdout 流去处理。流式方案的好处是边产出边消费，内存占用稳定，还方便继续做管道组合。代价是你要自己处理流的错误和结束时机，代码量会多不少。

5. 常见问题与排查实录

5.1 中文输出乱码

Windows 下跑命令，明明控制台显示正常中文，用 execa 拿到的结果却是乱码。本质上是编码问题：execa 默认按utf8解码 stdout，但某些命令输出的是 gbk 或者系统本地编码。

解决思路有三个：

• 如果命令本身支持指定编码参数，优先在命令参数里解决，比如iconv -f gbk -t utf8这种管道处理。
• 拿原始 Buffer，自己转码。execa 支持encoding: 'buffer'，拿到 Buffer 后再用iconv-lite之类的库转换。
• shell 层配合编码设置，但不推荐，跨平台容易顾此失彼。

import { execa } from 'execa'; import iconv from 'iconv-lite'; const result = await execa('some-command', [], { encoding: 'buffer' }); const text = iconv.decode(result.stdout, 'gbk');

这个方法能覆盖绝大多数乱码场景，代价是默认不可读字符串，需要你的逻辑跟着调整。

5.2 Windows 上命令找不到或 ENOENT

execa 在 Windows 上已经处理了很多坑，但仍然会有ENOENT报错。常见原因是没有写命令的完整扩展名。比如直接execa('npm', ['run', 'build'])在某些环境下可能失败，因为系统找到的是npm.cmd。建议遇到这类问题时，明确使用完整命令名：

await execa('npm.cmd', ['run', 'build']);

或者用execaCommand('npm run build')配合shell: true，让系统自己去解析。要注意execaCommand由于走 shell，会有转义和注入风险，只适用于你完全信任的静态命令。

5.3 stdout 和 stderr 的顺序错乱

在控制台日志里，有时候会看到错误信息出现在输出前面，时间顺序对不上。这是因为 stdout 和 stderr 是两个独立流，缓冲策略不同。想严格还原子进程内部输出顺序，必须用all: true：

const result = await execa('npm', ['run', 'test'], { all: true }); console.log(result.all);

result.all是两条流的合并，顺序基本接近真实执行顺序，排查问题时强烈建议开启。特别是在 CI 上分析构建日志，宁可多占一点内存，也不要看错乱顺序的日志。

5.4 timeout 触发了，但进程没退出

遇到最无语的情况：明明设置了timeout: 5000，5 秒后异常也抛了，但后台进程还在跑，端口还被占着。这是因为 execa 超时默认发的SIGTERM没被目标进程处理。这时有两个选择：

• 改成SIGKILL，强制终结：

await execa('npm', ['run', 'server'], { timeout: 5000, killSignal: 'SIGKILL' });

• 在父进程退出时彻底清理，execa 有个cleanup选项，默认是开启的，它会保证父进程结束前杀掉子进程，但如果父进程是被SIGKILL杀掉，这个机制也可能失效，所以别完全依赖它。

我的经验是：对于知道自己会长时间驻留的服务类命令，超时不要随便设SIGKILL，先给SIGTERM再观察；如果确认进程不响应任何优雅退出，就上SIGKILL。

5.5 CommonJS 项目导入报错

这个前面提过，再强调一次。新项目肯定是 ESM 没问题，老项目如果突然报ERR_REQUIRE_ESM，别慌。最简单方案是降级到execa@5，或者统一用await import('execa')。我见过不少团队因为版本升级，整个工具链直接挂掉，最后锁版本解决的。工具稳定比新功能重要，不是每个项目都值得为 ESM 重构。

6. 几个容易被忽略的小经验

最后再分享几条实际项目里验证过的小经验。

第一，不要过度依赖shell: true。有些开发者觉得写execa('git status --porcelain', { shell: true })很省事，但一旦命令里需要拼接变量，你就等于亲手打开注入风险的大门。文件路径里带个空格、用户名里带个;，脚本说不定就崩了。数组传参多写几个元素而已，收益却大得多。

第二，日志保留command字段。execa 的 result 对象里有command，方便打印实际执行的命令，排查参数传错时特别有用。出问题时把command、stdout、stderr、exitCode一起打出来，问题能定位快很多。

第三，尽量把 execa 封装到自己的公共函数里，不要在业务代码里到处直接await execa。我一般会在项目里做一个runCommand函数，统一处理 cwd、日志、超时、错误包装。这样后续如果要全局改超时时间、加日志前缀、统一错误格式，只需要改一个文件，维护成本低得多。

第四，如果你写的是要被别的工具调用的库，记得考虑cleanup和timeout的组合。库的生命周期可能和宿主进程不一致，子进程没人管就变孤儿进程，端口冲突、文件锁问题都是这么来的。给所有长命令设置合理 timeout，并且把 kill 逻辑暴露给调用方，是工程上比较成熟的做法。

execa 不是多神秘的东西，它就是让 Node 调外部命令这件事从“能用”变成“好用”。把它的参数模型、输出模型、错误模型理解透了，你写的脚本会稳定一大截。