Turbopack 树摇Tree Shaking快照解读从 simple-vars-1 剖析 ES 模块的 Item 依赖分析与碎片化输出【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.jssimple-vars-1是 Turbopack 仓库中一组“树摇分析器”的可视化快照用例以一段仅含两条const声明与一个具名导出语句的极简模块为输入把打包器内部的模块依赖图构建、碎片part拆分与合并过程完整 dump 成 markdown 文件。本文将逐段拆解这份快照说明“Item 是什么、依赖图如何经 4 个阶段构建、导出如何决定碎片划分”并结合源码确认每一步对应的真实实现位置让读者既能读懂这类output.md也能理解 Next.js 所依赖的 Turbopack 打包引擎在模块层做树摇的基本原理。快照文件概述一个可读的树摇过程“实验记录”该用例位于turbopack/crates/turbopack-ecmascript/tests/tree-shaker/analyzer/simple-vars-1/目录整个目录只有两个文件input.js被测输入模块全文只有 3 行const a a; const b b; export { a, b };output.md对上述输入运行“树摇分析器”后生成的快照即本文剖析的主体。这类测试属于“黄金文件对比”golden-file snapshot测试框架用统一的 fixture 通配符收集输入运行分析器后把过程与结果序列化成 markdown再与既有output.md逐字比对。若分析行为发生回归比对会失败并提示差异。测试入口在 module_fragments/tests.rs其#[fixture(tests/tree-shaker/analyzer/**/input.js)]声明了收集范围函数末尾通过NormalizedOutput::from(s).compare_to_file(input.with_file_name(output.md))见 tests.rs完成对比。值得注意的是快照把内部中间表示以人能读懂的 markdown 呈现用# Items列出语句切片用 mermaidgraph TD展示每个阶段的依赖图用## Part N给出最终产出的代码碎片。因此它既是回归测试资产也是理解 Turbopack 模块级树摇module fragments的“实验记录”。第一步模块被切成 4 个 Itemoutput.md开头的# Items段是分析入口DepGraph::init的产物模块内每一条值得被单独追踪的语句与导出条目都会被包装成一个“Item”这是后续依赖图构建的最小单元。快照记录Count: 4其中前两项有明细## Item 1: Stmt 0, VarDeclarator(0) const a a; - Declares: a - Write: a ## Item 2: Stmt 1, VarDeclarator(0) const b b; - Declares: b - Write: b读法说明Item N中的N是条目在列表中的展示序号从 1 开始Stmt 0, VarDeclarator(0)表示该 Item 源自第 0 号模块语句中的第 0 个变量声明符即第一行const a aDeclares: a/Write: a是该 Item 对变量a的静态元信息声明并写入。这些字段并非随意输出而是逐条由测试打印逻辑写出见 tests.rs其中还支持Reads、Reads (eventual)、Write (eventual)等扩展字段供存在“延迟读写”的复杂用例使用。另外两个 ItemCount: 4的后两项在文本段没有展开明细但会作为Item3[export a]、Item4[export b]出现在后续 mermaid 图中——它们对应export { a, b }拆出的两条具名导出条目。也就是说两条const声明各成一个“写入型” Item两条具名导出各成一个“导出型” Item。在实现侧这种逐变量追踪的能力对应 module_fragments/mod.rs 中的VarState每个变量记录declarator、last_writes、last_reads与最近一次操作last_opRead/Write供分析器判断“谁在何时写、谁依赖谁的写入”这是判断依赖边与副作用的关键依据。Phase 1~4依赖图分四阶段构建output.md用四个连续的 mermaid 图记录依赖图增量构建的中间态。这四个 Phase 与 tests.rs 中的分析器调用一一对应也与 mod.rs 里Analyzer::analyze的主流程一致Phase触发动作源码调用说明Phase 1hoist_vars_and_bindings()收集变量提升信息与绑定建立全部 Item 节点Phase 2evaluate_immediate(...)对可立即求值的读/写进行定值首次产生依赖边Phase 3evaluate_eventual(...)处理无法立即确定、需要“最终态”才能确定的读写Phase 4handle_exports(...)把导出条目接入图中并解析其对变量的依赖Phase 1的完整图对应 output.md 中# Phase 1段此时只有 4 个孤立的节点——声明与导出尚未建立联系。Phase 2开始出现两条箭头该节完整图这两条边含义明确导出条目export a读取了变量a因此依赖 Item 1const a的声明/写入export b同理依赖 Item 2。这正是导出→声明的依赖关系被解析出来的瞬间。到了Phase 3、Phase 4图与Phase 2完全相同。原因是该模块全部为字符串字面量const初始化不存在函数调用、可变重赋值、typeof、顶层 await 等需要“最终态”判定或额外副作用处理的构造因此事件型eventual分析与导出处理都没有再引入新边。这种“多阶段图完全稳定”本身就是一种可断言的特性只要用例足够简单阶段间增量就应当为零一旦未来实现改变阶段划分快照 diff 会立刻暴露。Final 与分组导出与声明合并为一个碎片节点四个阶段之后代码调用handle_explicit_deps()处理显式依赖再调用g.finalize(...)把连通、强耦合的 Item 聚合成“碎片节点”。output.md的# Final段给出了聚合结果可以看到两个孤立的 Item 聚合为两个分组节点N0ItemId(0, VarDeclarator(0))第一条const a 导出a条目N1ItemId(1, VarDeclarator(0))第二条const b 导出b条目。这里ItemId(Export(...))中的#2是 SWC 的SyntaxContext编号用于区分词法作用域上下文可以不必深究重要的是**“导出条目与其依赖的声明被合并进同一碎片”**这一分组结果由于const a a无副作用导出a是该声明的唯一消费者两者天然构成一个不可再拆分的单元。后续打包时只 importa的消费方只需拿到N0对应碎片而不会被迫加载N1。对应的Entrypoints段进一步把“从哪个入口进入模块”与“落到哪个碎片”做了映射{ ModuleEvaluation: 3, Export( a, ): 0, Export( b, ): 1, Exports: 2, }可解读为求值入口ModuleEvaluation走碎片3导入具名导出a走碎片0导入b走碎片1模块整体“导出面”走碎片2。在快照格式上这一 Entrypoints 块会在Modules (dev)之后重复输出一次属于既定的输出结构并非分析结果出现两次。Modulesdev/prod四种代码碎片是如何产出的output.md随后以# Modules (dev)与# Modules (prod)分别打印split_module拆分出的全部代码碎片。对本用例两个模式的输出完全一致因为不存在开发模式专属的调试语义例如 HMR 需要保留的额外代码dev下内容如下## Part 0 const a a; export { a }; export { a as a } from __TURBOPACK_VAR__ assert { __turbopack_var__: true }; ## Part 1 const b b; export { b }; export { b as b } from __TURBOPACK_VAR__ assert { __turbopack_var__: true }; ## Part 2 export { a } from __TURBOPACK_PART__ assert { __turbopack_part__: export a }; export { b } from __TURBOPACK_PART__ assert { __turbopack_part__: export b }; ## Part 3 export { }; ## Merged (module eval) export { };对照前文 Entrypoints 可以建立清晰的对应关系Part 索引对应 Entrypoint内容语义Part 0Export(a)const a a 导出声明 一条指向__TURBOPACK_VAR__的合成再导出谁 importa就执行该碎片的声明并拿到绑定Part 1Export(b)与 Part 0 同理但作用于b谁 importb就执行该碎片Part 2Exports两条export ... from __TURBOPACK_PART__的转发声明模块导出面的“facade”统一汇总各具名导出Part 3ModuleEvaluation空export { }纯副作用求值入口两个特殊的内部模块标识符值得解释__TURBOPACK_PART__跨碎片引用占位符其assert { __turbopack_part__: export a }标注出“要从哪个碎片导出什么名字”。在真实代码生成阶段这一占位导入会被解析为对具体碎片的实际引用。源码中对应的常量在 mod.rs 定义为TURBOPACK_PART_IMPORT_SOURCE: str __TURBOPACK_PART__配套的工具函数create_turbopack_part_id_assert/find_turbopack_part_id_in_asserts也由该模块对外导出__TURBOPACK_VAR__变量虚拟模块占位符。碎片化之后const a的“活绑定”需要被安全地再导出给其它消费者于是生成一条export { a as a } from __TURBOPACK_VAR__ assert { __turbopack_var__: true }的合成再导出。从实现看这个虚拟模块 specifier 的生成位于 module_fragments/graph.rs 附近的碎片拆分逻辑中。最有信息量的是## Merged (module eval)把ModuleEvaluation入口指向的碎片Part 3再通过Merger递归合并对应 tests.rs 中按 Entrypoint 收集 Part 代码后用merger.merge_recursively合并的过程后得到的代码仅仅是export { }。这直观地说明树摇结论如果只“引入该模块触发副作用”则无需执行任何代码——因为两条const均以无副作用的字符串字面量初始化它们的“写入”只在被具体导入的碎片Part 0/1中发生若根本没有消费者导入a/b声明就不会被执行模块求值为空。快照测试机制强弱边、模式与合并最后补充快照后处理部分的生成逻辑帮助读者理解dev/prod与Merged的来源实现集中在 tests.rs测试对每个模式Mode::Development/Mode::Production克隆一份依赖图并执行g.handle_weak(...)用于区分强弱依赖边强边为执行模块所必需弱边为按需拉取的优化边调用g.split_module([], items)得到SplitModuleResult碎片列表 entrypoint 映射随后先打印# Entrypoints再逐个打印## Part N的代码Merged则是把某个 Entrypoint如ModuleEvaluation命中的碎片代码配合单模块加载器与Merger::merge_recursively递归合并后的“按入口展开”结果——它展示的是“从这个入口看模块最终长什么样”。因此同一份output.md既保留了“分析前各阶段依赖图”这一过程性信息也保留了“拆分后各碎片 入口合并结果”这一结果性信息非常适合作为图分析类算法改造的回归基准。仓库中tests/tree-shaker/analyzer/目录下还有大量同类用例如 complex、shared-2、effects-1、write-order、let-bug-1、tla-1在那些用例中可以看到图在 Phase 2/3/4 之间不断长出边、出现共享节点与副作用隔离等更丰富形态对照阅读即可掌握从“极简”到“真实业务模块”的完整分析行为谱系。由于该测试编译于turbopack-ecmascriptcrate 的单元测试模块module_fragments/tests.rs在具备 Rust 工具链的环境中可用cargo test -p turbopack-ecmascript一类方式运行该 crate 的测试以复现比对。小结树摇分析的最小单元是Item模块中的每条可追踪语句与每个导出都会被独立切片并标注Declares/Reads/Write等元信息依赖图在Phase 1~4变量绑定提升 → 立即求值 → 最终态求值 → 导出处理中增量构建simple-vars-1的快照展示了“导出 Item 依赖声明 Item”这一最基础边从无到有的过程Final 分组把相互依赖的 Item 聚合成碎片节点导出与其唯一依赖的无副作用声明被合并从而允许“按需只加载被 import 的碎片”碎片产出Part 0~3通过__TURBOPACK_VAR__变量虚拟模块与__TURBOPACK_PART__跨碎片引用两类占位符表达跨碎片再导出最终Merged (module eval)为空证明该模块在无人导入其导出时求值为零开销整份output.md由 module_fragments/tests.rs 中的快照框架自动生成并与文件比对是保证 Turbopack 模块级树摇行为不回归的可执行文档。【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考