Next.js Turbopack 模块切分树摇剖析：turbopack-ecmascript 中 ipc-evaluate 快照测试逐段解读

Next.js Turbopack 模块切分树摇剖析：turbopack-ecmascript 中 ipc-evaluate 快照测试逐段解读

【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js

output.md并不是人工撰写的文档，而是 Next.js 仓库中 Turbopack 打包器核心 crateturbopack-ecmascript的一个快照测试（snapshot test）产物：它记录了“模块碎片化分析器（module fragments / tree-shaker analyzer）”对一个真实 Node.js IPC 求值模块的完整处理结果——从顶层语句切分为 6 个“条目（Item）”，到四阶段依赖图（Phase 1~4）与最终分组（Final），再到按入口拆分出的 dev/prod 两份模块碎片与合并结果。读完本文，你将理解 Turbopack 是如何把一个 ES 模块拆成可独立调度的执行片段、如何用__TURBOPACK_PART__/__TURBOPACK_VAR__协议在碎片之间重建引用，以及如何用UPDATE=1命令复现并更新这份快照。

一、文件定位：output.md是测试框架自动比对的“期望输出”

该快照位于测试用例目录 ipc-evaluate，与输入文件 input.js 成对出现。驱动它的是 src/module_fragments/tests.rs 中的 fixture 声明：

#[fixture("tests/tree-shaker/analyzer/**/input.js")] fn test_fixture(input: PathBuf) { run(input); }

从源码结构看，tests/tree-shaker/analyzer/下的每一个子目录（如ipc-evaluate、ipc-index、node-fetch、otel-core等 30 多个用例）就是一个回归锚点：测试框架解析input.js，跑完整个模块切分/树摇流水线，把结果渲染成一个长字符串，再与同目录的output.md逐字比对（tests.rs 中的NormalizedOutput::from(s).compare_to_file(...)）。只要分析器行为发生任何变化——多画了一条依赖边、少切了一个 Part、变量改名规则变了——快照比对就会失败，从而把“树摇结果”钉死为可审计的文本。

刷新快照的方式在 turbopack-ecmascript/readme.md 中有说明，为测试进程设置环境变量UPDATE=1即可重写全部output.md：

UPDATE=1 cargo test -p turbopack-ecmascript

此外，每个用例目录可以放一个可选的config.json。tests.rs 中的TestConfig只有一个字段exports: Vec<Vec<String>>，用于额外验证“只保留某几个具名导出”时的碎片化结果；ipc-evaluate用例没有config.json，框架按默认空配置{}处理，因此output.md中只出现module eval一组合并结果。

二、测试输入：一个真实的 IPC 求值循环模块

input.js是 Turbopack 内部用于“跨进程求值（evaluate）”场景的模块（与姊妹用例 ipc-index/input.js 中的 socket 版 IPC 相对应，本用例基于消息管道而非 TCP）。完整源码如下，仅 94 行，结构清晰：顶部两条const声明 + 一个导出的async run函数。

import { IPC } from "./index"; const ipc = IPC; const queue = []; export const run = async (moduleFactory)=>{ let nextId = 1; const requests = new Map(); const internalIpc = { sendInfo: (message)=>ipc.send({ type: "info", data: message }), sendRequest: (message)=>{ const id = nextId++; let resolve, reject; const promise = new Promise((res, rej)=>{ resolve = res; reject = rej; }); requests.set(id, { resolve, reject }); return ipc.send({ type: "request", id, data: message }).then(()=>promise); }, sendError: (error)=>{ return ipc.sendError(error); } }; let getValue; try { const module = await moduleFactory(); if (typeof module.init === "function") { await module.init(); } getValue = module.default; await ipc.sendReady(); } catch (err) { await ipc.sendReady(); await ipc.sendError(err); } let isRunning = false; const run = async ()=>{ while(queue.length > 0){ const args = queue.shift(); try { const value = await getValue(internalIpc, ...args); await ipc.send({ type: "end", data: value === undefined ? undefined : JSON.stringify(value, null, 2), duration: 0 }); } catch (e) { await ipc.sendError(e); } } isRunning = false; }; while(true){ const msg = await ipc.recv(); switch(msg.type){ case "evaluate": { queue.push(msg.args); if (!isRunning) { isRunning = true; run(); } break; } case "result": { const request = requests.get(msg.id); if (request) { requests.delete(msg.id); if (msg.error) { request.reject(new Error(msg.error)); } else { request.resolve(msg.data); } } break; } default: { console.error("unexpected message type", msg.type); process.exit(1); } } } };

这段代码的运行语义是：run(moduleFactory)被调用后，先通过moduleFactory()异步加载目标模块（支持可选的module.init()初始化钩子），然后进入一个while(true)消息循环——收到evaluate消息就把参数压入queue并串行执行getValue(internalIpc, ...args)，结果以type: "end"消息经 IPC 回传；sendRequest则用自增id+Map把一次请求与它未来的result消息配对，实现“请求-响应”语义。对这个模块做树摇分析的价值在于：它同时包含了具名导入（IPC）、导入后别名赋值（ipc = IPC）、顶层可变数组（queue）和一个包含闭包、await、无限循环的导出函数，恰好覆盖分析器需要判定的多种变量读写模式。

三、# Items：顶层语句如何被切成 6 个分析单元

output.md的第一部分（output.md）列出分析器从模块顶层切出的条目，Count: 6。切分与属性渲染逻辑在 tests.rs：g.init(&module, ...)返回item_ids与items，框架对每个条目打印源码（```js 代码块）以及Hoisted、Side effects、Declares:（声明的变量）、Reads:（读取的变量）、Write:（写入的变量）等属性；Reads (eventual)/Write (eventual)（异步/事件性读写）若存在也会打印，本用例没有出现。

逐条解读（与 output.md 原文一一对应）：

Item 1: Stmt 0,ImportOfModule—— 整条import声明的“模块求值”层面：

import { IPC } from "./index";

• Hoisted（被提升处理）
• Side effects（导入./index本身有副作用，必须执行）

Item 2: Stmt 0,ImportBinding(0)—— 同一个import声明的“绑定”层面，即导入的命名绑定IPC：

import { IPC } from "./index";

• Hoisted
• Declares:IPC

一条import语句被拆成“模块副作用”和“具名绑定”两个条目，这是 Turbopack 树摇的基础操作：即使IPC最终没被用到，只要./index有副作用，ImportOfModule仍会保留。

Item 3: Stmt 1,VarDeclarator(0)——const ipc = IPC;：

const ipc = IPC;

• Declares:ipc；Reads:IPC；Write:ipc

这是典型的“导入后别名”模式：ipc声明自绑定IPC的读取。

Item 4: Stmt 2,VarDeclarator(0)——const queue = [];：

const queue = [];

• Declares:queue；Write:queue

Item 5: Stmt 3,VarDeclarator(0)——export const run = async (moduleFactory)=>{ ... };，其完整函数体就是上文第二节给出的 input.js 第 4–94 行的run函数（output.md 中 Item 5 的代码块与之一字不差）。分析器标注的属性：

• Side effects
• Declares:run
• Reads:ipc,queue
• Write:ipc,queue,run

注意Write: ipc, queue, run中列出了对ipc、queue的“写”：从源码结构看，这对应函数体内部const run = async ()=>{...}（内层run遮蔽外层导出名run，构成一次同名写入）以及对闭包环境变量的访问判定；Reads: ipc, queue则是函数体对两个顶层常量的捕获。

Item 6（Count: 6中的最后一个）不是源码语句，而是导出分组节点。Phase 图里它显示为Item6["export run"]，对应 tests.rs 中ItemId::Group(ItemIdGroupKind::Export(_, name))渲染为export {name}的逻辑。ModuleEvaluation分组节点同样存在，作为所有语句必须依赖的“模块求值”根。

四、Phase 1–4 与 Final：依赖图的演化过程

output.md的中段用五个 mermaid 图记录了流水线每一阶段结束时的依赖图（节点为 Item，边为“执行顺序”依赖；实线-->是强依赖，点线-.-是弱依赖，见 render_graph）。每个阶段对应 tests.rs 中分析器的一个调用：

Phase 1（output.md L148-L158）确认了无边的初始状态：

Phase 2（L159-L174）在evaluate_immediate后一次性画出全部 5 条边，Phase 3、Phase 4 保持不变：

这 5 条边可以逐条映射回源码语义：

• Item3 --> Item2：const ipc = IPC读取导入绑定，必须晚于ImportBinding(IPC)；
• Item5 --> Item3/Item5 --> Item4：run函数体捕获顶层ipc与queue，函数声明必须先于这两个变量的求值依赖就绪；
• Item5 --> Item1：run内部会触发对./index模块的求值依赖（经由ipc间接持有模块引用）；
• Item6 --> Item5：导出run的分组节点依赖于run声明本身。

最终Final图（L207-L215）把 6 个节点压缩为 3 个“条目组”（finalize把依赖相同的条目内联合并）：

可以看到三个执行组：N0（./index的模块求值）、N1（导入绑定IPC，须先于模块求值完成绑定）、N2（ipc、queue、run三个声明连同导出分组归为一组，整体依赖 N0）。这正是一条合法的拓扑执行顺序：先加载./index并建立IPC绑定，再初始化ipc/queue/run。

五、# Entrypoints：碎片化入口表

图之后是入口表（output.md L216-L226），由 tests.rs 中g.split_module(&[], analyzer.items)的返回值entrypoints排序后打印：

{ ModuleEvaluation: 2, Export( "run", ): 2, Exports: 3, }

它声明了“哪个逻辑入口落在哪个 Part 上”：模块求值（ModuleEvaluation）与具名导出run都指向 Part 2，而Exports（导出声明的再导出壳）指向 Part 3。这张表是运行时加载器的调度依据——按入口键取 Part 索引，即可知道执行哪些碎片。

六、Modules (dev)/Modules (prod)：切分产物的真实形态

output.md随后分别输出开发模式（Mode::Development）与生产模式（Mode::Production）下g.handle_weak(mode)+split_module的结果（tests.rs）。本用例中两种模式的 Part 内容逐字相同，共 4 个 Part + 1 个合并视图。

Part 0—— 纯副作用导入碎片：

import "./index";

Part 1—— 依赖 Part 0 的空壳（承接导入声明的绑定处理）：

import "__TURBOPACK_PART__" assert { __turbopack_part__: 0 };

Part 2—— 主体碎片，包含全部变量声明、run函数与导出（L242-L356）：

import "__TURBOPACK_PART__" assert { __turbopack_part__: 0 }; import { IPC } from "./index"; import "__TURBOPACK_PART__" assert { __turbopack_part__: 0 }; const ipc = IPC; const queue = []; const run = async (moduleFactory)=>{ let nextId = 1; const requests = new Map(); const internalIpc = { sendInfo: (message)=>ipc.send({ type: "info", data: message }), sendRequest: (message)=>{ const id = nextId++; let resolve, reject; const promise = new Promise((res, rej)=>{ resolve = res; reject = rej; }); requests.set(id, { resolve, reject }); return ipc.send({ type: "request", id, data: message }).then(()=>promise); }, sendError: (error)=>{ return ipc.sendError(error); } }; let getValue; try { const module = await moduleFactory(); if (typeof module.init === "function") { await module.init(); } getValue = module.default; await ipc.sendReady(); } catch (err) { await ipc.sendReady(); await ipc.sendError(err); } let isRunning = false; const run = async ()=>{ while(queue.length > 0){ const args = queue.shift(); try { const value = await getValue(internalIpc, ...args); await ipc.send({ type: "end", data: value === undefined ? undefined : JSON.stringify(value, null, 2), duration: 0 }); } catch (e) { await ipc.sendError(e); } } isRunning = false; }; while(true){ const msg = await ipc.recv(); switch(msg.type){ case "evaluate": { queue.push(msg.args); if (!isRunning) { isRunning = true; run(); } break; } case "result": { const request = requests.get(msg.id); if (request) { requests.delete(msg.id); if (msg.error) { request.reject(new Error(msg.error)); } else { request.resolve(msg.data); } } break; } default: { console.error("unexpected message type", msg.type); process.exit(1); } } } }; export { run }; export { ipc as a } from "__TURBOPACK_VAR__" assert { __turbopack_var__: true }; export { queue as b } from "__TURBOPACK_VAR__" assert { __turbopack_var__: true }; export { run as c } from "__TURBOPACK_VAR__" assert { __turbopack_var__: true }; export { };

Part 3—— 导出再导出壳（L357-L363）：

export { run } from "__TURBOPACK_PART__" assert { __turbopack_part__: "export run" };

从输出结构看，这里出现了三个 Turbopack 内部协议标识符：

1. import "__TURBOPACK_PART__" assert { __turbopack_part__: N }：声明“本碎片在执行前必须先执行碎片 N”。Part 2 头部两次引用 Part 0，保证副作用与绑定先就绪。Part 3 则用字符串标签"export run"引用导出分组所在的源碎片，与 Phase 图中Item6["export run"]的标签一一对应。
2. export { x as a } from "__TURBOPACK_VAR__" assert { __turbopack_var__: true }：把模块级变量ipc、queue、run以单字母名重新导出为“变量导出”。从源码结构看，这是碎片化后跨 Part 引用顶层变量的通道——其他碎片（或运行时的入口调度）通过a/b/c这些稳定别名取回模块作用域变量，即使源变量是const也不影响绑定语义。
3. export { };空导出占位，保证该 Part 在 ESM 层面始终是一个合法模块。

Merged (module eval)（L364-L475）则是模拟运行时视角：测试用 SingleModuleLoader 按 Entrypoints 表把ModuleEvaluation入口对应的 Part 取出，再用Merger（tests.rs 的merger.merge_recursively(entry)）递归合并碎片间的__TURBOPACK_PART__导入。合并结果 = Part 0 的import "./index";置于开头 + Part 2 的完整主体，__TURBOPACK_PART__导入被消除，export { run };与三条__TURBOPACK_VAR__导出保留——这正是入口模块“模块求值”入口实际拿到的代码。Modules (prod)一节（L489-L735）重复输出同一份 Part 0/1/2/3 与 Merged 内容，表明本模块在 dev/prod 弱依赖处理上没有差异。

七、如何在仓库中复现与扩展该测试

• 查看：直接阅读 output.md 与 input.js；流水线实现见 src/module_fragments/tests.rs。
• 运行：在仓库根目录执行cargo test -p turbopack-ecmascript，fixture 会自动匹配tests/tree-shaker/analyzer/**/input.js并逐一比对快照。
• 更新快照：确认分析器改动符合预期后，执行UPDATE=1 cargo test -p turbopack-ecmascript重写快照（readme.md）。
• 新增用例：在tests/tree-shaker/analyzer/下新建目录放入input.js（需要限定导出集合时再加config.json），首次运行时以UPDATE=1生成对应的output.md即可纳入回归。
• 相关设施：同 crate 还有另一套 fixturetests/analyzer/graph/**/input.js（见 src/analyzer/mod.rs），以及 benches/analyzer.rs 中对create_graph/link的 criterion 基准测试——快照测试保证结果正确性，基准测试保证分析吞吐，二者共同看护这条树摇管线。

八、小结

ipc-evaluate/output.md以一份可读的文本快照，完整固化了 Turbopack 模块切分树摇的五个观察面：条目切分（Items）→ 四阶段依赖图（Phase 1-4）→ 压缩分组（Final）→ 入口表（Entrypoints）→ 碎片化产物与合并（Modules dev/prod + Merged）。它不仅是回归测试的“期望值”，更是一份天然的实现文档：读它就能理解__TURBOPACK_PART__执行序依赖、__TURBOPACK_VAR__变量别名导出、dev/prod 弱依赖处理等 Turbopack 打包机制是如何在真实业务代码（IPC 求值循环）上落地的。

【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js