企业官网建设流程全解析

• CLI
• 开发工具
• 语言运行时

tsx（TypeScript Execute）以 esbuild 作为通用转换后端，在逐文件转译 TypeScript 时默认开启keepNames，以确保函数与类的可观察name属性在转换后保持一致。本文以仓库研究笔记 function-identity.md 为核心骨架，结合 tsx 的转换配置、缓存设计与测试用例，剖析 esbuild 名称恢复调用的注入时机、最终符号名的确定过程，以及序列化（toString()/eval()）场景下的已知边界，帮助读者理解“函数身份”在转译管线中的完整生命周期。

一、为什么 tsx 默认开启keepNames：可观察的函数身份

在 JavaScript 中，函数与类的name属性是运行时可观察的行为：调试堆栈、日志、断言、Object.keys枚举都依赖它。转译器若在降级语法或重命名符号时破坏name，就会引入隐性的行为差异。

tsx 的共享转换配置在 get-esbuild-options.ts 中显式启用了keepNames：

export const cacheConfig = { ...baseConfig, sourcemap: true, /** * 仅在启用 V8 coverage 或 Node.js 调试器时生成 sourcesContent */ sourcesContent: Boolean(process.env.NODE_V8_COVERAGE) || isNodeDebuggerEnabled, /** * 更小的缓存输出与边际性能提升 * * minifyIdentifiers 被禁用：调试器不使用 source map 的 `names` 属性 * minifySyntax 被禁用：它可能做 tree-shaking（例如未使用的 try-catch 错误变量） */ minifyWhitespace: true, /** * esbuild 即使不开启压缩也会重命名变量 */ keepNames: true, };

这里有两个值得注意的细节：

1. 只开minifyWhitespace，不开标识符压缩与语法压缩：minifyIdentifiers与minifySyntax保持 esbuild 默认关闭，前者是为了让调试器能通过 source map 的names属性还原原始标识符，后者是为了避免 tree-shaking 带来的语义副作用。
2. keepNames之所以必要，正是因为“即使不压缩，esbuild 也会重命名变量”：配置注释与 function-identity.md 的研究结论相互印证——重命名是 esbuild 管线中的独立环节，与是否开启压缩无关。

tsx 对名称保持的重视在测试中可见一斑。烟雾测试固定量 fixtures.ts 专门断言函数名不被破坏：

const preserveName = ` assert( (function functionName() {}).name === 'functionName', 'Name should be preserved' ); `;

转换测试 transform.ts 的 fixture 也直接读取具名函数表达式的name，并断言转换后仍为原始名称：

export const functionName: string = (function named() {}).name; // 断言：functionName === 'named'（transform.ts#L62、L246）

此外，该测试还验证了 source map 的names字段包含原始名称'named'（transform.ts），说明名称信息不仅存在于运行时，也被完整保留在调试元数据中。

二、esbuild 如何恢复函数名：__name运行时辅助函数

根据 function-identity.md 的研究，开启keepNames后，esbuild 会在降级函数声明与降级箭头函数/函数表达式时插入名称恢复调用，这些调用指向一个生成的__name运行时辅助函数。

其机制可概括为：

• 函数声明（如function sum() {}）：降级后在声明末尾追加__name(sum, "sum")形式的恢复调用；
• 箭头函数/函数表达式（如const sum = () => {}）：降级时用恢复调用包裹，形如const sum = __name(() => {}, "sum")。

__name辅助函数的功能是在目标函数对象上写回原始name属性并返回该函数。示意如下（非 esbuild 逐字源码，仅说明行为）：

// 示意：esbuild 随模块输出注入的 __name 辅助函数（模块作用域） var __name = (fn, name) => { Object.defineProperty(fn, 'name', { value: name, configurable: true }); return fn; };

关键点在于：该辅助函数是模块作用域内的生成代码，即它随被转换文件一起输出，位于该文件的模块顶层，而非嵌入到每个函数体内。tsx 的转换契约 transform-backend.md 对此有明确记录：

tsx enables esbuild'skeepNames, whose restoration calls depend on a module-scoped helper; a transformed function containing nested restoration calls is not self-contained when serialized without its enclosing module.

在 tsx 中，keepNames的实际生效路径依赖 index.ts（CJS 路径）与 index.ts（ESM 路径）将cacheConfig合并进每次 esbuild 调用。同时，由于 baseConfig 将target固定为当前运行中的 Node 版本（target: node${process.versions.node}），绝大多数现代语法无需降级，因此名称恢复调用主要集中在确实需要语法降级或发生符号重命名的场景——这一点也从侧面解释了为什么 tsx 选择“以当前 Node 为 target”，从而尽量减少不必要的降级与辅助函数注入。

三、最终符号名：renamer 与 linker 的碰撞处理

名称恢复调用注入之后，最终符号名并不是立即确定的。根据 function-identity.md，最终符号名由后续两个阶段决定：

1. linker 的碰撞处理：当用户代码符号与生成的运行时辅助符号（如__name）或合并后的其他符号发生冲突时，linker 会挑选不冲突的最终名；
2. renamer 的重命名：即使没有开启压缩，renamer 仍可能对符号进行重命名，并在碰撞时追加后缀。

研究笔记特别强调了一个反直觉的结论：

禁用标识符压缩并不能阻止碰撞后缀的产生。

这与 tsx 的配置选择高度相关：tsx 关闭了minifyIdentifiers，但这只意味着“不会为了体积而主动缩短标识符”，并不代表符号永远不会被重命名——当发生碰撞时，esbuild 依然会为符号追加后缀以保证正确性。因此keepNames承担的角色是：无论最终符号名是什么，都通过__name调用把可观察的name属性恢复到原始值。名称保持与符号重命名是两条并行、互补的机制。

四、序列化边界：toString()/eval()与游离的__name引用

function-identity.md 的最后一段给出了一条基于上述机制的重要推断（Inference）：

序列化一个体内包含嵌套名称恢复调用的转换后函数，可能会留下一个游离的__name引用——因为该辅助函数仍保留在它的外层模块中；esbuild 官方文档明确将转换后函数的toString()/eval()重定位视为不支持的操作。

具体而言，考虑以下场景：

// 转换后的函数（示意） const handler = __name(async (x) => x + 1, "handler"); // 用户把 handler 序列化后重放 const serialized = handler.toString(); // -> "__name(async (x) => x + 1, \"handler\")" // 在新作用域中 eval eval(serialized); // ReferenceError: __name is not defined

当函数体（或包裹它的表达式）中存在__name调用，而序列化时并未携带所在模块顶层的辅助函数定义时，重放必然失败。这正是“模块作用域辅助函数”与“函数自包含性”之间的天然张力。

tsx 对该边界的态度是明确的——它不承诺Function.prototype.toString()的可移植性。转换契约 transform-backend.md 的非目标（Non-goals）章节写道：

Guarantee arbitraryFunction.prototype.toString()portability after required syntax lowering introduces external helpers.

同时，其不变量（Invariants）章节要求 transform-backend.md：

Preserve observable function and class names; disabling name preservation is not a default fix.

这两条共同构成了 tsx 的处理原则：名称保持是默认承诺，必须尽力保证；而序列化重定位是明示的非目标，不因后端选择而改变。在重新验证矩阵（Re-verification matrix）中，“Fresh-realm execution”（将嵌套的箭头函数、函数与类序列化进node:vm新领域执行）被列为名称保持契约变更时必须回归覆盖的测试项（transform-backend.md），足见该边界始终在契约守卫之内。

五、与 Oxc 候选后端的对比：两条不同的实现路线

同样的“函数身份”目标，不同后端选择了截然不同的实现路线。tsx 的后端能力矩阵 transform-backend.md 与 oxc-transform/function-identity.md 记录了这一点：

Oxc 的路线本质上回避了“游离__name引用”问题——它选择“不重命名就不需要恢复”，而不是“重命名后再恢复”。但其降级路径同样可能引入根作用域依赖（见 generated-helpers.md），因此“序列化仅函数本身无法保留原程序作用域中的绑定”这一推断依然成立（oxc-transform/function-identity.md）。这也是后端替换评估中“当前 target 的转换不得给原本自包含的函数添加游离辅助函数依赖”这一不变量（transform-backend.md）的来源。

六、实践要点小结

1. keepNames是 tsx 的默认契约而非可选优化：它保证函数/类在转译后的可观察name属性与调试元数据（source mapnames字段）双双完整（get-esbuild-options.ts、transform.ts）。
2. 重命名与压缩无关：即使关闭minifyIdentifiers，renamer 的碰撞后缀仍会出现；keepNames的价值正是在符号名变化时兜底恢复可观察名称。
3. 警惕序列化陷阱：不要对 tsx 转译后的函数体做toString()后跨模块重放（eval/new Function），因为__name等辅助函数留在原模块作用域，序列化内容不自包含；这是 esbuild 明示不支持的操作，也是 tsx 声明的非目标。
4. 缓存稳定性的隐性保障：tsx 的转换缓存键包含完整 esbuild 选项、esbuild 版本与动态导入转换器版本（index.ts、index.ts），这意味着__name辅助函数的形态随 esbuild 升级而改变时会自动使缓存失效，避免新旧辅助函数混用。
5. 后端对比时关注“辅助函数注入策略”：esbuild 的“重命名 + 恢复调用”与 Oxc 的“排除重命名”是两种不同的函数身份保持哲学，评估替代后端时应以“是否引入游离辅助函数依赖”为关键判据（transform-backend.md）。

延伸阅读：esbuild 研究系列的 README 汇总了模块解析、CJS/ESM 互操作、导入省略等相邻主题；tsx 侧的整体转换契约见 transform-backend.md，其中包含完整的后端能力矩阵与重新验证矩阵，可作为继续深入该主题的入口。

• CLI
• 开发工具
• 语言运行时