解读 Turbopack Tree-Shaker 分析快照typeof引用下 Next.js 模块碎片化与依赖图四阶段演化【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.jstypeof-1是 Next.js 仓库中 Turbopack ECMAScript 编译管线 tree-shaker 分析器的测试用例之一它的产出物是一份结构化快照文件 output.md。本文以这份快照为骨架逐段拆解“模块 item 化 → 四阶段依赖图演化 → 图压缩 → dev/prod 分片与合并”的完整分析流程并结合 tests.rs、mod.rs 与 graph.rs 中的真实实现说明当一个 ESM 绑定仅被typeof间接引用时分析器如何建模“延迟读取eventual read”、如何保守地保留 import以及为何在 dev/prod 下生成完全一致的模块分片。读完你可以独立读懂 tree-shaker 目录下任意一份output.md快照。一、用例背景一个 App Router 风格的路由处理模块测试用例目录结构如下turbopack/crates/turbopack-ecmascript/tests/tree-shaker/analyzer/typeof-1/ ├── input.js # 待分析的输入模块 └── output.md # 分析结果的期望快照golden file输入文件 input.js 内容是一个典型的 Next.js App Router 风格模块import { NextResponse } from next/server import { ClientComponent } from ../../ClientComponent import { MyModuleClientComponent } from my-module/MyModuleClientComponent export function GET() { return NextResponse.json({ clientComponent: typeof ClientComponent, myModuleClientComponent: typeof MyModuleClientComponent, }) }从目录与模块命名可以推断该用例模拟了在路由处理函数Route Handler中通过typeof检测某个导入绑定的“形态”——例如判断目标是客户端组件还是服务端组件、目标模块是否已被正确装载。它刻意把三个导入的绑定放进一个被导出的、延迟执行的函数体内且只做typeof求值以此考察 tree-shaker 对“绑定被函数体间接读取eventual read”场景的处理是否保守、是否正确。测试的驱动方式是由 tests.rs 中声明的 fixture 自动扫描#[fixture(tests/tree-shaker/analyzer/**/input.js)] fn test_fixture(input: PathBuf) { run(input); }run会读取与input.js同目录的config.json若不存在则按{}处理config.json里的exports字段可指定额外测试多个导出组合见 tests.rs。typeof-1目录下没有config.json因此快照只覆盖 dev/prod 两种模式下的模块求值module eval合并结果没有额外的按导出拆分快照。输入模块会先用 SWC 解析并完成 resolver变量作用域标记再交给 tree-shaker 分析器。解析得到的完整Item清单、四个阶段的依赖图、Final压缩图、入口点与最终分片代码全部写入output.md作为期望结果。二、# Items模块如何被拆成 item快照第一个区块列出分析器从模块中识别出的全部条目item及其元数据。注意输出标题为Count: 8但详细清单只打印了 7 条——因为第 8 条Item8是一个Export(GET)的分组节点Group在清单循环中被ItemId::Group(_) continue跳过只在后面的 mermaid 依赖图中以Item8[export GET]出现见 tests.rs。1. 每条 import 被拆成“两个 item”typeof-1最值得注意的结构特征是一条 import 语句在依赖图中并非一个节点而是被拆分为两个 item它们共享同一个语句下标Stmt但具有不同的ItemKind展示编号StmtItemKind来源代码标注Item 1Stmt 0ImportOfModuleimport { NextResponse } from next/serverHoisted, Side effectsItem 2Stmt 0ImportBinding(0)同上Hoisted, Declares:NextResponseItem 3Stmt 1ImportOfModuleimport { ClientComponent } from ../../ClientComponentHoisted, Side effectsItem 4Stmt 1ImportBinding(0)同上Hoisted, Declares:ClientComponentItem 5Stmt 2ImportOfModuleimport { MyModuleClientComponent } from my-module/MyModuleClientComponentHoisted, Side effectsItem 6Stmt 2ImportBinding(0)同上Hoisted, Declares:MyModuleClientComponentItem 7Stmt 3Normalexport function GET() {...}Hoisted, Declares/Write:GETReads/Write (eventual):NextResponse等这一设计与 graph.rs 中的 item 类型枚举完全对应pub(crate) enum ItemIdItemKind { Normal, ImportOfModule, /// Imports are split as multiple items. /// /// Note that this item is not actually present in the module, and rather a phantom node. /// We only need this node to create an unique identifier for each binding in an import /// declaration. ImportBinding(u32), /// Reexport of a binding ReexportBinding(u32), VarDeclarator(u32), }其中ImportBinding(u32)是关键它是幻影节点phantom node——不对应模块中真实存在的代码只是为 import 声明的每个绑定提供唯一 ID从而在依赖图上表达“函数体读取了哪个导入绑定”。ItemId统一用Item { index, kind }定位到ModuleItem详见 graph.rs。2. 每类标注的含义每个 item 下方的标注由 tests.rs 依据 graph.rs 中ItemData的字段渲染Hoistedis_hoisted条目是否被提升。import、函数声明都属于提升类条目意味着它们在模块求值序中不依赖前面的普通语句。Side effectsside_effects条目本身可能触发副作用。三个ImportOfModule都被标记为有副作用——import 语句会对被导入模块求值即使当前模块最终没用到这些绑定只要 import 保留被导入模块仍会被执行。Declaresvar_decls条目声明的绑定即NextResponse/ClientComponent/MyModuleClientComponent/GET。Readsread_vars与Reads (eventual)eventual_read_vars前者是模块求值阶段立即发生的读取后者是在延迟执行的函数体内才会发生的读取。Item 7GET的所有读取都是 eventual——函数体不会在模块加载时执行。Writewrite_vars与Write (eventual)eventual_write_vars条目对绑定的写入。GET写入自身函数名绑定并 eventual 写入NextResponse。对typeof用例而言Reads (eventual): NextResponse, ClientComponent, MyModuleClientComponent这行是全文最重要的信号三个导入绑定都没有在模块顶层被立即读取它们只在导出的GET函数内部以typeof形式被“延迟读取”。分析器据此必须为它们建立到对应ImportBinding节点的依赖否则打包器可能在碎片化阶段错误地把这些绑定乃至整条 import删掉。三、Phase 1–4依赖图如何逐步长出来快照的中段用 mermaid 图记录了依赖图在四轮分析后的形态。这个渲染顺序与 tests.rs 中Analyzer的调用序列一一对应也与生产路径 mod.rs 的analyze()完全同构let eventual_ids analyzer.hoist_vars_and_bindings(); // 之后打印 Phase 1 analyzer.evaluate_immediate(module, eventual_ids); // 之后打印 Phase 2 analyzer.evaluate_eventual(module); // 之后打印 Phase 3 analyzer.handle_exports(module); // 之后打印 Phase 4 analyzer.handle_explicit_deps(); let mut condensed analyzer.g.finalize(analyzer.items); // 之后打印 Final四张图的节点集合始终是 Item1–Item8八个 item边随分析推进逐步增加。快照中边的方向约定为“A → B 表示 A 依赖 B”例如 Item2→Item1 表示 NextResponse 的绑定条目依赖其所属 import 语句这与 graph.rs 中“ImportBinding should depend on actual import statements”的注释一致。下面按阶段增量解读。Phase 1 —— 完成变量提升与绑定悬挂hoist_vars_and_bindingsPhase 1 只有两条边Item2 → Item1NextResponse 的ImportBinding幻影节点被挂在同一条 import 语句的ImportOfModule上。Item3 → Item2第二条 importClientComponent 的ImportOfModule带副作用依赖前一条 import 的绑定形成 ESM 顶层求值顺序链——模块级语句必须按源码顺序执行后续可能产生副作用的 import 需要排在先前 import 所建立的“最后副作用点”之后。从源码结构看这一步通过hoist_vars_and_bindings收集所有 eventual 读写变量并把提升类条目与绑定先串联成骨架属于 mod.rs 注释所定义的“Phase 1: Hoisted Variables and Bindings”。Phase 2 —— 立即求值evaluate_immediate新增Item8 → Item7导出分组节点“export GET”依赖GET这一 Normal item。这是在处理模块求值期立即发生的引用模块以export function GET()导出导出本身是模块顶层行为因此立刻把 export 节点与函数条目相连。Phase 3 —— 延迟求值evaluate_eventual这一阶段新增的三条边是全文的核心结论Item7 → Item4GET依赖 ClientComponent 的ImportBinding。Item7 → Item6GET依赖 MyModuleClientComponent 的ImportBinding。Item7 → Item5GET还依赖 MyModuleClientComponent 的ImportOfModule保持 import 顺序链的完整。也就是说仅仅因为在被导出函数的函数体里写了typeof ClientComponent和typeof MyModuleClientComponent这两个导入绑定的依赖就被完整记录下来。evaluate_eventual遍历函数体内的“延迟”引用把读取者GET连到变量的“最后声明点/最后写入点”这正是 mod.rs 中VarState里last_reads/last_writes追踪的结果。相比之下NextResponse虽也在GET中被NextResponse.json(...)调用但它的读取路径通过Item3 → Item2 → Item1已间接连通因此没有重复加边。Phase 4 —— 处理导出handle_exportsPhase 4 的图与 Phase 3 完全相同没有新增边。这说明“export GET”这一分组在 Phase 2 就已连好handle_exports在无重导出、无额外导出依赖的本用例中没有引入新的依赖关系。四、# Final图压缩与绑定碎片化四阶段分析结束后依赖图被finalize压缩为强连通分量condensation见快照的# Final段这张图揭示了 tree-shaker 碎片化的核心结果核心组 N0收纳了三条ImportOfModule、NormalGET 函数以及Export(GET)分组——也就是“必须整体保留、负责模块求值”的部分。三整条 import 语句都留在了核心组即使这些绑定在模块顶层完全没被读取因为① import 语句本身有副作用② 它们被导出函数GET在延迟执行时读取。三个绑定碎片 N1 / N2 / N3三个ImportBinding(0)幻影节点被单独拧出来成为独立组件分别代表 NextResponse、ClientComponent、MyModuleClientComponent 三个绑定。这样设计使每个绑定拥有独立的“生死判定”粒度当某个绑定真正无人使用时它可以在后续碎片化split_module时被单独剔除而不必波及整条 import。N0 → N1 / N2 / N3的边表明核心组依赖这些绑定碎片。对比N0的条目列表可以发现一个有意思的细节N0 内已经包含了三条 import 语句对应的ItemId(0..2, ImportOfModule)与函数Normal而绑定被外置为 N1–N3因此 import 与绑定的“合与分”是完全正交的——import 语句天然不可删副作用绑定是否保留则取决于可达性分析。这种“绑定级”而非“语句级”的粒度是 module fragments 设计区别于传统单模块 tree-shaking 的关键。五、入口点与 dev/prod 分片handle_weak之后进入split_module测试用Mode::Development与Mode::Production分别跑一遍见 tests.rs所以快照中# Entrypoints、# Modules (dev)、# Modules (prod)各出现一次。typeof-1没有config.json指定额外导出故 dev/prod 两次都只按ModuleEvaluation这一入口合并。入口点映射{ ModuleEvaluation: 0, Export(GET): 0, Exports: 1, }含义模块求值module eval入口和Export(GET)入口都映射到Part 0对外导出的符号数为 1即GET。也就是说任何入口最终都汇聚到同一个核心分片。Modules (dev) / Modules (prod) 分片代码Part 0 是完整模块体值得注意的是它逐字保留了全部三条 import 的两种形态——既保留具名绑定导入又追加了仅供副作用的三行纯导入import { MyModuleClientComponent } from my-module/MyModuleClientComponent; import { NextResponse } from next/server; import { ClientComponent } from ../../ClientComponent; import next/server; import ../../ClientComponent; import my-module/MyModuleClientComponent; function GET() { return NextResponse.json({ clientComponent: typeof ClientComponent, myModuleClientComponent: typeof MyModuleClientComponent }); } export { GET }; export { GET as a } from __TURBOPACK_VAR__ assert { __turbopack_var__: true }; export { };后半段是 Turbopack 模块碎片化使用的内部协议export { GET }真实的具名导出export { GET as a } from __TURBOPACK_VAR__ assert { __turbopack_var__: true }通过占位模块源__TURBOPACK_VAR__表达“本模块导出一个 var 级依赖”export { }空的具名导出兜底末尾三行裸 importimport next/server等是副作用保留的显式呈现分析器把“保留 import 语句对目标模块求值产生的副作用”与“保留绑定供函数使用”两件事拆开表达最终产物里两者都在。Part 1 是一个极薄的再导出分片使用另一个占位源export { GET } from __TURBOPACK_PART__ assert { __turbopack_part__: export GET };__TURBOPACK_PART__正是 mod.rs 中声明的协议常量pub(crate) const TURBOPACK_PART_IMPORT_SOURCE: str __TURBOPACK_PART__;它表示“从另一个分片part导入”配合__turbopack_var__这类断言让下游模块合并器merge.rs 中的Merger能够递归地把分片重新拼装成最终可执行的 ESM 模块。Merged (module eval)快照末尾把 Part 0 与 Part 1 按模块求值入口合并得到的“Merged (module eval)”产物与 Part 0 完全一致——因为 Part 1 只是再导出薄片不贡献任何函数体。dev 与 prod 两套产物逐字节相同这并非偶然handle_weak中弱依赖的裁剪只在生产模式下生效见 graph.rs 附近的fn handle_weak其中Mode::Production分支会删掉弱边而本用例中所有依赖均为强依赖import 副作用、函数体延迟读取、导出不存在可以被弱化剪枝的边因此两种模式殊途同归。六、这份快照告诉我们什么综合整个output.md可以提炼出以下可复用的技术结论typeof不是 tree-shaker 的“免死金牌”。虽然typeof x本身不会触发x的取值在普通脚本里即使x未声明也只会得到undefined但当x是 ESM 绑定、且被放进导出并延迟执行的函数时删除 import 会改变语义绑定不存在、副作用丢失、typeof结果被改写因此 Turbopack 的分析器选择保守处理凡是出现在导出函数体内的绑定引用无论是否typeof都记为 eventual read并建立强依赖。绑定粒度的碎片化是核心机制。ImportOfModule与ImportBinding分离使得“import 副作用”与“绑定可达性”可以分别决策Final 图中核心组与三个绑定碎片的拓扑清楚地展示了这种“合中有分”的结构。快照本身就是一份可执行的行为规格。output.md与input.js一一对应任何改动分析器导致依赖图、分片代码或合并产物变化的 PR都会在此类快照用例上留下 diff。同目录下的兄弟用例如 route-handler、next-response、dce、combined-export分别覆盖路由处理器、NextResponse、死代码消除与组合导出等不同形态与typeof-1相互印证是理解整个 module fragments 设计的最佳阅读材料。如何亲手复现与验证在仓库根目录运行对应 crate 的 fixture 测试即可重新生成/校验快照例如cargo test -p turbopack-ecmascript tree_shaker该 crate 位于turbopack/crates/turbopack-ecmascript测试入口在 tests.rs。若需要观察其他输入形态可在任意analyzer/case/目录中放一份新的input.js分析器会按其解析路径自动跑出对应输出。读懂typeof-1/output.md你就掌握了阅读 tree-shaker 家族所有快照的通用方法论先看# Items掌握“谁被拆成了谁”再看 Phase 1–4 把握“边在哪个阶段长出来”然后看# Final明确“哪些绑定被独立成碎片”最后对照 dev/prod 的 Parts 与 Merged 产物验证最终代码形态。这套方法同样适用于阅读 Turbopack 中optimizer等其他变换产出的快照。【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 解读 Turbopack Tree-Shaker 分析快照：`typeof` 引用下 Next.js 模块碎片化与依赖图四阶段演化
解读 Turbopack Tree-Shaker 分析快照typeof引用下 Next.js 模块碎片化与依赖图四阶段演化【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.jstypeof-1是 Next.js 仓库中 Turbopack ECMAScript 编译管线 tree-shaker 分析器的测试用例之一它的产出物是一份结构化快照文件 output.md。本文以这份快照为骨架逐段拆解“模块 item 化 → 四阶段依赖图演化 → 图压缩 → dev/prod 分片与合并”的完整分析流程并结合 tests.rs、mod.rs 与 graph.rs 中的真实实现说明当一个 ESM 绑定仅被typeof间接引用时分析器如何建模“延迟读取eventual read”、如何保守地保留 import以及为何在 dev/prod 下生成完全一致的模块分片。读完你可以独立读懂 tree-shaker 目录下任意一份output.md快照。一、用例背景一个 App Router 风格的路由处理模块测试用例目录结构如下turbopack/crates/turbopack-ecmascript/tests/tree-shaker/analyzer/typeof-1/ ├── input.js # 待分析的输入模块 └── output.md # 分析结果的期望快照golden file输入文件 input.js 内容是一个典型的 Next.js App Router 风格模块import { NextResponse } from next/server import { ClientComponent } from ../../ClientComponent import { MyModuleClientComponent } from my-module/MyModuleClientComponent export function GET() { return NextResponse.json({ clientComponent: typeof ClientComponent, myModuleClientComponent: typeof MyModuleClientComponent, }) }从目录与模块命名可以推断该用例模拟了在路由处理函数Route Handler中通过typeof检测某个导入绑定的“形态”——例如判断目标是客户端组件还是服务端组件、目标模块是否已被正确装载。它刻意把三个导入的绑定放进一个被导出的、延迟执行的函数体内且只做typeof求值以此考察 tree-shaker 对“绑定被函数体间接读取eventual read”场景的处理是否保守、是否正确。测试的驱动方式是由 tests.rs 中声明的 fixture 自动扫描#[fixture(tests/tree-shaker/analyzer/**/input.js)] fn test_fixture(input: PathBuf) { run(input); }run会读取与input.js同目录的config.json若不存在则按{}处理config.json里的exports字段可指定额外测试多个导出组合见 tests.rs。typeof-1目录下没有config.json因此快照只覆盖 dev/prod 两种模式下的模块求值module eval合并结果没有额外的按导出拆分快照。输入模块会先用 SWC 解析并完成 resolver变量作用域标记再交给 tree-shaker 分析器。解析得到的完整Item清单、四个阶段的依赖图、Final压缩图、入口点与最终分片代码全部写入output.md作为期望结果。二、# Items模块如何被拆成 item快照第一个区块列出分析器从模块中识别出的全部条目item及其元数据。注意输出标题为Count: 8但详细清单只打印了 7 条——因为第 8 条Item8是一个Export(GET)的分组节点Group在清单循环中被ItemId::Group(_) continue跳过只在后面的 mermaid 依赖图中以Item8[export GET]出现见 tests.rs。1. 每条 import 被拆成“两个 item”typeof-1最值得注意的结构特征是一条 import 语句在依赖图中并非一个节点而是被拆分为两个 item它们共享同一个语句下标Stmt但具有不同的ItemKind展示编号StmtItemKind来源代码标注Item 1Stmt 0ImportOfModuleimport { NextResponse } from next/serverHoisted, Side effectsItem 2Stmt 0ImportBinding(0)同上Hoisted, Declares:NextResponseItem 3Stmt 1ImportOfModuleimport { ClientComponent } from ../../ClientComponentHoisted, Side effectsItem 4Stmt 1ImportBinding(0)同上Hoisted, Declares:ClientComponentItem 5Stmt 2ImportOfModuleimport { MyModuleClientComponent } from my-module/MyModuleClientComponentHoisted, Side effectsItem 6Stmt 2ImportBinding(0)同上Hoisted, Declares:MyModuleClientComponentItem 7Stmt 3Normalexport function GET() {...}Hoisted, Declares/Write:GETReads/Write (eventual):NextResponse等这一设计与 graph.rs 中的 item 类型枚举完全对应pub(crate) enum ItemIdItemKind { Normal, ImportOfModule, /// Imports are split as multiple items. /// /// Note that this item is not actually present in the module, and rather a phantom node. /// We only need this node to create an unique identifier for each binding in an import /// declaration. ImportBinding(u32), /// Reexport of a binding ReexportBinding(u32), VarDeclarator(u32), }其中ImportBinding(u32)是关键它是幻影节点phantom node——不对应模块中真实存在的代码只是为 import 声明的每个绑定提供唯一 ID从而在依赖图上表达“函数体读取了哪个导入绑定”。ItemId统一用Item { index, kind }定位到ModuleItem详见 graph.rs。2. 每类标注的含义每个 item 下方的标注由 tests.rs 依据 graph.rs 中ItemData的字段渲染Hoistedis_hoisted条目是否被提升。import、函数声明都属于提升类条目意味着它们在模块求值序中不依赖前面的普通语句。Side effectsside_effects条目本身可能触发副作用。三个ImportOfModule都被标记为有副作用——import 语句会对被导入模块求值即使当前模块最终没用到这些绑定只要 import 保留被导入模块仍会被执行。Declaresvar_decls条目声明的绑定即NextResponse/ClientComponent/MyModuleClientComponent/GET。Readsread_vars与Reads (eventual)eventual_read_vars前者是模块求值阶段立即发生的读取后者是在延迟执行的函数体内才会发生的读取。Item 7GET的所有读取都是 eventual——函数体不会在模块加载时执行。Writewrite_vars与Write (eventual)eventual_write_vars条目对绑定的写入。GET写入自身函数名绑定并 eventual 写入NextResponse。对typeof用例而言Reads (eventual): NextResponse, ClientComponent, MyModuleClientComponent这行是全文最重要的信号三个导入绑定都没有在模块顶层被立即读取它们只在导出的GET函数内部以typeof形式被“延迟读取”。分析器据此必须为它们建立到对应ImportBinding节点的依赖否则打包器可能在碎片化阶段错误地把这些绑定乃至整条 import删掉。三、Phase 1–4依赖图如何逐步长出来快照的中段用 mermaid 图记录了依赖图在四轮分析后的形态。这个渲染顺序与 tests.rs 中Analyzer的调用序列一一对应也与生产路径 mod.rs 的analyze()完全同构let eventual_ids analyzer.hoist_vars_and_bindings(); // 之后打印 Phase 1 analyzer.evaluate_immediate(module, eventual_ids); // 之后打印 Phase 2 analyzer.evaluate_eventual(module); // 之后打印 Phase 3 analyzer.handle_exports(module); // 之后打印 Phase 4 analyzer.handle_explicit_deps(); let mut condensed analyzer.g.finalize(analyzer.items); // 之后打印 Final四张图的节点集合始终是 Item1–Item8八个 item边随分析推进逐步增加。快照中边的方向约定为“A → B 表示 A 依赖 B”例如 Item2→Item1 表示 NextResponse 的绑定条目依赖其所属 import 语句这与 graph.rs 中“ImportBinding should depend on actual import statements”的注释一致。下面按阶段增量解读。Phase 1 —— 完成变量提升与绑定悬挂hoist_vars_and_bindingsPhase 1 只有两条边Item2 → Item1NextResponse 的ImportBinding幻影节点被挂在同一条 import 语句的ImportOfModule上。Item3 → Item2第二条 importClientComponent 的ImportOfModule带副作用依赖前一条 import 的绑定形成 ESM 顶层求值顺序链——模块级语句必须按源码顺序执行后续可能产生副作用的 import 需要排在先前 import 所建立的“最后副作用点”之后。从源码结构看这一步通过hoist_vars_and_bindings收集所有 eventual 读写变量并把提升类条目与绑定先串联成骨架属于 mod.rs 注释所定义的“Phase 1: Hoisted Variables and Bindings”。Phase 2 —— 立即求值evaluate_immediate新增Item8 → Item7导出分组节点“export GET”依赖GET这一 Normal item。这是在处理模块求值期立即发生的引用模块以export function GET()导出导出本身是模块顶层行为因此立刻把 export 节点与函数条目相连。Phase 3 —— 延迟求值evaluate_eventual这一阶段新增的三条边是全文的核心结论Item7 → Item4GET依赖 ClientComponent 的ImportBinding。Item7 → Item6GET依赖 MyModuleClientComponent 的ImportBinding。Item7 → Item5GET还依赖 MyModuleClientComponent 的ImportOfModule保持 import 顺序链的完整。也就是说仅仅因为在被导出函数的函数体里写了typeof ClientComponent和typeof MyModuleClientComponent这两个导入绑定的依赖就被完整记录下来。evaluate_eventual遍历函数体内的“延迟”引用把读取者GET连到变量的“最后声明点/最后写入点”这正是 mod.rs 中VarState里last_reads/last_writes追踪的结果。相比之下NextResponse虽也在GET中被NextResponse.json(...)调用但它的读取路径通过Item3 → Item2 → Item1已间接连通因此没有重复加边。Phase 4 —— 处理导出handle_exportsPhase 4 的图与 Phase 3 完全相同没有新增边。这说明“export GET”这一分组在 Phase 2 就已连好handle_exports在无重导出、无额外导出依赖的本用例中没有引入新的依赖关系。四、# Final图压缩与绑定碎片化四阶段分析结束后依赖图被finalize压缩为强连通分量condensation见快照的# Final段这张图揭示了 tree-shaker 碎片化的核心结果核心组 N0收纳了三条ImportOfModule、NormalGET 函数以及Export(GET)分组——也就是“必须整体保留、负责模块求值”的部分。三整条 import 语句都留在了核心组即使这些绑定在模块顶层完全没被读取因为① import 语句本身有副作用② 它们被导出函数GET在延迟执行时读取。三个绑定碎片 N1 / N2 / N3三个ImportBinding(0)幻影节点被单独拧出来成为独立组件分别代表 NextResponse、ClientComponent、MyModuleClientComponent 三个绑定。这样设计使每个绑定拥有独立的“生死判定”粒度当某个绑定真正无人使用时它可以在后续碎片化split_module时被单独剔除而不必波及整条 import。N0 → N1 / N2 / N3的边表明核心组依赖这些绑定碎片。对比N0的条目列表可以发现一个有意思的细节N0 内已经包含了三条 import 语句对应的ItemId(0..2, ImportOfModule)与函数Normal而绑定被外置为 N1–N3因此 import 与绑定的“合与分”是完全正交的——import 语句天然不可删副作用绑定是否保留则取决于可达性分析。这种“绑定级”而非“语句级”的粒度是 module fragments 设计区别于传统单模块 tree-shaking 的关键。五、入口点与 dev/prod 分片handle_weak之后进入split_module测试用Mode::Development与Mode::Production分别跑一遍见 tests.rs所以快照中# Entrypoints、# Modules (dev)、# Modules (prod)各出现一次。typeof-1没有config.json指定额外导出故 dev/prod 两次都只按ModuleEvaluation这一入口合并。入口点映射{ ModuleEvaluation: 0, Export(GET): 0, Exports: 1, }含义模块求值module eval入口和Export(GET)入口都映射到Part 0对外导出的符号数为 1即GET。也就是说任何入口最终都汇聚到同一个核心分片。Modules (dev) / Modules (prod) 分片代码Part 0 是完整模块体值得注意的是它逐字保留了全部三条 import 的两种形态——既保留具名绑定导入又追加了仅供副作用的三行纯导入import { MyModuleClientComponent } from my-module/MyModuleClientComponent; import { NextResponse } from next/server; import { ClientComponent } from ../../ClientComponent; import next/server; import ../../ClientComponent; import my-module/MyModuleClientComponent; function GET() { return NextResponse.json({ clientComponent: typeof ClientComponent, myModuleClientComponent: typeof MyModuleClientComponent }); } export { GET }; export { GET as a } from __TURBOPACK_VAR__ assert { __turbopack_var__: true }; export { };后半段是 Turbopack 模块碎片化使用的内部协议export { GET }真实的具名导出export { GET as a } from __TURBOPACK_VAR__ assert { __turbopack_var__: true }通过占位模块源__TURBOPACK_VAR__表达“本模块导出一个 var 级依赖”export { }空的具名导出兜底末尾三行裸 importimport next/server等是副作用保留的显式呈现分析器把“保留 import 语句对目标模块求值产生的副作用”与“保留绑定供函数使用”两件事拆开表达最终产物里两者都在。Part 1 是一个极薄的再导出分片使用另一个占位源export { GET } from __TURBOPACK_PART__ assert { __turbopack_part__: export GET };__TURBOPACK_PART__正是 mod.rs 中声明的协议常量pub(crate) const TURBOPACK_PART_IMPORT_SOURCE: str __TURBOPACK_PART__;它表示“从另一个分片part导入”配合__turbopack_var__这类断言让下游模块合并器merge.rs 中的Merger能够递归地把分片重新拼装成最终可执行的 ESM 模块。Merged (module eval)快照末尾把 Part 0 与 Part 1 按模块求值入口合并得到的“Merged (module eval)”产物与 Part 0 完全一致——因为 Part 1 只是再导出薄片不贡献任何函数体。dev 与 prod 两套产物逐字节相同这并非偶然handle_weak中弱依赖的裁剪只在生产模式下生效见 graph.rs 附近的fn handle_weak其中Mode::Production分支会删掉弱边而本用例中所有依赖均为强依赖import 副作用、函数体延迟读取、导出不存在可以被弱化剪枝的边因此两种模式殊途同归。六、这份快照告诉我们什么综合整个output.md可以提炼出以下可复用的技术结论typeof不是 tree-shaker 的“免死金牌”。虽然typeof x本身不会触发x的取值在普通脚本里即使x未声明也只会得到undefined但当x是 ESM 绑定、且被放进导出并延迟执行的函数时删除 import 会改变语义绑定不存在、副作用丢失、typeof结果被改写因此 Turbopack 的分析器选择保守处理凡是出现在导出函数体内的绑定引用无论是否typeof都记为 eventual read并建立强依赖。绑定粒度的碎片化是核心机制。ImportOfModule与ImportBinding分离使得“import 副作用”与“绑定可达性”可以分别决策Final 图中核心组与三个绑定碎片的拓扑清楚地展示了这种“合中有分”的结构。快照本身就是一份可执行的行为规格。output.md与input.js一一对应任何改动分析器导致依赖图、分片代码或合并产物变化的 PR都会在此类快照用例上留下 diff。同目录下的兄弟用例如 route-handler、next-response、dce、combined-export分别覆盖路由处理器、NextResponse、死代码消除与组合导出等不同形态与typeof-1相互印证是理解整个 module fragments 设计的最佳阅读材料。如何亲手复现与验证在仓库根目录运行对应 crate 的 fixture 测试即可重新生成/校验快照例如cargo test -p turbopack-ecmascript tree_shaker该 crate 位于turbopack/crates/turbopack-ecmascript测试入口在 tests.rs。若需要观察其他输入形态可在任意analyzer/case/目录中放一份新的input.js分析器会按其解析路径自动跑出对应输出。读懂typeof-1/output.md你就掌握了阅读 tree-shaker 家族所有快照的通用方法论先看# Items掌握“谁被拆成了谁”再看 Phase 1–4 把握“边在哪个阶段长出来”然后看# Final明确“哪些绑定被独立成碎片”最后对照 dev/prod 的 Parts 与 Merged 产物验证最终代码形态。这套方法同样适用于阅读 Turbopack 中optimizer等其他变换产出的快照。【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考