• 开发工具

esformatter 是一款专业的 JavaScript 代码格式化工具（ECMAScript code beautifier/formatter），除了内置的缩进、换行与空白控制外，它还提供了 pipe 管道功能：在配置文件中声明一组 CLI 命令，就能把 strip-debug 等独立工具与 esformatter 串联成一条完整的代码处理流水线，一次运行即可完成「预处理 → 格式化 → 后处理」全流程。

1. 为什么需要 pipe 管道？

日常处理 JS 源码时，格式化往往只是其中一步，完整流程还包括：

• 预处理：移除debug标记代码（strip-debug）、清理注释
• 格式化：统一缩进、换行、空格（esformatter 的强项）
• 后处理：追加版本号、统计行数等

esformatter 官方的设计思路是：不要求所有需求都写成插件，而是鼓励复用社区现成的 CLI 工具。pipe 选项正是为此而生，官方文档在 doc/config.md 中说明：

pipe is a simple way to "pipe" multiple binaries input/output

其工作原理（见 lib/format.js 中的pipe函数）：

1. 把代码字符串写入第一个命令的stdin
2. 捕获该命令的stdout，再写入下一个命令的stdin
3. 按队列顺序依次执行，直到全部处理完毕

这和 Shell 里的|管道完全一致，只是被封装进了 esformatter 的配置文件中。

2. pipe 配置快速上手：before 和 after 两条队列

2.1 两个数组控制执行时机

pipe 配置可以写在.esformatter文件或package.json的esformatter属性下，核心是两个数组：

• before：在 esformatter 格式化之前执行
• after：在 esformatter 格式化之后执行

官方 README（README.md）给出的标准示例：

{ "pipe": { // 格式化前执行，输出转发给队列中的下一个命令 "before": [ "strip-debug", "./bin/my-custom-script.sh --foo true -zx" ], // 格式化后执行 "after": [ "baz --keepLineBreaks" ] } }

整体执行顺序为：before 队列（按数组顺序）→ esformatter 本体格式化 → after 队列（按数组顺序），对应源码 lib/format.js 中的先后两次pipe(...)调用。

2.2 最小可用配置

只想先用 strip-debug 移除调试代码，再交给 esformatter 美化？只需要这一小段：

{ "pipe": { "before": ["strip-debug"] } }

数组里每一项都是一条完整的 shell 命令，参数会原样传递，带--foo true -zx这类参数的脚本、相对路径的本地脚本都没问题。

2.3 安装与运行

clone 仓库并本地安装后即可体验：

git clone https://gitcode.com/gh_mirrors/es/esformatter cd esformatter npm install

然后在项目根目录创建.esformatter文件写入 pipe 配置，执行：

esformatter --config .esformatter src/app.js > dist/app.release.js

一条命令即完成「去调试代码 + 代码美化」，输出重定向到dist/就是发布文件。

💡esformatter也支持从stdin读取（cat app.js | esformatter），但把命令写进 pipe 配置的好处是随项目一起提交，团队成员无需重复输入。

3. 命令查找规则：优先本地 node_modules

pipe 的执行机制类似npm run-script（doc/config.md 明确说明）：

1. 先在项目的node_modules中查找本地安装的可执行文件
2. 找不到时再回退到全局命令

这意味着你可以把工具装进devDependencies，只对当前项目生效，不污染全局环境：

npm install --save-dev strip-debug

这也是官方推荐的团队实践：版本锁定在项目里，所有人跑出的结果保持一致。

4. pipe 与插件怎么选？

官方在 doc/plugins.md 中明确建议：如果需要修改 AST 结构，优先写成独立 CLI 工具再走 pipe，而不是硬塞进插件。原因是插件直接改 AST 容易与其他插件及 esformatter 本体产生冲突，而 pipe 各命令之间只通过字符串交接，互不干扰。

5. 执行顺序验证：看官方测试用例

pipe 严格按数组顺序串行执行，顺序写错会导致结果不符合预期。这一点在测试 test/pipe.spec.js 中有明确验证：after队列里test-2写在test-1前面时，输出中test-2的注释也先出现。

仓库自带两个演示命令，可以对照理解 pipe 的数据流：

• esformatter-pipe-test-1：读取stdin，原样输出并在末尾追加一行注释
• esformatter-pipe-test-2：行为相同，追加的注释内容不同

再配合 test/pipe/package.json 中的bin字段，可以看到这些脚本是如何注册成可执行命令的。

6. 常见问题速查

Q1：命令找不到会怎样？直接抛错中断（参见 test/pipe.spec.js 中的should throw error if command not found）。先检查命令名拼写和是否已安装。

Q2：性能敏感的大项目怎么办？官方提示（doc/config.md）：pipe 命令通常比插件慢，因为要重新解析文件、fork 新进程。纯样式类需求建议优先用插件或 preset，pipe 留给 strip-debug 这类结构类处理。

Q3：shebang（#!/usr/bin/env node）会被破坏吗？不会。lib/format.js 在进管道前先把 shebang 剥离，等所有命令执行完后再补回去，避免第三方工具无法识别首行。

总结

esformatter 的 pipe 选项把「多工具串联」从 Shell 习惯升级成了可提交、可共享的项目配置：

• 用before/after两个队列，覆盖格式化前后的全部处理需求
• 命令按数组顺序串行执行，stdout自动喂给下一个工具的stdin
• 本地node_modules命令优先，方便团队锁定版本
• 需要改 AST 结构的活儿（如 strip-debug），交给 pipe 是最稳的方案

掌握这条流水线后，一次esformatter调用即可完成从源码到发布文件的全流程，值得作为每个 JS 项目的标配能力。

• 开发工具