Rolldown 输出配置解析topLevelVar 与顶层声明重写原理【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldown导读topLevelVar是 Rolldown 提供的一项输出级output.*优化开关开启后产物中模块顶层作用域的let、const声明会被重写为var声明从而避开 JavaScript 引擎在 Temporal dead zoneTDZ暂时性死区 检查上的运行时性能开销。本文围绕该选项的官方文档说明结合 Rolldown 源码与测试用例讲清它的触发条件、作用范围、边界行为与底层实现原理帮助你判断何时启用、何时应保持默认关闭。一、背景TDZ 检查为什么会影响运行时性能原文档 output-top-level-var.md 明确指出启用该选项的动机在于多个 JavaScript 引擎在 TDZ 检查上存在持续的性能问题。TDZ 是let、const、class声明的语义约束——这些符号在真正初始化之前被读取会抛出ReferenceError。引擎为保障这一语义需要在每次访问这类绑定前插入检查逻辑验证该符号是否已初始化。这类检查的代价在热路径hot path上会被显著放大V8Chrome / Node.js / Denohttps://issues.chromium.org/issues/42203665JavaScriptCoreSafarihttps://bugs.webkit.org/show_bug.cgi?id199866已修复因此当产物运行环境以 V8 为主时把顶层let/const统一改写为varvar不存在 TDZ 语义可以让引擎省略掉这部分检查换取可感知的运行性能提升。二、选项定义与基本用法topLevelVar是 OutputOptions 中的一个布尔选项默认值为false。官方 JSDoc 的语义描述为Whether to convert top-levelletandconstdeclarations intovardeclarations.即是否将顶层的let和const声明转换为var声明。其作用有两个硬性边界只作用于模块顶层作用域函数、块级作用域if、for等内部的声明一律保持不变function声明永远不会被重写。在 TypeScript 侧该选项通过include机制直接内联了 output-top-level-var.md 作为深入阅读In-depth章节因此该文档本质上是此选项的官方技术说明。在 JS/TS API 中启用方式如下import { rolldown } from rolldown; const bundle await rolldown({ input: ./src/main.js, output: { topLevelVar: true, // 默认 false }, }); await bundle.write({ dir: dist });对应的类型声明在 binding.d.cts 中同样以topLevelVar?: boolean呈现构建时通过 bindingify-output-options.ts 透传到 Rust 侧。三、源码实现重写发生在哪个阶段从源码结构看该选项的生效位置在模块收尾器module finalizer阶段也就是产物代码生成前的最后一道 AST 改写环节。核心逻辑位于 crates/rolldown/src/module_finalizers/mod.rsif self.ctx.options.top_level_var { if let Statement::VariableDeclaration(var_decl) mut top_stmt { var_decl.kind ast::VariableDeclarationKind::Var; } if let Statement::ClassDeclaration(class_decl) top_stmt { top_stmt match self.get_transformed_class_decl(class_decl) { Ok(decl) Statement::from(decl), Err(class_decl) Statement::ClassDeclaration(class_decl), }; } }这段代码揭示了三条关键实现事实变量声明直接把VariableDeclaration的kind从Let/Const改写为Var即let x→var x、const x→var x类声明class X {}会被尝试改写为var X class {}的表达式形式get_transformed_class_decl以便与顶层其他绑定一起提升执行时机该改写发生在遍历顶层语句top_stmt的过程中只针对模块顶层天然不会触达嵌套作用域。此外模块收尾器还维护了一个top_level_var_bindings集合见 finalizer_context.rs 与 mod.rs用于在改写后统一处理需要追加的声明装饰decorations见 impl_visit_mut.rs。也就是说topLevelVar并不是一次简单的字符串替换而是与 Rolldown 的符号分析、声明收集机制深度耦合的 AST 变换。一个重要的既有行为class 改写与 topLevelVar 无关官方文档特别强调顶层class X {}声明总是会被输出为var X class {}这一行为与topLevelVar是否开启无关。原因是 Rolldown 需要将顶层类与其他顶层绑定统一提升hoist以维持正确的初始化顺序。在topLevelVar: false的产物中你依然能看到var FirstLevelClass class {};正是这个固定行为详见下文测试快照对比。四、测试用例逐行验证作用边界仓库为topLevelVar提供了两组测试可以直接当作行为规格来阅读。4.1 function/top_level_var主行为测试入口文件 main.js 故意混合了顶层与嵌套作用域的各种声明测试配置 _config.json 先以false跑一遍基线再通过configVariants以true跑一遍对比。两轮输出的快照都记录在 artifacts.snap 中。先看topLevelVar: false的基线产物节选let firstLevelLet let; var firstLevelVar var; const firstLevelConst const; var FirstLevelClass class {}; // class 被改写与 topLevelVar 无关 console.log(firstLevelLet, firstLevelVar, firstLevelConst, new FirstLevelClass()); const exportedConst exported_const; let exportedLet exported_let; var ExportedClass class {}; function exportedFunction() {} function second_level() { let secondLevelLet let; var secondLevelVar var; const secondLevelConst const; class SecondLevelClass {} console.log(secondLevelLet, secondLevelVar, secondLevelConst, new SecondLevelClass()); } second_level();再对照topLevelVar: true的产物var firstLevelLet let; // let → var var firstLevelVar var; var firstLevelConst const; // const → var var FirstLevelClass class {}; console.log(firstLevelLet, firstLevelVar, firstLevelConst, new FirstLevelClass()); var exportedConst exported_const; // 导出的 const 也被改写 var exportedLet exported_let; // 导出的 let 也被改写 var ExportedClass class {}; function exportedFunction() {} // function 永远不被改写 console.log(let); function second_level() { let secondLevelLet let; // 函数作用域内的 let 保持不变 var secondLevelVar var; const secondLevelConst const; class SecondLevelClass {} // 嵌套 class 保持不变 console.log(secondLevelLet, secondLevelVar, secondLevelConst, new SecondLevelClass()); } second_level();这份对比可以总结出完整的行为矩阵声明类型顶层嵌套作用域函数/块let改写为var保持不变const改写为var保持不变class始终改写为var X class {}与选项无关保持不变function永不改写保持不变普通var保持var保持不变值得注意的是即使开启了topLevelVar被导出的let/const改写为var后导出的语义依然通过尾部的export { ... }语句完整保留快照末尾的export { ExportedClass, exportedConst, exportedFunction, exportedLet };说明该变换不会破坏 ESM 的导出契约。4.2 misc/top_level_var/issue_5884回归测试第二组测试对应一个真实 issue 的回归场景issue_5884入口 main.js其核心是包含static {}静态初始化块的类class Example { static { this.prop new Example(bar); assert.strictEqual(Example.prop.foo, bar); } constructor(foo) { this.foo foo; } }对比 artifacts.snap 中true与false两个变体的输出会发现两者完全一致(class Example { static { this.prop new Example(bar); assert.strictEqual(Example.prop.foo, bar); } constructor(foo) { this.foo foo; } });这说明当顶层类无法安全地改写为提升形式例如包含static {}等特殊语义时实现会选择保守地保留原始声明topLevelVar不会强行改写而破坏语义。这正是能改才改、语义优先的设计取舍。五、参数校验与生态衔接在 JS API 侧topLevelVar接受可选的布尔值。Rolldown 使用 Valibot schema 对输出选项做校验见 validator.tstopLevelVar: v.pipe( v.optional(v.boolean()), v.description(Rewrite top-level declarations to use var.), ),归一化后的选项保存在NormalizedOutputOptions中normalized-output-options.ts默认值为falseget topLevelVar(): boolean { return this.inner.topLevelVar ?? false; }Rust 侧对应的内部选项字段位于 crates/rolldown_common/src/inner_bundler_options/types/normalized_bundler_options.rs并通过 crates/rolldown_binding/src/utils/normalize_binding_options.rs 完成从 JS 绑定层到 Rust 内部选项的归一化最终在 finalizer 阶段被读取即上文第三部分展示的self.ctx.options.top_level_var。测试框架层面topLevelVar也被纳入配置变体configVariants机制见 config_variant.rs方便对同一份 fixture 做开关前后对比。六、使用建议与注意事项综合官方文档、源码与测试给出如下实操建议面向 V8 系运行时Chrome、Node.js、Deno且性能敏感的项目可以开启topLevelVar: true以消除产物热路径上的 TDZ 检查不要期望它改变嵌套作用域函数体、块级作用域内的let/const不受影响若这些才是瓶颈需要寻求其他手段例如后续的压缩/内联放心依赖语义安全topLevelVar只作用于模块顶层且导出语义通过尾部export {}完整保留遇到static {}类等无法安全改写的情形实现会自动保留原样见 issue_5884 测试function声明不受影响如果你期待函数声明也被改写该选项不提供此能力这是刻意的设计边界与class改写的区别即使topLevelVar: false顶层class也已经被 Rolldown 改写为var X class {}这属于既有的提升策略与本文选项无因果关系。总的来说topLevelVar是一个零成本开关、面向特定运行时优化的轻量级选项它用一次顶层 AST 改写换取 V8 等引擎在 TDZ 检查上的运行时收益同时通过严格的顶层作用域边界与保守的改写策略保证了输出语义的可预期性。需要深入了解细节时可直接阅读 output-top-level-var.md 的 In-depth 章节以及上述两组测试快照。【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Rolldown 输出配置解析：topLevelVar 与顶层声明重写原理
Rolldown 输出配置解析topLevelVar 与顶层声明重写原理【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldown导读topLevelVar是 Rolldown 提供的一项输出级output.*优化开关开启后产物中模块顶层作用域的let、const声明会被重写为var声明从而避开 JavaScript 引擎在 Temporal dead zoneTDZ暂时性死区 检查上的运行时性能开销。本文围绕该选项的官方文档说明结合 Rolldown 源码与测试用例讲清它的触发条件、作用范围、边界行为与底层实现原理帮助你判断何时启用、何时应保持默认关闭。一、背景TDZ 检查为什么会影响运行时性能原文档 output-top-level-var.md 明确指出启用该选项的动机在于多个 JavaScript 引擎在 TDZ 检查上存在持续的性能问题。TDZ 是let、const、class声明的语义约束——这些符号在真正初始化之前被读取会抛出ReferenceError。引擎为保障这一语义需要在每次访问这类绑定前插入检查逻辑验证该符号是否已初始化。这类检查的代价在热路径hot path上会被显著放大V8Chrome / Node.js / Denohttps://issues.chromium.org/issues/42203665JavaScriptCoreSafarihttps://bugs.webkit.org/show_bug.cgi?id199866已修复因此当产物运行环境以 V8 为主时把顶层let/const统一改写为varvar不存在 TDZ 语义可以让引擎省略掉这部分检查换取可感知的运行性能提升。二、选项定义与基本用法topLevelVar是 OutputOptions 中的一个布尔选项默认值为false。官方 JSDoc 的语义描述为Whether to convert top-levelletandconstdeclarations intovardeclarations.即是否将顶层的let和const声明转换为var声明。其作用有两个硬性边界只作用于模块顶层作用域函数、块级作用域if、for等内部的声明一律保持不变function声明永远不会被重写。在 TypeScript 侧该选项通过include机制直接内联了 output-top-level-var.md 作为深入阅读In-depth章节因此该文档本质上是此选项的官方技术说明。在 JS/TS API 中启用方式如下import { rolldown } from rolldown; const bundle await rolldown({ input: ./src/main.js, output: { topLevelVar: true, // 默认 false }, }); await bundle.write({ dir: dist });对应的类型声明在 binding.d.cts 中同样以topLevelVar?: boolean呈现构建时通过 bindingify-output-options.ts 透传到 Rust 侧。三、源码实现重写发生在哪个阶段从源码结构看该选项的生效位置在模块收尾器module finalizer阶段也就是产物代码生成前的最后一道 AST 改写环节。核心逻辑位于 crates/rolldown/src/module_finalizers/mod.rsif self.ctx.options.top_level_var { if let Statement::VariableDeclaration(var_decl) mut top_stmt { var_decl.kind ast::VariableDeclarationKind::Var; } if let Statement::ClassDeclaration(class_decl) top_stmt { top_stmt match self.get_transformed_class_decl(class_decl) { Ok(decl) Statement::from(decl), Err(class_decl) Statement::ClassDeclaration(class_decl), }; } }这段代码揭示了三条关键实现事实变量声明直接把VariableDeclaration的kind从Let/Const改写为Var即let x→var x、const x→var x类声明class X {}会被尝试改写为var X class {}的表达式形式get_transformed_class_decl以便与顶层其他绑定一起提升执行时机该改写发生在遍历顶层语句top_stmt的过程中只针对模块顶层天然不会触达嵌套作用域。此外模块收尾器还维护了一个top_level_var_bindings集合见 finalizer_context.rs 与 mod.rs用于在改写后统一处理需要追加的声明装饰decorations见 impl_visit_mut.rs。也就是说topLevelVar并不是一次简单的字符串替换而是与 Rolldown 的符号分析、声明收集机制深度耦合的 AST 变换。一个重要的既有行为class 改写与 topLevelVar 无关官方文档特别强调顶层class X {}声明总是会被输出为var X class {}这一行为与topLevelVar是否开启无关。原因是 Rolldown 需要将顶层类与其他顶层绑定统一提升hoist以维持正确的初始化顺序。在topLevelVar: false的产物中你依然能看到var FirstLevelClass class {};正是这个固定行为详见下文测试快照对比。四、测试用例逐行验证作用边界仓库为topLevelVar提供了两组测试可以直接当作行为规格来阅读。4.1 function/top_level_var主行为测试入口文件 main.js 故意混合了顶层与嵌套作用域的各种声明测试配置 _config.json 先以false跑一遍基线再通过configVariants以true跑一遍对比。两轮输出的快照都记录在 artifacts.snap 中。先看topLevelVar: false的基线产物节选let firstLevelLet let; var firstLevelVar var; const firstLevelConst const; var FirstLevelClass class {}; // class 被改写与 topLevelVar 无关 console.log(firstLevelLet, firstLevelVar, firstLevelConst, new FirstLevelClass()); const exportedConst exported_const; let exportedLet exported_let; var ExportedClass class {}; function exportedFunction() {} function second_level() { let secondLevelLet let; var secondLevelVar var; const secondLevelConst const; class SecondLevelClass {} console.log(secondLevelLet, secondLevelVar, secondLevelConst, new SecondLevelClass()); } second_level();再对照topLevelVar: true的产物var firstLevelLet let; // let → var var firstLevelVar var; var firstLevelConst const; // const → var var FirstLevelClass class {}; console.log(firstLevelLet, firstLevelVar, firstLevelConst, new FirstLevelClass()); var exportedConst exported_const; // 导出的 const 也被改写 var exportedLet exported_let; // 导出的 let 也被改写 var ExportedClass class {}; function exportedFunction() {} // function 永远不被改写 console.log(let); function second_level() { let secondLevelLet let; // 函数作用域内的 let 保持不变 var secondLevelVar var; const secondLevelConst const; class SecondLevelClass {} // 嵌套 class 保持不变 console.log(secondLevelLet, secondLevelVar, secondLevelConst, new SecondLevelClass()); } second_level();这份对比可以总结出完整的行为矩阵声明类型顶层嵌套作用域函数/块let改写为var保持不变const改写为var保持不变class始终改写为var X class {}与选项无关保持不变function永不改写保持不变普通var保持var保持不变值得注意的是即使开启了topLevelVar被导出的let/const改写为var后导出的语义依然通过尾部的export { ... }语句完整保留快照末尾的export { ExportedClass, exportedConst, exportedFunction, exportedLet };说明该变换不会破坏 ESM 的导出契约。4.2 misc/top_level_var/issue_5884回归测试第二组测试对应一个真实 issue 的回归场景issue_5884入口 main.js其核心是包含static {}静态初始化块的类class Example { static { this.prop new Example(bar); assert.strictEqual(Example.prop.foo, bar); } constructor(foo) { this.foo foo; } }对比 artifacts.snap 中true与false两个变体的输出会发现两者完全一致(class Example { static { this.prop new Example(bar); assert.strictEqual(Example.prop.foo, bar); } constructor(foo) { this.foo foo; } });这说明当顶层类无法安全地改写为提升形式例如包含static {}等特殊语义时实现会选择保守地保留原始声明topLevelVar不会强行改写而破坏语义。这正是能改才改、语义优先的设计取舍。五、参数校验与生态衔接在 JS API 侧topLevelVar接受可选的布尔值。Rolldown 使用 Valibot schema 对输出选项做校验见 validator.tstopLevelVar: v.pipe( v.optional(v.boolean()), v.description(Rewrite top-level declarations to use var.), ),归一化后的选项保存在NormalizedOutputOptions中normalized-output-options.ts默认值为falseget topLevelVar(): boolean { return this.inner.topLevelVar ?? false; }Rust 侧对应的内部选项字段位于 crates/rolldown_common/src/inner_bundler_options/types/normalized_bundler_options.rs并通过 crates/rolldown_binding/src/utils/normalize_binding_options.rs 完成从 JS 绑定层到 Rust 内部选项的归一化最终在 finalizer 阶段被读取即上文第三部分展示的self.ctx.options.top_level_var。测试框架层面topLevelVar也被纳入配置变体configVariants机制见 config_variant.rs方便对同一份 fixture 做开关前后对比。六、使用建议与注意事项综合官方文档、源码与测试给出如下实操建议面向 V8 系运行时Chrome、Node.js、Deno且性能敏感的项目可以开启topLevelVar: true以消除产物热路径上的 TDZ 检查不要期望它改变嵌套作用域函数体、块级作用域内的let/const不受影响若这些才是瓶颈需要寻求其他手段例如后续的压缩/内联放心依赖语义安全topLevelVar只作用于模块顶层且导出语义通过尾部export {}完整保留遇到static {}类等无法安全改写的情形实现会自动保留原样见 issue_5884 测试function声明不受影响如果你期待函数声明也被改写该选项不提供此能力这是刻意的设计边界与class改写的区别即使topLevelVar: false顶层class也已经被 Rolldown 改写为var X class {}这属于既有的提升策略与本文选项无因果关系。总的来说topLevelVar是一个零成本开关、面向特定运行时优化的轻量级选项它用一次顶层 AST 改写换取 V8 等引擎在 TDZ 检查上的运行时收益同时通过严格的顶层作用域边界与保守的改写策略保证了输出语义的可预期性。需要深入了解细节时可直接阅读 output-top-level-var.md 的 In-depth 章节以及上述两组测试快照。【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
