esbuild：一个极快 JavaScript 打包器的技术解析——设计动机、特性体系与源码级实现

esbuild 的定位是"Web 端极快的打包器"（an extremely fast bundler for the web），其核心主张是现有构建工具普遍比理论上慢 10–100 倍，而 esbuild 通过并行化、减少 AST 全量遍历、透明兼容 ESM/CommonJS 等工程手段，在无缓存的前提下依然保持极端速度。本文以仓库根目录 README.md 为主线，结合 架构文档、核心源码与测试快照，完整梳理 esbuild 的设计原则、特性覆盖、CLI/JS/Go 三种接口用法，以及扫描、链接、打印各阶段的源码级实现，读完后可掌握 esbuild 的快速构建原理及其在真实项目中的可复制用法。

一、设计动机：为什么现有构建工具这么慢

README 开篇即给出结论："Our current build tools for the web are 10-100x slower than they could be"（当前 Web 构建工具比它们本可以达到的速度慢 10–100 倍），并配以上方基准测试柱状图（对应仓库中的 benchmark-dark.svg 与 benchmark-light.svg 明暗两套配色）。esbuild 项目的目标是"开启构建工具性能的新纪元，并顺带打造一个易于使用的现代打包器"。

这一主张并非空谈，架构文档 将其落实为四条设计原则，理解这四条原则是理解 esbuild 所有实现取舍的钥匙：

1. 最大化并行（Maximize parallelism）：大部分时间应花在可完全并行的工作上，可通过 --trace=[file] 标志生成 CPU trace，再用 go tool trace 观察。
2. 避免不必要的中间工作：很多打包器会先写出中间 JS 再用另一个工具读回，esbuild 让各阶段共用同一套数据结构，省掉序列化/反序列化开销。
3. 透明支持 ES6 与 CommonJS 双语法：解析器处理的模块是两者的超集，同一文件里可以混用 import 和 require()。
4. 尽量少的 AST 全量遍历以提升缓存局部性：全项目只有三遍全量 AST pass——
   • 词法 + 语法解析 + 作用域建立 + 符号声明；
   • 符号绑定 + 常量折叠 + 语法降级（lowering）+ 语法压缩（mangling）；
   • 打印 + source map 生成。
5. 为 watch 模式下的增量编译做结构准备：跨构建存活的数据结构必须是不可变的，以便在构建间共享。

另外，文档还特别提到 import 路径解析中系统调用的开销很高，因此在 resolver 与文件系统实现中缓存 syscall 结果是"相当大的提速"，这也是无缓存依然快的关键之一。

二、README 特性清单与仓库实现的逐条对应

README 列出了七大核心特性，下文将每一条特性落到当前仓库中可验证的实现位置：

README 特性	仓库中的实现/证据
无需缓存的极速构建	三遍 AST pass 设计（docs/architecture.md），syscall 结果缓存（internal/fs 目录）
内建 JavaScript / CSS / TypeScript / JSX	JS/TS 解析器 internal/js_parser、CSS 解析器 internal/css_parser、JSX 选项 --jsx 见 main.go
CLI / JS / Go 三套 API	CLI：cmd/esbuild；JS：lib/npm 与 lib/shared；Go：pkg/api
同时打包 ESM 与 CommonJS	混合模块链接说明见 docs/architecture.md "Hybrid CommonJS and ES6 modules" 一节
打包 CSS（含 CSS Modules）	CSS 解析 internal/css_parser、composes 处理 css_decls_composes.go
Tree shaking / Minify / Source maps	摇树算法见 internal/linker 及架构文档 "Tree shaking" 一节；快照测试 snapshots_dce.txt
本地服务器 / watch 模式 / 插件	serve/watch 参数见 main.go；watch 增量实现 pkg/api/watcher.go；插件经 stdin/stdout 服务协议 service.go

版本与平台支持

当前仓库版本为 0.28.1（见 version.txt），Go 模块声明为 go 1.13（go.mod），这是刻意为之——为了让用户能在较老的操作系统上用旧版 Go 自行交叉编译 esbuild。仓库还通过 npm/ 目录发布了覆盖 20+ 平台的预编译二进制包，包括 linux-x64、darwin-arm64、win32-x64、android-arm64，乃至 wasi-preview1 等 WASI 目标，每个平台目录内含 package.json 与 README.md。

三、构建流水线：扫描与编译两阶段

架构文档 指出，构建流水线有两个主要阶段，都实现在 bundler.go 中，bundler.go 文件头注释也明确写道：每个 build/transform 操作分两阶段，第一阶段扫描模块图（ScanBundle），第二阶段从模块图生成输出文件（Compile）。

扫描阶段（Scan phase）

从入口点开始遍历依赖图，找出 bundle 需要的所有模块。源码入口为 ScanBundle（bundler.go#L1370），采用并行 worklist 算法：worklist 初始为入口点列表，每个文件由独立 goroutine 解析成 AST，若存在依赖（ES6 import 语句、import() 表达式或 CommonJS require()）则把新文件追加进 worklist，直到 worklist 为空。相关的核心子例程包括 scanAllDependencies（bundler.go#L2175）和 addEntryPoints（bundler.go#L1841）。

编译阶段（Compile phase）

为每个入口点生成 bundle：先把 import 与 export"链接"起来，再把解析好的 AST 转回 JavaScript，最后拼接成最终的打包文件。源码入口为 (*Bundle).Compile（bundler.go#L3012）。打印阶段每个文件独立输出、可完全并行，source map 生成亦然——每个文件打印时生成一段 VLQ 编码的 "source map chunk"，最后在 AppendSourceMapChunk() 中"重定位"到正确偏移。

四、解析、链接与打印的关键技术

词法与解析：为什么两遍 pass 就够

解析器与词法器分离，词法器在解析时按需调用而非预先扫描整个输入——因为正则表达式 vs 除号、JSX 元素 vs 小于号等场景下，token 类型取决于语义上下文。除 TypeScript 外，词法前瞻几乎都保持在 1 个 token（TypeScript 需要任意前瞻，相关逻辑在解析器的 trySkipTypeScript*WithBacktracking() 系列方法中，实现见 internal/js_parser/ts_parser.go）。

符号与作用域方面：每个标识符都引用一个 64 位 ID 的"符号"，即使是没有声明的"未绑定"符号（如全局变量 $）也有符号表示，这让解析器生成新符号时不必担心命名冲突。整个文件的符号存在扁平的顶层数组中，克隆符号只需克隆数组。作用域树不挂在 AST 上，而是通过两遍 pass 按相同顺序调用 pushScope*()/popScope() 临时映射到 AST 上。

常量折叠：虽"极简"，但足以处理 React 这类库中 if (process.env.NODE_ENV === 'production') 的分支。使用 --define:process.env.NODE_ENV="production" 后，比较式先折叠为 "production" === 'production' 再折叠为 true，解析器随后把 else 分支当死代码处理——其中的 require()/import() 调用会被忽略，react.development.js 永远不会进入依赖图。

TypeScript 解析：通过增强现有 JS 解析器实现，类型声明大部分"按空白跳过"；enum、namespace、参数属性等 TS 专有特性在第二遍 pass 中转换为 JS 语法。一个容易忽略的细节：TS 中未使用的 import 必须移除（它们可能是 type-only import），且 import 语句整体移除时可能有语义影响——这由解析器中的 tsUseCounts 字段跟踪。

链接阶段：三种模块形态的合并

• CommonJS 链接：模块若使用了任何 CommonJS 特性（引用 exports/module、顶层 return 等），就作为独立闭包表示，通过运行时辅助函数 __commonJS() 包裹，精确模拟 Node 运行模块的方式。
• ES6 链接（作用域提升）：不使用 CommonJS 特性的模块进入跨模块作用域，即"scope hoisting"（Rollup 式做法）。符号合并通过每个符号的 Link 字段实现（类似并查集），打印器遇到符号引用须调用 FollowSymbols() 追到链尾。整个 bundle 期间，所有文件的符号表被合并为一个大符号表（数组的数组，外层下标即扫描阶段分配的文件索引）。
• 混合模块：ES6 语法与 CommonJS 语法可同文件混用，ES6 import 会被转换为 require() 调用，ES6 export 转为模块 exports 对象上的 getter。由于解析期尚不知道目标模块是否为 CJS，对 ES6 import 的引用使用特殊的 EImportIdentifier AST 节点，在链接期决定是否需要转为属性访问（填充符号的 NamespaceAlias 字段），从而避免打印前再做一遍全量 AST 遍历。
• 运行时库：__commonJS()、__decorate() 等辅助函数集中在单个字符串中，位于 internal/runtime/runtime.go，自动包含进每次构建，未使用的部分会被树摇移除。

Tree shaking：以顶层语句为节点的图遍历

摇树把输入文件视为图，每个节点是顶层语句（代码中称 "part"），每个 part 标记"有/无副作用"（如 let foo = 123 无副作用，let foo = bar() 有副作用）。遍历从入口点的所有有副作用 part 出发沿两类边前进：有副作用 part 的依赖边（必须保留）、符号引用到声明它的 part 的边（仅在符号被引用时保留）。遍历结束，只有被访问的 part 进入 bundle。上文的 tree-shaking 示意图正是 架构文档 中三文件示例（index.js/config.js/net.js）的可视化，最终产物只保留被遍历到的 get()、session/api/load() 与入口语句。该特性始终开启且不可关闭（README 帮助文本中的 --tree-shaking 仅能显式强制 on/off，见 main.go#L131）。仓库中有专门的 DCE（死代码消除）测试快照 snapshots_dce.txt 和测试入口 bundler_dce_test.go 验证其行为。

代码分割：树摇的高级形态

代码分割把多入口 bundle 切分为 chunk，保证同一段代码只出现在一个 chunk 中、且每个入口不会下载永不会用的代码；每个动态 import() 的目标都视为额外入口。它本质是对每个入口各跑一次树摇，每个 part 记录到达它的所有入口集合，集合决定 chunk 归属；随后为跨 chunk 的符号引用自动生成 import/export。默认关闭，用 --splitting 标志启用（当前仅支持 esm，见 main.go#L52），对应的测试快照在 snapshots_splitting.txt。

一个值得注意的边界：分割算法不能把对模块局部变量的赋值移入与声明不同的 chunk（ES6 import 是只读绑定，跨 chunk 赋值会抛出 TypeError: Assignment to constant variable）。修复方式是把"含赋值的 part"与"含符号声明的 part"分组（求图的连通分量），使它们具有相同的入口集合——架构文档中用 entry1.js/entry2.js/data.js 三文件示例完整演示了 setData 函数最终被并入共享 chunk 的过程。

打印阶段的符号压缩

压缩器把内部符号重命名为短名时有一个反直觉的约束：不用 Unicode 而限定 ASCII——因为目标是最小化字节数，而多数 Unicode 字符在 UTF-8 下占多字节。ASCII 下 JS 只有 54 个单字符标识符、3453 个双字符标识符，所以按频率把最常用的符号分最短名字。更妙的优化借鉴自 Google Closure Compiler：把兄弟函数形参符号合并，使 function x(a, b, c) 与 function y(a, b, c, d) 产生重复字符序列，从而提升 gzip 压缩率。该算法（为每个嵌套作用域符号分配 "slot" 频率计数器槽位，再按降序计数分配名字）必须跑三遍，因为 JS 有三个独立命名空间：普通符号、label 符号、私有符号。

五、CLI 使用：完整选项与可复制示例

快速上手示例

main.go 中内置帮助文本（esbuild --help 的输出）给出了六个官方示例，均为可直接复制运行的命令：

# 生成 dist/entry_point.js 和 dist/entry_point.js.map
esbuild --bundle entry_point.js --outdir=dist --minify --sourcemap

# 允许 .js 文件中使用 JSX 语法
esbuild --bundle entry_point.js --outfile=out.js --loader:.js=jsx

# 将标识符 RELEASE 替换为字面量 true
esbuild example.js --outfile=out.js --define:RELEASE=true

# 从 stdin 读入，从 stdout 输出
esbuild --minify --loader=ts < input.ts > output.js

# 输入文件变化时自动重建
esbuild app.ts --bundle --watch

# 为 "www" 目录启动本地 HTTP 服务器
esbuild app.ts --bundle --servedir=www --outdir=www/js

常用（Simple）选项

帮助文本将选项分为 Simple 与 Advanced 两组，常用组包括：

选项	说明
--bundle	将所有依赖打包进输出文件
--define:K=V	解析期间用 V 替换 K
--external:M	将模块 M 排除在打包之外（支持 * 通配）
--format=...	输出格式（iife | cjs | esm）；不打包时无默认值，打包时 browser 平台默认 iife、node 平台默认 cjs
--loader:X=L	用 loader L 加载扩展名 X 的文件，可选：base64 | binary | copy | css | dataurl | empty | file | global-css | js | json | jsx | local-css | text | ts | tsx
--minify	压缩输出（等价于开启所有 --minify-* 标志）
--outdir=... / --outfile=...	多入口用输出目录 / 单入口用输出文件
--packages=...	设为 external 可避免打包任何第三方包
--platform=...	平台目标：browser | node | neutral，默认 browser
--serve=...	在此 host:port 启动本地 HTTP 服务器
--sourcemap	生成 source map（还支持 =inline、=external 变体）
--splitting	启用代码分割（目前仅限 esm）
--target=...	环境目标（如 es2017、chrome58、node10、ie9），默认 esnext
--watch	watch 模式：文件变化时重建；stdin 关闭时退出，可用 --watch=forever 忽略

进阶（Advanced）选项（节选）

帮助文本还包含大量进阶选项（main.go#L58-L135），常用的有：--analyze（打印 bundle 内容报告，--analyze=verbose 更详细）、--banner:T=... / --footer:T=...（在 css/js 输出文件首尾插入文本）、--chunk-names=... / --entry-names=...（输出路径模板，默认分别为 [name]-[hash] 与 [dir]/[name]）、--drop:...（移除 console/debugger 构造）、--external、--inject:F（把文件 F 导入所有输入文件并自动替换匹配的全局变量）、--jsx=automatic（使用 React 自动运行时，配套 --jsx-factory/--jsx-fragment/--jsx-import-source 等）、--keep-names（保留函数/类的 name 属性）、--mangle-props=...（按正则重命名属性，可用 --mangle-cache 持久化决策）、--metafile=...（把构建元数据写入 JSON 文件）、--resolve-extensions=...（隐式扩展名列表，默认 .tsx,.ts,.jsx,.js,.css,.json）、--sourcemap=external|inline、--supported:F=...（手动声明某 JS 特性是否受支持）、--tsconfig=... / --tsconfig-raw=...、--watch-delay=... 等。

隐藏的工程选项

main() 入口还预扫描了若干隐藏参数（main.go#L186-L217）：--heap= 生成堆快照、--trace= 生成 CPU trace、--cpuprofile= 生成 CPU profile（因 Go profiler 仅 100 Hz，源码注释说明会持续采样 30 秒以获得约 3000 个样本）、--timing 开启内部计时。另外，当非 watch/serve 模式且入口点不超过 1 个时，esbuild 会调用 debug.SetGCPercent(-1) 关闭 GC——源码注释称"这个提速并不小"，因为一次性构建"分配大量内存后立即退出"，GC 纯属浪费。

六、JS 与 Go API

README 强调"A straightforward API for CLI, JS, and Go"，仓库中三种接口一一对应：

Go API

api.go 的包注释给出了两个官方示例，可直接作为集成起点。Build API 端到端执行构建：

package main

import (
    "os"
    "github.com/evanw/esbuild/pkg/api"
)

func main() {
    result := api.Build(api.BuildOptions{
        EntryPoints: []string{"input.js"},
        Outfile:     "output.js",
        Bundle:      true,
        Write:       true,
        LogLevel:    api.LogLevelInfo,
    })

    if len(result.Errors) > 0 {
        os.Exit(1)
    }
}

Transform API 则把源码字符串转换为 JavaScript，可用于压缩、TS/JSX 转 JS、或新语法降级到旧语法（包注释示例用 api.Transform + Loader: api.LoaderJSX 转换一段 JSX）。此外，若想免子进程开销地从 Go 调用 CLI，官方建议直接使用 pkg/cli（见 api.go 注释）。

JS API 与进程间服务

Node.js 端通过 lib/npm/node.ts 拉起 esbuild 原生二进制作为长驻服务：服务经 stdin/stdout 通信，协议是"每个请求为字符串数组，每个响应为字符串到字节串的映射，所有值用 32 位小端长度前缀"（service.go#L1-L4）。--service=<version> 启动服务时会先校验宿主版本与二进制版本一致（main.go#L202-L214），不一致则报错退出——这是为拦截安装错误而设。服务空闲时会周期性 ping 宿主以检测宿主已消失的情形，协议与消息类型定义见 lib/shared/stdio_protocol.ts 与 stdio_protocol.go。watch 模式的增量重建逻辑位于 pkg/api/watcher.go，与架构文档"为增量编译而设计"的原则呼应：未变更的文件不会重跑任何全量 AST pass。

七、从源码构建与验证

Makefile 提供了完整的开发流程：

make            # 构建 esbuild 二进制（CGO_ENABLED=0，带 -ldflags=-s -w -buildid= -trimpath）
make test       # 开发测试：test-go、vet-go、no-filepath、verify-source-map、end-to-end-tests 等
make test-all   # 发布测试：额外包含 test-deno、ts-type-tests、test-wasm-node、test-wasm-browser、test-yarnpnp

其中两个细节值得注意：no-filepath 目标会 grep 检查代码中禁止使用标准库 path/filepath（改用自研 internal/fs 以跨平台/WASM 一致）；go/$(GO_VERSION) 目标会下载指定版本 Go 源码并打补丁禁用 buildinfo，再自编译工具链——Makefile#L60-L82 的注释解释这是为避免"安全扫描工具"仅凭构建用的 Go 版本就给 esbuild 误报 CVE。测试体系还包括 bundler 快照测试 internal/bundler_tests（按 dce、lower、splitting、packagejson 等主题分组的 txt 快照）、CSS 解析器测试 css_parser_test.go、以及 Node 端到端脚本 scripts/end-to-end-tests.js。

八、小结

回到 README 的主张：esbuild 的速度不是来自缓存技巧，而是来自贯穿全链路的系统性设计——只有三遍全量 AST pass、词法按需进行、syscall 结果缓存、扫描与打印全面并行、单次构建直接关 GC；其特性覆盖（JS/CSS/TS/JSX 内建、ESM+CJS 混合打包、CSS Modules、树摇、压缩、source map、serve/watch/插件）在仓库中都能找到对应的实现目录与测试快照；而 CLI、JS、Go 三种接口则分别落在 cmd/esbuild、lib/npm 与 pkg/api。如果你想继续深挖，建议的阅读路径是：docs/architecture.md → internal/bundler/bundler.go（ScanBundle/Compile）→ internal/linker/linker.go → internal/js_printer/js_printer.go，这条路径恰好覆盖了"扫描—链接—打印"的完整构建流水线。