Next.js Turbopack 模块级 Tree-Shaking 分析器快照解读:从 node-fetch 测试用例看 `output.md` 的结构与语义
Next.js Turbopack 模块级 Tree-Shaking 分析器快照解读:从 node-fetch 测试用例看 output.md 的结构与语义
导读
Turbopack 是 Next.js 的底层打包器(Rust 实现,位于本仓库 turbopack/crates 下)。它内部有一整套基于"模块片段(module fragments)"的 ECMAScript 模块图切分与按需代码生成机制——通俗说就是模块级的 tree-shaking:把模块拆成可独立加载的 part,再把真正会被用到的部分合并输出。本文以 turbopack-ecmascript crate 中 tree-shaker 测试套件的一个用例 —— node-fetch 为例,逐段拆解其快照文件 output.md 的格式、语义与生成原理。读完本文,你将能读懂 Turbopack tree-shaker 测试快照中的每个字段(Items、Phases、Final、Entrypoints、Modules dev/prod),并掌握"快照为什么长这样"背后的源码依据。
一、快照文档的定位:这是测试产出,不是手写文档
先明确 output.md 的性质:它是由 Rust 单测自动生成并与文件比对的 golden snapshot(黄金快照),与同目录下的 input.js 一一对应。用例目录只有两个文件:input.js(被测输入)与 output.md(期望/实际输出),没有 config.json,意味着该用例使用空配置(exports 列表为空,见下文测试驱动说明)。
驱动该快照的测试位于 module_fragments/tests.rs,关键证据:
#[fixture("tests/tree-shaker/analyzer/**/input.js")]
fn test_fixture(input: PathBuf) {
run(input);
}
这段代码用 #[fixture] 声明了一个 glob:tests/tree-shaker/analyzer/**/input.js。也就是说,tree-shaker/analyzer 目录下每一个子目录里的 input.js 都会被当作一个独立测试用例(tests.rs)。测试末尾会把拼接出的文本与同名 output.md 对比:
NormalizedOutput::from(s)
.compare_to_file(input.with_file_name("output.md"))
.unwrap();
(tests.rs)。这意味着:任何一次代码改动如果改变了模块图切分的结果,output.md 都会 diff 出来,快照本身是"行为即规格"的回归防线。整个 analyzer 目录下还有 simple、dce、complex、shared-2、node-globals、next-response、route-handler、mui-sys 等几十个用例(详见 tests/tree-shaker/analyzer),覆盖 import、export、TLA、副作用、共享模块等不同形态。
二、输入用例:复刻 node-fetch 的能力探测片段
被测输入 input.js 只有四行顶级语句:
import Stream from 'node:stream';
const streamDestructionSupported = 'destroy' in Stream.Readable.prototype;
function fetch(){
}
export default fetch;
从目录名与代码形态可以推断,该用例刻意复刻了 node-fetch 风格的"能力探测"片段:用 'destroy' in Stream.Readable.prototype 判断当前 Node 运行时是否支持流的销毁(destruction),并默认导出 fetch。用例虽然短,却集齐了 tree-shaker 需要处理的四类语法单元:
- 默认导入:
import Stream from 'node:stream'—— 一个副作用模块(Node 内置模块)的默认导出绑定; - 顶级常量声明 + 成员访问:
const ... = 'destroy' in Stream.Readable.prototype—— 该语句读取了导入绑定Stream,属于"潜在副作用"操作; - 函数声明:
function fetch(){}—— 空的具名函数声明; - 默认导出:
export default fetch;—— 模块对外契约。
好,下面我们逐节解读快照 output.md 本身。
三、# Items:语句被切成的最小图节点
快照第一部分列出了分析器初始化阶段(对应 tests.rs 中 g.init(&module, ...) 的产物)产生的全部 item:
# Items
Count: 6
## Item 1: Stmt 0, `ImportOfModule`
import Stream from 'node:stream';
- Hoisted
- Side effects
## Item 2: Stmt 0, `ImportBinding(0)`
import Stream from 'node:stream';
- Hoisted
- Declares: `Stream`
...
3.1 Count: 6 与"只列 5 个"的关系
Count 显示 6,但 Items 列表只有 Item 1~5。原因见 tests.rs 的打印逻辑:它遍历全部 item id,遇到 ItemId::Group(_)(组节点,不是真正的语句 item)就 continue 跳过:
let (index, kind) = match id {
ItemId::Group(_) => continue,
ItemId::Item { index, kind } => (*index, kind),
};
第 6 个 id 正是一个 Group(即默认导出入口组),它不出现在清单里,但会作为节点出现在后面的依赖图与 Entrypoints 中。
3.2 ItemId 的类型体系
Item 的种类(ItemIdItemKind)定义在 module_fragments/graph.rs,本用例恰好覆盖其中四种:
| Kind | 出现位置 | 快照中对应 |
|---|---|---|
ImportOfModule |
一条 import 语句拆出的"模块副作用"节点 | Item 1(Stmt 0) |
ImportBinding(u32) |
同一 import 中每个绑定项拆出一个节点,用于为绑定创建唯一标识 | Item 2(Stmt 0, ImportBinding(0)) |
VarDeclarator(u32) |
顶层变量声明中每个声明符 | Item 3(Stmt 1, VarDeclarator(0)) |
Normal |
普通顶级语句/声明 | Item 4(Stmt 2, function fetch)、Item 5(Stmt 3, export default fetch) |
ReexportBinding(u32) |
re-export 的绑定(本用例未出现) | — |
源码注释还明确指出一个设计要点:ImportBinding 并不是模块中真实存在的语句,而是一个"幻影节点"(phantom node),仅用于给 import 声明里的每个绑定生成唯一标识(见 graph.rs)。
同时 ItemId::Group(ItemIdGroupKind) 包含 ModuleEvaluation 与 Export(Id, Atom) 两种(graph.rs),后者 (local, export_name) 表示"某个本地绑定以某个导出名输出"。本用例第 6 个 id 即 Export((__TURBOPACK__default__export__, #0), "default")——它会在 # Final 一节以 ItemId(Export(("__TURBOPACK__default__export__", #0), "default")) 的形式出现。
3.3 item 上悬挂的属性标记
每个 item 下方用 - 前缀列出静态分析得到的属性,字段来源与打印逻辑一一对应(tests.rs):
- Hoisted:该节点属于"提升"绑定类(import、函数声明等),打印自item.is_hoisted;- Side effects:该语句被认为可能产生副作用,打印自item.side_effects;- Declares:声明了哪些顶层绑定(item.var_decls,打印标题虽为 Declares,但数据来自 var_decls);- Reads:立即读取了哪些绑定(item.read_vars);- Reads (eventual):最终/间接读取(item.eventual_read_vars,本例未出现);- Write:写入了哪些绑定(item.write_vars);- Write (eventual):最终/间接写入(item.eventual_write_vars,本例未出现)。
对本用例逐项翻译:
| Item | 判定 | 语义 |
|---|---|---|
Item 1 ImportOfModule |
Hoisted + Side effects | node:stream 的模块副作用导入需要保留执行 |
Item 2 ImportBinding(0) |
Hoisted + Declares Stream |
提供 Stream 绑定 |
Item 3 VarDeclarator(0) |
Side effects + Declares streamDestructionSupported + Reads Stream + Write Stream、streamDestructionSupported |
'destroy' in Stream.Readable.prototype 读取绑定并写常量;因对 Stream.Readable.prototype 的探测被视为可能产生副作用 |
Item 4 function fetch(){} |
Hoisted + Declares/Write fetch |
函数声明被提升 |
Item 5 export default fetch |
Side effects + Declares __TURBOPACK__default__export__ + Reads fetch + Write __TURBOPACK__default__export__ |
默认导出被改写为写入魔法变量 __TURBOPACK__default__export__ |
注意 __TURBOPACK__default__export__ 属于 Turbopack 的 magic identifier 体系(MAGIC_IDENTIFIER_DEFAULT_EXPORT_ATOM 等定义见 module_fragments 引用的 magic_identifier 模块),它把 ES 模块的 export default 转成内部变量 + 内部导出名,便于跨 part 引用。
四、# Phase 1 ~ 4:依赖图的分阶段构建
接下来四段内容结构完全相同,都是 mermaid 图,分别对应分析器生命周期中的四个步骤(tests.rs):
analyzer.hoist_vars_and_bindings()—— 提升变量与绑定;analyzer.evaluate_immediate(&module, &eventual_ids)—— 计算立即读/写产生的依赖;analyzer.evaluate_eventual(&module)—— 补充最终/间接读写的依赖;analyzer.handle_exports(&module)—— 处理导出对语句的依赖。
4.1 Phase 1:只有节点,没有边
graph TD
Item1;
Item2;
Item3;
Item4;
Item5;
Item6;
Item6["export default"];
此时 6 个节点全部建立,其中 Item 6 是"export default"入口组(Group 节点),用 Item6["export default"] 覆写显示名;但依赖边尚未计算,图中没有任何连线。
4.2 Phase 2:立即依赖建边
Item3 --> Item2;
Item3 --> Item1;
Item5 --> Item4;
Item5 --> Item3;
Item6 --> Item5;
对应 evaluate_immediate 的结果,边语义可以这样理解:
Item3 --> Item2:VarDeclarator读取了绑定Stream,因而依赖提供该绑定的ImportBinding(0)节点;Item3 --> Item1:同一语句又依赖node:stream这个模块的副作用求值节点ImportOfModule;Item5 --> Item4:export default fetch读取了fetch;Item5 --> Item3:导出语句被排在其前的副作用语句之后(顶层语句求值顺序约束);Item6 --> Item5:默认导出入口组依赖承载它的导出语句。
4.3 Phase 3、Phase 4:无新增
Phase 3 与 Phase 4 的图与 Phase 2 完全一致,说明该用例在 evaluate_eventual(无间接读写的额外边)与 handle_exports(导出节点已在 init 阶段建立、无新增依赖)两轮中没有产生新变化。这正是快照的价值——把"哪些分析步骤真的改变了图"这个行为显式固化下来。
五、# Final:收缩(condensation)后的模块级依赖
handle_explicit_deps 之后,测试调用 analyzer.g.finalize(...)(tests.rs),对图做强连通分量收缩(petgraph 的 condensation,见 graph.rs 附近的 condensation(graph, true)),得到模块加载级的最简依赖:
N0["Items: [ItemId(0, ImportOfModule)]"];
N1["Items: [ItemId(0, ImportBinding(0))]"];
N2["Items: [ItemId(1, VarDeclarator(0)), ItemId(2, Normal), ItemId(3, Normal), ItemId(Export(("__TURBOPACK__default__export__", #0), "default"))]"];
N1 --> N0;
解读:
- N0 = 原始 Stmt 0 的
ImportOfModule:保留成"仅副作用导入"; - N1 = 原始 Stmt 0 的
ImportBinding(0):依赖 N0; - N2 = 剩下的全部真实代码(常量探测语句 +
fetch函数 + 导出语句)外加默认导出入口组被收拢成一个整体,快照里 N2 没有指向 N0/N1 的静态边(运行期依赖由下面Modules各 part 内的__TURBOPACK_PART__import 承载)。
也就是说:tree-shaker 的最终结论是把模块切成两个可独立求值的载荷 —— 一个是 node:stream 的副作用导入(N0/N1 链),一个是包含导出代码的 N2;而 export default 是模块的对外契约,强制 N2 中的所有语句存活。
六、# Entrypoints:每种入口对应到哪个 part
紧随其后(dev 与 prod 各打印一次)的是切分模块的入口表:
{
ModuleEvaluation: 2,
Export(
"default",
): 2,
Exports: 3,
}
它来自 g.split_module(&[], analyzer.items) 返回的 entrypoints,并被排序后以 {:#?} 打印(tests.rs)。入口 key 类型对应 mod.rs 中的 Key 枚举(ModuleEvaluation、Export(name)、Exports、StarExports 等)。含义是:
ModuleEvaluation: 2:要"求值整个模块",应加载 part 2(见下,part 2 内含全部业务代码与node:stream依赖);Export("default"): 2:要拿默认导出,定义点在 part 2;Exports: 3:模块的导出外壳(export facade)是 part 3,由它对外 re-export default。
七、# Modules (dev) 与 # Modules (prod):最终拆出的 part
这一节展示 split_module 真正产出的代码片段。本例 dev 与 prod 完全一致(快照中两段字节相同),我们以 dev 为准逐个 part 看。
Part 0 —— 纯副作用导入
import 'node:stream';
这是 N0 的代码形态:只为了执行 node:stream 的求值副作用,不绑定任何名字。
Part 1 —— 绑定占位
import "__TURBOPACK_PART__" assert {
__turbopack_part__: 0
};
它只 import part 0。__TURBOPACK_PART__ 是 Turbopack 内部约定的 part 间导入源名(常量 TURBOPACK_PART_IMPORT_SOURCE = "__TURBOPACK_PART__",见 mod.rs),配合 assert { __turbopack_part__: 0 } 这种 import attributes 语法,把"从 part 0 加载"编码到 AST 中,供下游 chunk 生成阶段解析(参见 mod.rs 中对 __TURBOPACK_PART__ 的处理)。
Part 2 —— 真实业务代码所在的 part
import "__TURBOPACK_PART__" assert {
__turbopack_part__: 0
};
import Stream from 'node:stream';
const streamDestructionSupported = 'destroy' in Stream.Readable.prototype;
function fetch() {}
const __TURBOPACK__default__export__ = fetch;
export { __TURBOPACK__default__export__ as default };
export { streamDestructionSupported as a } from "__TURBOPACK_VAR__" assert {
__turbopack_var__: true
};
export { fetch as b } from "__TURBOPACK_VAR__" assert {
__turbopack_var__: true
};
export { __TURBOPACK__default__export__ as c } from "__TURBOPACK_VAR__" assert {
__turbopack_var__: true
};
export { };
要点:
- 它先 import part 0 确保
node:stream副作用先执行,再自己重新import Stream from 'node:stream'获得绑定; - 常量探测、
fetch函数、魔法导出变量__TURBOPACK__default__export__ = fetch原样保留; - 每个顶层绑定都额外通过
export { x as 字母 } from "__TURBOPACK_VAR__" assert { __turbopack_var__: true }抛出一个内部"变量导出"入口——这是 Turbopack 让其它 part/模块能按需引用这些绑定(streamDestructionSupported、fetch、默认导出)的机制; - 末尾
export { };是模块出口占位。
值得强调:被 export default 引用的空函数 fetch 必须保留。这里体现了模块级 tree-shaking 与一般 DCE 的差别:只要默认导出是模块对外契约的一部分,构造该导出的整条数据链(fetch → __TURBOPACK__default__export__)就都要存活;而 node:stream 的导入因"副作用 + 绑定被使用"双重原因被保守保留。
Part 3 —— 导出外壳
export { default } from "__TURBOPACK_PART__" assert {
__turbopack_part__: "export default"
};
这是 Entrypoints 中 Exports 指向的 facade:从指定 part(名为 "export default" 的部分)re-export default,供真正的外部消费者 import 使用。
Merged (module eval) —— 求值视图的合并结果
import "__TURBOPACK_PART__" assert {
__turbopack_part__: 0
};
import Stream from 'node:stream';
const streamDestructionSupported = 'destroy' in Stream.Readable.prototype;
function fetch() {}
const __TURBOPACK__default__export__ = fetch;
export { __TURBOPACK__default__export__ as default };
...
这段由 Merger::merge_recursively 生成(tests.rs):以 Key::ModuleEvaluation 指向的 part 2 为起点,沿 part 引用递归合并 part 0(import 'node:stream' 的副作用),最终得到一个"等价于原模块完整求值"的扁平模块。可以看到它和输入 input.js 在语义上一一对应——快照以这种方式证明:切分与重组是可逆且保语义的。
八、为什么 dev 与 prod 输出相同?
在 tests.rs 中,两次 describe 调用分别以 Mode::Development 与 Mode::Production 执行 g.handle_weak(...),随后才 split_module。dev/prod 的差异只会来自"弱依赖(weak edge)"在不同模式下的处理策略不同。对本用例,模块图里不存在这类会随模式变化的弱依赖,所以 # Modules (dev) 与 # Modules (prod) 完全一致。如果读者想看到模式差异,可以横向对比 analyzer 目录下其它快照中 dev/prod 分叉的用例(例如涉及大量内部引用的 complex 或 next-response 等),它们更能体现生产模式下的裁剪效果。
九、如何查看与运行这类用例
- 位置:输入统一为
turbopack/crates/turbopack-ecmascript/tests/tree-shaker/analyzer/<name>/input.js,期望输出为同目录output.md,可选config.json通过exports: Vec<Vec<String>>声明"同时启用多个导出"的额外场景(tests.rs); - 运行:这是
turbopack-ecmascriptcrate 的 Rust 单测(fixture 宏来自 turbo-tasks 的testing设施),在仓库根执行对应 crate 的cargo test即可驱动全部analyzer/**用例;若快照与实现不一致,测试会以 diff 形式报出; - 实现阅读:核心数据结构(
ItemId、依赖图DepGraph、finalize/condensation)在 graph.rs;快照生成器与四种分析阶段编排在 tests.rs;part 合并器在 merge.rs,与侧效应/part 代码生成相关的子模块见 side_effects 与 part。
十、小结:快照告诉我们的 tree-shaker 行为
把整份 output.md 串起来,可以得到一条清晰的因果链:
- 分析器把模块顶层语句细化为 item(import 会被拆成"模块副作用 + 逐绑定"),并为每个 item 记录 Hoisted / Side effects / Declares / Reads / Write 等静态属性;
- 依赖边按"立即依赖 → 最终依赖 → 导出依赖"四阶段逐步建图(Phase 1~4);
- 图收缩(condensation)后得到模块级的最小求值依赖(Final),随后按入口 key(ModuleEvaluation / Export / Exports)切分成多个 part 代码(Entrypoints 与 Modules);
__TURBOPACK_PART__/__TURBOPACK_VAR__魔法导入构成 part 之间的运行期引用;Merger再沿入口递归合并出可求值的完整模块,证明切分保语义;- 由于空
fetch被export default引用、node:stream导入既带副作用又被读取,本用例中几乎全部代码都被判定存活——这是 tree-shaker 对"外部可见契约与潜在副作用"采取的保守且正确的姿态。
对于想为 Turbopack 贡献或排查打包体积问题的开发者,tests/tree-shaker/analyzer 下的大量快照是一份"用代码说话"的活文档:读懂 node-fetch 这一份,就等于拿到了打开其余全部用例的钥匙。