ESBuild 中 TypeScript 装饰器兼容性问题解析

问题背景

在使用 ESBuild 构建工具处理包含 TypeScript 装饰器的代码时，开发者可能会遇到一个常见问题：在 ESBuild 0.17.19 版本中能够正常工作的装饰器代码，在升级到 0.18.0 及更高版本后会出现"Unsupported decorator location: field"的错误提示。

根本原因

这个问题的根源在于 ESBuild 0.18.0 版本引入了一个重要变更：开始支持原生 JavaScript 装饰器方案，同时改变了原有对 TypeScript 实验性装饰器的处理方式。在 0.17.19 及之前版本中，ESBuild 默认支持 TypeScript 风格的装饰器语法，而从 0.18.0 开始，开发者需要显式配置才能继续使用这种语法。

解决方案

要解决这个问题，开发者有以下两种选择：

1. 启用 TypeScript 实验性装饰器： 在项目的 tsconfig.json 文件中添加 "experimentalDecorators": true 配置项。这会告诉 ESBuild 继续使用 TypeScript 风格的装饰器实现。

2. 迁移到新版装饰器语法： 对于使用 Lit 等现代框架的开发者，可以考虑使用新的装饰器语法。例如，在属性装饰器前添加 accessor 修饰符：

   @property({type: String})
   accessor name = "";
   

技术细节

TypeScript 装饰器和 JavaScript 原生装饰器方案有几个关键区别：

1. 语法位置：TypeScript 装饰器可以应用于类字段，而原生方案对装饰器的应用位置有更严格的限制。

2. 运行时行为：两种装饰器的实现机制和转换后的代码结构有所不同。

3. 元数据生成：TypeScript 装饰器通常会生成额外的类型元数据，而原生方案不依赖这种机制。

最佳实践

对于现有项目：

• 如果项目已经大量使用 TypeScript 装饰器，建议保持 "experimentalDecorators": true 配置
• 考虑逐步迁移到新版装饰器语法，特别是新开发的功能

对于新项目：

• 评估是否真的需要使用装饰器，有时简单的函数调用可能更清晰
• 如果使用装饰器，建议直接采用新版语法，以获得更好的未来兼容性

总结

ESBuild 对装饰器支持的变更反映了 JavaScript 语言标准的演进过程。理解这种变化背后的原因，掌握相应的配置方法，能够帮助开发者更好地使用构建工具，同时为未来的技术升级做好准备。在实际开发中，建议团队根据项目具体情况选择合适的装饰器方案，并在项目文档中明确记录相关配置。