Turbopack Tree Shaker 快照精读process.turbopack {}如何通过副作用分析被完整保留【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js本文以 next.js 仓库内turbopack-ecmascriptcrate 的node-globals测试快照为切入点逐段拆解 Turbopack 树摇Tree Shaker分析器的输出结构从Items元数据、Phase 1–4 依赖图演化到 dev/prod 两个模式下的模块拆分与合并结果。读完你将能读懂tests/tree-shaker/analyzer/**/output.md这类快照的每一个字段并理解为何对全局对象process的属性写入这类副作用语句永远不会被摇掉。快照在仓库中的角色output.md并非一份手写文档而是 Turbopack ECMAScript 模块拆分/树摇测试自动生成的黄金快照snapshot。它位于快照本身turbopack/crates/turbopack-ecmascript/tests/tree-shaker/analyzer/node-globals/output.md测试输入同目录下的turbopack/crates/turbopack-ecmascript/tests/tree-shaker/analyzer/node-globals/input.js可选配置同目录下的config.json本案例不存在回退为空配置整条测试目录turbopack/crates/turbopack-ecmascript/tests/tree-shaker/analyzer/下并列存放了约 40 组用例simple、dce、next-response、amphtml-document、otel-core等每组都由input.jsoutput.md组成个别带config.json。它背后的 fixture 驱动代码在turbopack/crates/turbopack-ecmascript/src/module_fragments/tests.rs核心一行是#[fixture(tests/tree-shaker/analyzer/**/input.js)] fn test_fixture(input: PathBuf) { run(input); }也就是说凡匹配该 glob 的input.js都会被当作一次独立测试运行解析模块、做依赖图分析与树摇、按固定模板渲染出一份报告再调用NormalizedOutput::compare_to_file(input.with_file_name(output.md))与快照逐字比对。本案例node-globals选用的输入极短仅一条对 Node 全局对象process的属性赋值// ts-ignore process.turbopack {};对应的快照就是我们本文要精读的对象。另外turbopack/crates/turbopack-ecmascript/Cargo.toml中声明了[[bench]] name analyzer且harness false说明analyzer相关的分析管线在仓库内是独立于普通单测的受控运行单元。快照逐段精读整份node-globals/output.md的正文结构是固定的Items→Phase 1~4→Final→Entrypoints→Modules (dev)→Entrypoints→Modules (prod)。下面按段拆解。1. Items输入被切成了多少个条目快照开头# Items Count: 1 ## Item 1: Stmt 0, Normal js process.turbopack {};Side effects这对应测试代码中 DepGraph::init 后对 item_ids 的逐个打印逻辑见 tests.rs。先看结果 - **Count: 1**整份模块只产生 1 个 Item。 - **Item 1: Stmt 0, Normal**该 Item 对应源文件第 0 条顶层语句Stmt 0Normal 是 Item 的种类kind。ItemId::Group 这类组条目如 ModuleEvaluation、export 组不会进入该列表会被 match id { ItemId::Group(_) continue, ... } 跳过。 - **Side effects**这是 Item 元数据标记意为该条语句被分析器判定为**带副作用**。 快照里的每条 Item 若还满足对应条件会继续追加 - Hoisted、- Declares: ...、- Reads: ...、- Write: ... 等标记行字段包括 is_hoisted、var_decls、read_vars、eventual_read_vars、write_vars、eventual_write_vars。node-globals 这个 Item 除了副作用标记外一无所有——它不声明任何模块级变量、不读取任何本地标识符纯粹是一次对外部对象 process 的写入所以在快照里只见一行 - Side effects。 ### 2. Phase 1–4 与 Final依赖图如何演化 output.md 接下来连续输出 4 张演化过程图和 1 张最终图全部以 Mermaid graph TD 表达。本案例四张阶段图完全一致  最终图则多了一层节点标签记录了被收缩/合并后的节点内包含哪些原始 Item  在测试代码里每次 writeln!(s, # Phase N) 都对应一次真实的分析器 pass见 tests.rs 的顺序 | 快照小节 | 触发的分析步骤 | 含义 | | --- | --- | --- | | # Phase 1 | hoist_vars_and_bindings() 之后 | 变量提升与绑定归类完成后立即绘制 | | # Phase 2 | evaluate_immediate(...) 之后 | 立即求值变量初始化、常量传播等即时可见效果 | | # Phase 3 | evaluate_eventual(...) 之后 | 延迟求值跨 Item 的最终读/写信息生效后 | | # Phase 4 | handle_exports(...) 之后 | 处理导出引用后再次绘制 | | # Final | handle_explicit_deps() 与 g.finalize(...) 之后 | 依赖图收缩合并用节点内 Items: [...] 展示每个最终节点对应的原始 Item 集合 | 图内元素也有固定语义每个 ItemN 节点表示一个 Item节点之间的边若为强依赖画实线 --弱依赖画虚线 -.-对应 render_graph 中 Dependency::Strong / Dependency::Weak 的分支。node-globals 中只有一个 Item、没有依赖边因此四张阶段图都是孤立节点 Item1而 Final 阶段节点被整合为一个标签 N0[Items: [ItemId(0, Normal)]] 明确告诉我们最终保留下来的这个执行单元就是那条 Normal 类型的副作用语句。 ### 3. Entrypoints拆分后的两个入口 紧跟在 Final 之后快照给出第一组入口点映射这是 dev 描述块打印的{ ModuleEvaluation: 0, Exports: 1, }在测试驱动里split_module 会把整份模块按依赖切分成若干 Part代码片段模块并产出一张 entrypoints 表Key → 在 parts 数组中的下标。{:#?} 排序列印后得到上面两个键值 - ModuleEvaluation: 0模块被求值module evaluation时需要执行的是下标为 0 的 Part即真正包含副作用代码的那一段 - Exports: 1外部通过 ESM 导入本模块的导出时走的是下标为 1 的 Part一份空的导出壳。 这正好呼应 1 中的结论副作用代码与导出外壳被拆成了两个独立单元模块求值与按名导入可以各自只加载自己需要的 Part。 ### 4. Modules (dev)开发模式下的 Part 拆分与合并Modules (dev)Part 0process.turbopack {}; export { };Part 1Merged (module eval)process.turbopack {}; export { };Entrypoints{ ModuleEvaluation: 0, Exports: 1, }上段 # Entrypoints 为便于阅读在此合并展示快照原文中它位于 Merged 之后紧随其后的才是 # Modules (prod)。 两个 Part 的含义非常清晰 - **Part 0**持有原副作用语句并自动补了一个空导出 export { };让它作为独立 ESM 模块仍然合法 - **Part 1**导出入口对应的空模块里面没有任何可执行代码Merged (module eval) 是测试把模块求值入口指向的 Part逐层递归合并后的最终产物——既然求值入口就是 Part 0合并结果自然与 Part 0 逐字一致。 这段输出由 describe(true, module eval, vec![ModuleEvaluation], false) 产生对应 handle_weak(Mode::Development)开发模式下弱依赖不会被丢弃保留最完整执行语义。 ### 5. Modules (prod)生产模式结果逐字相同Entrypoints{ ModuleEvaluation: 0, Exports: 1, }Modules (prod)Part 0process.turbopack {}; export { };Part 1Merged (module eval)process.turbopack {}; export { };这是第二次 describe(false, module eval, ...) 的输出内部走 handle_weak(Mode::Production)再 split_module 并按求值入口合并。对于本例**prod 与 dev 逐字一致**——这不是偶然而是由输入的性质决定的模块既没有导出任何命名也没有可省的弱依赖唯一的执行单元是一段不可删除的副作用语句所以无论什么模式它都必须原样进入产物。# Entrypoints 重复出现一次正对应测试代码中 dev / prod 两条 describe 分支各自打印入口点。 ## 原理纵深为什么这条语句摇不掉 把 process.turbopack {} 保留到底背后是树摇正确性的第一原则**可观察副作用不能删除**。 - process 在这里是解析阶段无法归因到本地绑定的全局对象输入中没有 import 也没有变量声明对它做属性写入属于对外部状态的修改 - 分析器无法证明运行时没有其他模块或宿主代码读取 process.turbopack因此这个 Item 被打上 Side effects 标记在 Final 阶段作为 [ItemId(0, Normal)] 完整存活 - 同一份输入既无 export也无读取所以产物里除了这条语句就是空导出壳。 把这组用例和它的邻居对比会更直观目录中的 dce/input.js 内容是 js import { baz } from ./module if (1 1 3) { baz(); }它是一个典型的可删除代码样本——恒假分支里的调用、连带被引入的baz导入都应当被摇掉而simple/input.js则是有声明 有导出的样本分析器要处理变量间读写依赖与命名导出的传播。是否有副作用、是否被导出消费决定了语句最终被保留还是被消除node-globals正好站在纯副作用、零导出这一极端上做回归验证。config.json机制也值得了解。fixture 运行时会读取同目录config.json缺省回退为{}。配置项只有一个{ exports: [ [c1_3], [c1_3, c2_2] ] }示例取自analyzer/3/config.json。exports是导出组合列表VecVecString允许一次测试多组导出场景每组导出一串都会在 prod 模式下额外触发一次describe用对应命名导出作为入口做模块拆分与合并从而验证按名导出时哪些 Part 被拉到产物中。node-globals没有config.json、没有可导出的名字故快照中只出现模块求值module eval这一种合并视角。这些快照背后的真实管线与下一步阅读从仓库结构看树摇/模块拆分能力并不是独立玩具crates/next-core/src/next_client/context.rs、crates/next-core/src/next_server/context.rs、crates/next-core/src/next_config.rs中都出现了对tree_shaker的引用说明 next-core 在构造 client/server 构建上下文时即接入了这套 ECMAScript 分析管线使 Next.js 的页面与应用代码在打包阶段能获得基于依赖图的分析结果。想继续深挖的读者可以按以下顺序阅读分析器与图结构实现turbopack/crates/turbopack-ecmascript/src/module_fragments/下的graph.rsDepGraph、ItemId、Dependency、merge.rsMerger与模块入口mod.rs它们分别对应快照中的 Items、依赖边与 Merged 段测试渲染逻辑本身turbopack/crates/turbopack-ecmascript/src/module_fragments/tests.rs的run/describe/render_graph/render_mermaid是理解output.md排版规则最直接的地图fixture 声明在 tests.rsPhase 输出顺序在 tests.rs对比同批其他快照如analyzer/simple变量与导出、analyzer/dce死代码删除、analyzer/effects-1副作用分析在/tests/tree-shaker/analyzer/目录内成对阅读input.js与output.md即可建立什么代码 → 什么产物的直觉。复现这套快照的成本很低在turbopack/工作区中执行cargo test -p turbopack-ecmascript即可让 fixture 扫描tests/tree-shaker/analyzer/**/input.js并逐一校验对应output.md。想亲手验证改输入会改快照只需编辑任意input.js后重新运行测试比较器会报告新的渲染结果与既有快照的差异——这正是把优化器行为固化进回归测试的标准姿势。【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Turbopack Tree Shaker 快照精读process.turbopack {}如何通过副作用分析被完整保留【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js本文以 next.js 仓库内turbopack-ecmascriptcrate 的node-globals测试快照为切入点逐段拆解 Turbopack 树摇Tree Shaker分析器的输出结构从Items元数据、Phase 1–4 依赖图演化到 dev/prod 两个模式下的模块拆分与合并结果。读完你将能读懂tests/tree-shaker/analyzer/**/output.md这类快照的每一个字段并理解为何对全局对象process的属性写入这类副作用语句永远不会被摇掉。快照在仓库中的角色output.md并非一份手写文档而是 Turbopack ECMAScript 模块拆分/树摇测试自动生成的黄金快照snapshot。它位于快照本身turbopack/crates/turbopack-ecmascript/tests/tree-shaker/analyzer/node-globals/output.md测试输入同目录下的turbopack/crates/turbopack-ecmascript/tests/tree-shaker/analyzer/node-globals/input.js可选配置同目录下的config.json本案例不存在回退为空配置整条测试目录turbopack/crates/turbopack-ecmascript/tests/tree-shaker/analyzer/下并列存放了约 40 组用例simple、dce、next-response、amphtml-document、otel-core等每组都由input.jsoutput.md组成个别带config.json。它背后的 fixture 驱动代码在turbopack/crates/turbopack-ecmascript/src/module_fragments/tests.rs核心一行是#[fixture(tests/tree-shaker/analyzer/**/input.js)] fn test_fixture(input: PathBuf) { run(input); }也就是说凡匹配该 glob 的input.js都会被当作一次独立测试运行解析模块、做依赖图分析与树摇、按固定模板渲染出一份报告再调用NormalizedOutput::compare_to_file(input.with_file_name(output.md))与快照逐字比对。本案例node-globals选用的输入极短仅一条对 Node 全局对象process的属性赋值// ts-ignore process.turbopack {};对应的快照就是我们本文要精读的对象。另外turbopack/crates/turbopack-ecmascript/Cargo.toml中声明了[[bench]] name analyzer且harness false说明analyzer相关的分析管线在仓库内是独立于普通单测的受控运行单元。快照逐段精读整份node-globals/output.md的正文结构是固定的Items→Phase 1~4→Final→Entrypoints→Modules (dev)→Entrypoints→Modules (prod)。下面按段拆解。1. Items输入被切成了多少个条目快照开头# Items Count: 1 ## Item 1: Stmt 0, Normal js process.turbopack {};Side effects这对应测试代码中 DepGraph::init 后对 item_ids 的逐个打印逻辑见 tests.rs。先看结果 - **Count: 1**整份模块只产生 1 个 Item。 - **Item 1: Stmt 0, Normal**该 Item 对应源文件第 0 条顶层语句Stmt 0Normal 是 Item 的种类kind。ItemId::Group 这类组条目如 ModuleEvaluation、export 组不会进入该列表会被 match id { ItemId::Group(_) continue, ... } 跳过。 - **Side effects**这是 Item 元数据标记意为该条语句被分析器判定为**带副作用**。 快照里的每条 Item 若还满足对应条件会继续追加 - Hoisted、- Declares: ...、- Reads: ...、- Write: ... 等标记行字段包括 is_hoisted、var_decls、read_vars、eventual_read_vars、write_vars、eventual_write_vars。node-globals 这个 Item 除了副作用标记外一无所有——它不声明任何模块级变量、不读取任何本地标识符纯粹是一次对外部对象 process 的写入所以在快照里只见一行 - Side effects。 ### 2. Phase 1–4 与 Final依赖图如何演化 output.md 接下来连续输出 4 张演化过程图和 1 张最终图全部以 Mermaid graph TD 表达。本案例四张阶段图完全一致  最终图则多了一层节点标签记录了被收缩/合并后的节点内包含哪些原始 Item  在测试代码里每次 writeln!(s, # Phase N) 都对应一次真实的分析器 pass见 tests.rs 的顺序 | 快照小节 | 触发的分析步骤 | 含义 | | --- | --- | --- | | # Phase 1 | hoist_vars_and_bindings() 之后 | 变量提升与绑定归类完成后立即绘制 | | # Phase 2 | evaluate_immediate(...) 之后 | 立即求值变量初始化、常量传播等即时可见效果 | | # Phase 3 | evaluate_eventual(...) 之后 | 延迟求值跨 Item 的最终读/写信息生效后 | | # Phase 4 | handle_exports(...) 之后 | 处理导出引用后再次绘制 | | # Final | handle_explicit_deps() 与 g.finalize(...) 之后 | 依赖图收缩合并用节点内 Items: [...] 展示每个最终节点对应的原始 Item 集合 | 图内元素也有固定语义每个 ItemN 节点表示一个 Item节点之间的边若为强依赖画实线 --弱依赖画虚线 -.-对应 render_graph 中 Dependency::Strong / Dependency::Weak 的分支。node-globals 中只有一个 Item、没有依赖边因此四张阶段图都是孤立节点 Item1而 Final 阶段节点被整合为一个标签 N0[Items: [ItemId(0, Normal)]] 明确告诉我们最终保留下来的这个执行单元就是那条 Normal 类型的副作用语句。 ### 3. Entrypoints拆分后的两个入口 紧跟在 Final 之后快照给出第一组入口点映射这是 dev 描述块打印的{ ModuleEvaluation: 0, Exports: 1, }在测试驱动里split_module 会把整份模块按依赖切分成若干 Part代码片段模块并产出一张 entrypoints 表Key → 在 parts 数组中的下标。{:#?} 排序列印后得到上面两个键值 - ModuleEvaluation: 0模块被求值module evaluation时需要执行的是下标为 0 的 Part即真正包含副作用代码的那一段 - Exports: 1外部通过 ESM 导入本模块的导出时走的是下标为 1 的 Part一份空的导出壳。 这正好呼应 1 中的结论副作用代码与导出外壳被拆成了两个独立单元模块求值与按名导入可以各自只加载自己需要的 Part。 ### 4. Modules (dev)开发模式下的 Part 拆分与合并Modules (dev)Part 0process.turbopack {}; export { };Part 1Merged (module eval)process.turbopack {}; export { };Entrypoints{ ModuleEvaluation: 0, Exports: 1, }上段 # Entrypoints 为便于阅读在此合并展示快照原文中它位于 Merged 之后紧随其后的才是 # Modules (prod)。 两个 Part 的含义非常清晰 - **Part 0**持有原副作用语句并自动补了一个空导出 export { };让它作为独立 ESM 模块仍然合法 - **Part 1**导出入口对应的空模块里面没有任何可执行代码Merged (module eval) 是测试把模块求值入口指向的 Part逐层递归合并后的最终产物——既然求值入口就是 Part 0合并结果自然与 Part 0 逐字一致。 这段输出由 describe(true, module eval, vec![ModuleEvaluation], false) 产生对应 handle_weak(Mode::Development)开发模式下弱依赖不会被丢弃保留最完整执行语义。 ### 5. Modules (prod)生产模式结果逐字相同Entrypoints{ ModuleEvaluation: 0, Exports: 1, }Modules (prod)Part 0process.turbopack {}; export { };Part 1Merged (module eval)process.turbopack {}; export { };这是第二次 describe(false, module eval, ...) 的输出内部走 handle_weak(Mode::Production)再 split_module 并按求值入口合并。对于本例**prod 与 dev 逐字一致**——这不是偶然而是由输入的性质决定的模块既没有导出任何命名也没有可省的弱依赖唯一的执行单元是一段不可删除的副作用语句所以无论什么模式它都必须原样进入产物。# Entrypoints 重复出现一次正对应测试代码中 dev / prod 两条 describe 分支各自打印入口点。 ## 原理纵深为什么这条语句摇不掉 把 process.turbopack {} 保留到底背后是树摇正确性的第一原则**可观察副作用不能删除**。 - process 在这里是解析阶段无法归因到本地绑定的全局对象输入中没有 import 也没有变量声明对它做属性写入属于对外部状态的修改 - 分析器无法证明运行时没有其他模块或宿主代码读取 process.turbopack因此这个 Item 被打上 Side effects 标记在 Final 阶段作为 [ItemId(0, Normal)] 完整存活 - 同一份输入既无 export也无读取所以产物里除了这条语句就是空导出壳。 把这组用例和它的邻居对比会更直观目录中的 dce/input.js 内容是 js import { baz } from ./module if (1 1 3) { baz(); }它是一个典型的可删除代码样本——恒假分支里的调用、连带被引入的baz导入都应当被摇掉而simple/input.js则是有声明 有导出的样本分析器要处理变量间读写依赖与命名导出的传播。是否有副作用、是否被导出消费决定了语句最终被保留还是被消除node-globals正好站在纯副作用、零导出这一极端上做回归验证。config.json机制也值得了解。fixture 运行时会读取同目录config.json缺省回退为{}。配置项只有一个{ exports: [ [c1_3], [c1_3, c2_2] ] }示例取自analyzer/3/config.json。exports是导出组合列表VecVecString允许一次测试多组导出场景每组导出一串都会在 prod 模式下额外触发一次describe用对应命名导出作为入口做模块拆分与合并从而验证按名导出时哪些 Part 被拉到产物中。node-globals没有config.json、没有可导出的名字故快照中只出现模块求值module eval这一种合并视角。这些快照背后的真实管线与下一步阅读从仓库结构看树摇/模块拆分能力并不是独立玩具crates/next-core/src/next_client/context.rs、crates/next-core/src/next_server/context.rs、crates/next-core/src/next_config.rs中都出现了对tree_shaker的引用说明 next-core 在构造 client/server 构建上下文时即接入了这套 ECMAScript 分析管线使 Next.js 的页面与应用代码在打包阶段能获得基于依赖图的分析结果。想继续深挖的读者可以按以下顺序阅读分析器与图结构实现turbopack/crates/turbopack-ecmascript/src/module_fragments/下的graph.rsDepGraph、ItemId、Dependency、merge.rsMerger与模块入口mod.rs它们分别对应快照中的 Items、依赖边与 Merged 段测试渲染逻辑本身turbopack/crates/turbopack-ecmascript/src/module_fragments/tests.rs的run/describe/render_graph/render_mermaid是理解output.md排版规则最直接的地图fixture 声明在 tests.rsPhase 输出顺序在 tests.rs对比同批其他快照如analyzer/simple变量与导出、analyzer/dce死代码删除、analyzer/effects-1副作用分析在/tests/tree-shaker/analyzer/目录内成对阅读input.js与output.md即可建立什么代码 → 什么产物的直觉。复现这套快照的成本很低在turbopack/工作区中执行cargo test -p turbopack-ecmascript即可让 fixture 扫描tests/tree-shaker/analyzer/**/input.js并逐一校验对应output.md。想亲手验证改输入会改快照只需编辑任意input.js后重新运行测试比较器会报告新的渲染结果与既有快照的差异——这正是把优化器行为固化进回归测试的标准姿势。【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
