如何使用TypeScript为Three.js等图形库编写强类型封装？

Three.js是一个优秀的WebGL图形库，但它本身用JavaScript编写，即便官方提供了类型声明包，直接在业务代码里使用时，仍然容易出现参数拼错、单位混淆、资源类型不匹配等问题。这类错误在编译期无法暴露，只能等到场景渲染出黑屏或控制台报错时才发现。为图形库编写一层TypeScript强类型封装，可以让大量低级错误在编写阶段就被编辑器红线标出，同时也能让团队中不熟悉图形学的同事安全地使用三维能力。本文将以Three.js为例，从声明文件、类型约束、资源加载到封装模式，完整介绍一套可落地的做法。

一、先理清封装的两种思路：声明文件还是包装层

第一种思路是只写类型声明，不改变任何运行时行为。Three.js官方维护了@types/three与自带的类型文件，这种方式适合API调用者已经比较熟练的团队，成本最低。但如果想在业务层屏蔽掉Three.js的细节，让渲染引擎将来可以替换（比如换成Babylon.js），就需要第二种思路：写一个真正的包装层，对外只暴露自己定义的类型和函数。

包装层的核心价值在于收窄API。Three.js的Mesh构造函数接受BufferGeometry和Material，这两者都是庞大的基类，直接暴露给业务代码意味着业务方可以传入任何材质子类，出现不合理的组合。在封装层中，我们可以定义一个只允许特定几何体与特定材质组合的工厂函数，把组合规则固化在类型签名里。

两种思路并不冲突。常见的企业实践是：底层直接依赖官方类型声明，中间层做包装，业务层只 import 中间层的导出。这样即使Three.js升级带来类型变动，也只需要修改中间层，业务代码不受影响。

二、用字面量联合类型与泛型约束参数合法性

图形API里最典型的隐患是字符串枚举参数。比如Three.js的阴影类型、纹理包裹模式、颜色空间，都是靠字符串区分的。拼错一个字符不会有任何编译报错。解决办法是用字面量联合类型把这些取值固化下来。

// 定义纹理包裹模式的合法取值
type WrapMode = 'repeat' | 'clamp-to-edge' | 'mirrored-repeat';

// 用映射把字符串映射到Three.js的常量
const wrapModeMap: Record<WrapMode, THREE.Wrapping> = {
  'repeat': THREE.RepeatWrapping,
  'clamp-to-edge': THREE.ClampToEdgeWrapping,
  'mirrored-repeat': THREE.MirroredRepeatWrapping,
};

// 对外暴露的封装函数，参数被严格约束
function setTextureWrap(tex: THREE.Texture, mode: WrapMode): void {
  tex.wrapS = wrapModeMap[mode];
  tex.wrapT = wrapModeMap[mode];
  tex.needsUpdate = true;
}

这种写法的好处是双重的。一方面调用方传入非法字符串时编辑器立刻报错，另一方面wrapModeMap的类型是Record<WrapMode, THREE.Wrapping>，如果将来新增一个合法值却忘记在映射表里补齐，编译也无法通过。类型系统同时在保护函数的两端。

泛型则适合管理场景对象。假设我们维护一个按名称索引的对象注册表，希望取出来时能自动恢复具体类型，可以这样设计：

class ObjectRegistry {
  private store = new Map<string, THREE.Object3D>();

  register<T extends THREE.Object3D>(name: string, obj: T): void {
    this.store.set(name, obj);
  }

  // 泛型根据注册时推断的类型收窄返回值
  get<T extends THREE.Object3D>(name: string, ctor: new (...args: any[]) => T): T {
    const obj = this.store.get(name);
    if (!(obj instanceof ctor)) {
      throw new Error(`对象 ${name} 的类型不匹配`);
    }
    return obj;
  }
}

这里用构造函数签名作为类型凭证，运行时做instanceof校验，编译时用泛型收窄返回类型，双层保障。调用registry.get('hero', THREE.Mesh)拿到的就是Mesh类型，可以直接访问geometry和material，不需要手动断言。

三、资源加载器的类型安全设计

资源加载是图形项目里另一个事故高发区。贴图、模型、音频的URL都是字符串，加载器选错类型或者后缀名写错，通常要到加载失败才被发现。可以设计一个根据后缀名自动分发的加载器，并用重载让返回类型精确到具体资源类型。

type TextureUrl = `${string}.png` | `${string}.jpg` | `${string}.webp`;
type ModelUrl = `${string}.gltf` | `${string}.glb`;

function loadAsset(url: TextureUrl): Promise<THREE.Texture>;
function loadAsset(url: ModelUrl): Promise<THREE.Group>;
function loadAsset(url: string): Promise<unknown> {
  // 实现里根据后缀分发到不同loader
  if (url.endsWith('.gltf') || url.endsWith('.glb')) {
    return gltfLoader.loadAsync(url).then(g => g.scene);
  }
  return textureLoader.loadAsync(url);
}

模板字面量类型在这里发挥了很大作用。TextureUrl描述的不是任意字符串，而是必须以特定后缀结尾的字符串。在VSCode里输入路径时，配合路径自动补全插件，体验接近于直接引用文件。如果传入hero.gltf却按Texture使用，编译期就会报错，因为重载签名不允许这种组合。

对于模型内部结构，可以用可辨识联合描述节点类型。骨骼、蒙皮网格、相机各自有不同的属性集合，定义成联合类型后，配合switch分支的类型收窄，访问每个分支的专属属性时不需要断言，编辑器还能检查分支是否遗漏。

四、用Builder模式约束复杂对象的初始化

材质、灯光这类对象的构造参数往往有十几个，而且单位各异：距离用米、角度用弧度、颜色可以是十六进制数或字符串。直接用一个巨大的options对象，很容易把角度传成了度数。Builder模式配合类型别名可以缓解这个问题。

// 用类型别名显式标注单位，避免混淆
type Radian = number & { __unit: 'radian' };
type Meter = number & { __unit: 'meter' };

const rad = (deg: number): Radian => (deg * Math.PI / 180) as Radian;
const m = (v: number): Meter => v as Meter;

class SpotLightBuilder {
  private opts = {
    color: 0xffffff,
    angle: rad(45),
    distance: m(10),
    penumbra: 0.2,
  };

  withAngle(angle: Radian): this {
    this.opts.angle = angle;
    return this;
  }

  withDistance(d: Meter): this {
    this.opts.distance = d;
    return this;
  }

  build(): THREE.SpotLight {
    const light = new THREE.SpotLight(this.opts.color);
    light.angle = this.opts.angle;
    light.distance = this.opts.distance;
    light.penumbra = this.opts.penumbra;
    return light;
  }
}

branded type（品牌类型）的技巧在于用交叉类型给number打上标记。裸数字字面量无法直接赋给Radian，必须经过rad函数转换，转换过程本身就是单位换算发生的地方。这样一来，withAngle(45)会直接编译报错，必须写成withAngle(rad(45))，度数与弧度混淆的问题从根源上被堵住。

Builder的每个方法都返回this，支持链式调用的同时保留了具体类型，后续扩展子类Builder也不会丢失方法。这种方式虽然比直接传对象多写一些代码，但对于参数多、组合规则复杂的图形对象来说，可维护性提升非常明显。

五、封装过程中的注意事项

首先要避免过度封装。Three.js的能力非常丰富，如果每个API都包一层，封装层会迅速膨胀且难以维护。建议只封装业务高频使用的部分，比如资源加载、对象创建、相机控制，其余能力通过导出Three.js本身类型的方式让需要的人直接使用，保留逃生舱口。

其次要注意类型断言的使用纪律。在封装层内部，遇到Three.js回调里类型不够精确的地方，可以用as断言，但要确保断言伴随着运行时校验，例如上面注册表中的instanceof检查。只有类型断言而没有运行时验证的代码，等于把风险从编译期推迟到了线上。

最后，建议把封装层单独作为一个npm包或workspace包管理，并为其编写接口级别的类型测试，例如用@ts-expect-error标注那些应当编译失败的调用，纳入持续集成。一旦有人误改了类型约束导致防线失效，测试会立刻发现。这样整套强类型封装才能长期稳定地服务项目。

TypeScriptThree.js类型声明修改时间：2026-09-15 19:08:54