@kaokei/di

Appearance

useDefineForClassFields 详解 ​

什么是 useDefineForClassFields ​

useDefineForClassFields 是 TypeScript 编译器选项之一，控制类字段（class fields）的编译输出方式。它决定了 TypeScript 是使用 Object.defineProperty 还是简单赋值来初始化类的实例属性。

这个选项的出现源于 TC39 对类字段语义的标准化。在 TC39 规范最终确定之前，TypeScript 采用了自己的类字段初始化方式（简单赋值）。当 TC39 规范确定使用 [[Define]] 语义后，TypeScript 引入了这个选项来对齐标准行为。

useDefineForClassFields 的默认值 ​

useDefineForClassFields 的默认值取决于 target 配置：

target 值useDefineForClassFields 默认值
ES2022 及以上true
ESNexttrue
ES2021 及以下false

这是因为 [[Define]] 语义是在 ES2022 中正式纳入规范的。当 target 为 ES2022+ 时，TypeScript 默认对齐标准行为。

true 和 false 的不同表现 ​

示例代码 ​

typescript
class Animal {
  name = 'animal';
}

class Dog extends Animal {
  name = 'dog';
}

useDefineForClassFields: false（赋值语义） ​

编译输出等价于：

javascript
class Animal {
  constructor() {
    // 简单赋值，走原型链的 setter
    this.name = 'animal';
  }
}

class Dog extends Animal {
  constructor() {
    super();
    // 简单赋值，走原型链的 setter
    this.name = 'dog';
  }
}

关键特征：

  • 类字段通过 this.xxx = value 赋值
  • 会触发原型链上的 setter
  • 子类字段赋值发生在 super() 之后
  • 未赋初始值的字段（如 name!: string）不会生成任何赋值代码

useDefineForClassFields: true（Define 语义） ​

编译输出等价于：

javascript
class Animal {
  constructor() {
    // 使用 Object.defineProperty，不走原型链的 setter
    Object.defineProperty(this, 'name', {
      configurable: true,
      enumerable: true,
      writable: true,
      value: 'animal'
    });
  }
}

class Dog extends Animal {
  constructor() {
    super();
    // 使用 Object.defineProperty
    Object.defineProperty(this, 'name', {
      configurable: true,
      enumerable: true,
      writable: true,
      value: 'dog'
    });
  }
}

关键特征：

  • 类字段通过 Object.defineProperty 定义
  • 不会触发原型链上的 setter
  • 未赋初始值的字段（如 name!: string）会被定义为 undefined

核心差异对比 ​

特性false（赋值语义）true（Define 语义）
初始化方式this.x = valueObject.defineProperty(this, 'x', ...)
是否触发 setter是否
未初始化的声明字段不生成代码定义为 undefined
declare 字段不生成代码不生成代码
与 TC39 标准一致否是

注意：declare 关键字在两种模式下都不会生成运行时代码，它仅用于类型声明。这是 TypeScript 提供的一种"逃生舱"，让开发者在 useDefineForClassFields: true 时仍能声明不需要运行时初始化的字段。

对装饰器功能的影响 ​

Stage 1 装饰器（experimentalDecorators: true） ​

Stage 1 装饰器（也称为 TypeScript 实验性装饰器）支持以下装饰器类型：

  • 类装饰器
  • 方法装饰器
  • 访问器装饰器
  • 属性装饰器
  • 参数装饰器（Stage 3 不支持）

useDefineForClassFields: false 时 ​

这是 Stage 1 装饰器的推荐配置。属性装饰器通过 Object.defineProperty 在原型上定义拦截器，而 false 模式下类字段通过 this.x = value 赋值，会触发原型上的 setter，装饰器可以正常拦截属性的读写操作。

typescript
// Stage 1 属性装饰器示例
function Log(target: any, propertyKey: string) {
  let value: any;
  Object.defineProperty(target, propertyKey, {
    get() { return value; },
    set(newVal) {
      console.log(`${propertyKey} changed to ${newVal}`);
      value = newVal;
    }
  });
}

class MyClass {
  @Log
  name = 'hello'; // false 模式：this.name = 'hello' → 触发 setter → 正常工作
}

useDefineForClassFields: true 时 ​

属性装饰器可能失效。因为 true 模式下类字段通过 Object.defineProperty 直接在实例上定义属性，这会覆盖原型上装饰器定义的 getter/setter，导致装饰器的拦截逻辑被绕过。

typescript
class MyClass {
  @Log
  name = 'hello';
  // true 模式：Object.defineProperty(this, 'name', { value: 'hello', ... })
  // 直接在实例上定义了 name 属性，覆盖了原型上 @Log 定义的 getter/setter
  // 装饰器失效！
}

这就是为什么使用 Stage 1 装饰器时，TypeScript 官方建议将 useDefineForClassFields 设置为 false。

Stage 3 装饰器（TC39 标准装饰器） ​

Stage 3 装饰器是 TC39 标准化的装饰器提案，TypeScript 5.0+ 原生支持（不需要 experimentalDecorators 选项）。

Stage 3 装饰器支持的类型：

  • 类装饰器
  • 方法装饰器
  • 访问器装饰器（accessor 关键字）
  • 字段装饰器（Field Decorator）
  • 不支持参数装饰器

Stage 3 字段装饰器的工作机制 ​

Stage 3 字段装饰器的签名为：

typescript
type ClassFieldDecorator = (
  value: undefined,
  context: ClassFieldDecoratorContext
) => ((initialValue: unknown) => unknown) | void;

关键 API：

  • context.metadata：装饰器元数据对象，可在装饰器执行阶段直接写入数据
  • context.addInitializer(fn)：注册一个回调函数，在类实例化时执行
  • 装饰器可以返回一个函数，用于转换字段的初始值

对本项目（@kaokei/di）的影响分析 ​

版本演进 ​

本项目经历了两个大版本的装饰器实现方案：

版本元数据注册方案对 useDefineForClassFields 的依赖
v4context.addInitializer不依赖，但 useDefineForClassFields: false 时要求esbuild>=0.24.0 vite>=6.0.0
v5（当前）context.metadata不依赖，但是要求typescript>=5.2.2，vite>=5.3.0（esbuild>=0.21.0）

两个版本都不依赖 useDefineForClassFields 配置项，无论设置为 true 还是 false，在符合版本要求的编译器下都能正常工作。区别仅在于 v4 版本在 useDefineForClassFields: false 时，对 esbuild/vite 的最低版本有额外要求。

装饰器建立关联关系的路线差异 ​

两个版本在「类与装饰器数据如何建立关联关系」这一核心问题上采用了完全不同的路线：

v4 版本：addInitializer → this.constructor → 建立关联 ​

v4 版本中，属性/方法装饰器通过 context.addInitializer 注册回调函数。这些回调在类实例化时执行，此时可以通过 this.constructor 获取到类的构造函数，从而建立「类 → 装饰器数据」的关联关系。

属性/方法装饰器执行 → addInitializer(callback)
                          ↓
                    类实例化时触发 callback
                          ↓
                    通过 this.constructor 获取类
                          ↓
                    建立 类 与 装饰器数据 的关联

这条路线的特点是：关联关系的建立依赖于实例化过程，装饰器数据的收集和关联是耦合在一起的。

v5 版本：context.metadata 收集数据 + @Injectable 建立关联 ​

v5 版本将数据收集和关联建立拆分为两个独立的阶段：

  1. 属性/方法装饰器在执行阶段直接将数据写入 context.metadata，只负责收集数据，不关心关联关系
  2. @Injectable 类装饰器在类定义阶段读取 context.metadata，通过 defineMetadata(target, metadata) 建立「类 → context.metadata」的关联关系
属性/方法装饰器执行 → 写入 context.metadata（仅收集数据）
                          ↓
@Injectable 类装饰器执行 → 读取 context.metadata
                          ↓
                    defineMetadata(target, metadata)
                          ↓
                    建立 类 与 context.metadata 的关联

这条路线的特点是：职责分离更清晰，数据收集不依赖实例化过程，关联关系在类定义阶段就已建立。

v4 版本的版本要求 ​

v4 版本使用 addInitializer 方案注册装饰器元数据。当 useDefineForClassFields: true 时，所有单元测试在任意版本的 esbuild/vite 下都能通过；当设置为 false 时，在较低版本的 esbuild 下会有部分单元测试失败。

但这里有一个关键发现：失败的单元测试在 typescriptlang.org/play/ 中是可以正常运行的。

根本原因在于编译器的差异：

  • typescriptlang.org/play/ 使用的是标准的 tsc 编译器，转译代码时完全符合 TC39 规范
  • 本地的单元测试使用 vitest，底层依赖 esbuild 作为编译器

经过在 esbuild.github.io/try/ 中测试，发现 esbuild 需要最低 0.24.0 版本才能在 useDefineForClassFields: false 时正确处理 Stage 3 装饰器的 addInitializer，对应的 vite 版本是 6.0.0。

也就是说，v4 版本在 useDefineForClassFields: false 时测试失败，并非 TypeScript 规范本身的问题，也不是本项目依赖了 useDefineForClassFields 配置，而是 esbuild 旧版本对 Stage 3 装饰器在 useDefineForClassFields: false 场景下的转译存在 bug。只要 esbuild 版本 ≥ 0.24.0（vite ≥ 6.0.0），v4 版本在 false 模式下同样能正常工作。

v5 版本的现状 ​

v5 版本已经将元数据注册方案从 addInitializer 改为直接使用 context.metadata。核心变化如下：

typescript
// v4 方案：通过 addInitializer 在实例化时注册元数据
function createDecorator(decoratorKey: string, defaultValue?: any) {
  return function (decoratorValue?: any) {
    return function (_value: undefined, context: ClassFieldDecoratorContext) {
      context.addInitializer(function (this: any) {
        // 在实例化阶段注册元数据
      });
    };
  };
}

// v5 方案：直接在装饰器执行阶段写入 context.metadata
function createDecorator(decoratorKey: string, defaultValue?: any) {
  return function (decoratorValue?: any) {
    return function (_value: undefined, context: ClassFieldDecoratorContext) {
      const meta = context.metadata as Record<string, any>;
      // 在类定义阶段直接写入元数据，不依赖实例化过程
      if (!hasOwn(meta, KEYS.INJECTED_PROPS)) {
        meta[KEYS.INJECTED_PROPS] = {};
      }
      // ...
    };
  };
}

经过验证，v5 版本在当前项目配置（[email protected]）下，无论 useDefineForClassFields 设置为 true 还是 false，所有单元测试都能通过。v5 版本不再依赖 useDefineForClassFields 这个配置项。

最低版本要求 ​

虽然 v5 版本不再受 useDefineForClassFields 的影响，但 context.metadata 本身对编译器版本有要求：

TypeScript 最低版本：5.2.2 ​

经过在 typescriptlang.org/play/ 中验证，TypeScript 低于 5.2.2 时，context.metadata 的实现是不正确的。因此本项目要求 TypeScript 版本必须 ≥ 5.2.2。

Vite / esbuild 最低版本：vite ≥ 5.3.0（esbuild ≥ 0.21.0） ​

vite 需要 ≥ 5.3.0（对应 esbuild ≥ 0.21.0）才开始支持 Stage 3 装饰器语法。低于此版本的 esbuild 无法正确编译 Stage 3 装饰器代码。

总结对比 ​

维度v4（addInitializer 方案）v5（context.metadata 方案）
useDefineForClassFields 依赖不依赖不依赖
TypeScript 最低版本5.05.2.2
true 时 esbuild 最低版本无特殊要求0.21.0
false 时 esbuild 最低版本0.24.00.21.0
true 时 vite 最低版本无特殊要求5.3.0
false 时 vite 最低版本6.0.05.3.0

最佳实践建议 ​

装饰器类型useDefineForClassFields 推荐值
Stage 1（experimentalDecorators）false
Stage 3（TC39 标准）true（推荐，但 v5 版本下 false 也可以）

对于本项目 v5 版本：

  • useDefineForClassFields 设置为 true 或 false 均可正常工作
  • 仍然推荐设置为 true，与 TC39 标准保持一致
  • TypeScript 版本必须 ≥ 5.2.2，否则 context.metadata 行为不正确
  • Vite 版本必须 ≥ 5.3.0（esbuild ≥ 0.21.0），这是支持 Stage 3 装饰器语法的最低版本

配置示例 ​

jsonc
// tsconfig.app.json — 推荐配置
{
  "compilerOptions": {
    "target": "ES2015",
    "useDefineForClassFields": true,  // 推荐设置为 true，与标准一致
    // ...
  }
}

如果将 target 升级到 ES2022 或更高版本，则可以省略 useDefineForClassFields，因为默认值就是 true：

jsonc
{
  "compilerOptions": {
    "target": "ES2022",
    // useDefineForClassFields 默认为 true，无需显式设置
  }
}

stage3 装饰器执行顺序 ​

enter method decorator
        ↓
enter field decorator
        ↓
enter class decorator
        ↓
class decorator addInitializer callback
        ↓
method decorator addInitializer callback
        ↓
field decorator addInitializer callback
        ↓
class constructor