TypeScript 模块扩展

星光不问赶路人2025-08-05 18:11

TypeScript 支持你"扩展现有模块的类型定义 "，这称为 模块扩展（Module Augmentation），常见于：

为第三方库添加缺失的类型定义
扩展现有模块的接口或类型
使用 declare module 'xxx' 扩展模块内容

❗ 为什么要"放在模块中"？

如果你写了 declare module 'xxx' {...}：

✅ 如果这个文件是一个模块（有 export {}），那么你写的东西是"扩展"原模块。
❌ 如果这个文件是 script（无 import/export），那它就是"声明一个全新的模块"，会覆盖原来的类型！

✅ 示例：正确扩展模块

typescript 复制代码

// example.d.ts
export {}; // 👈 让这个文件成为模块！

declare module 'vue' {
  interface ComponentCustomProperties {
    $trans: (key: string) => string;
  }
}

✅ 这样，TypeScript 会将你的扩展合并到 'vue' 原来的类型中。

❌ 示例：错误用法（会覆盖原模块）

typescript 复制代码

// example.d.ts
// ❌ 没有 export/import，这会变成全局 script

declare module 'vue' {
  interface ComponentCustomProperties {
    $trans: (key: string) => string;
  }
}

这样会导致 TypeScript 认为你声明的是整个模块的完整定义 ，原有类型就会被完全替换掉，造成类型错误或丢失。

✅ 总结一句话：

如果你想扩展 TypeScript 中的已有模块，记得把扩展代码放在一个模块文件里（至少写个 export {}），否则它就不是"扩展"，而是"覆盖"了！