[!info] related notes

• 所属 MOC: TypeScript MOC
• 总览页: TypeScript
• 相关概念: TypeScript 中的 .d.ts 声明文件, TypeScript 中的声明合并
• 并列概念: TypeScript 中的 import type 与普通 import

TypeScript 中的全局声明与全局扩展

一句话定义

全局声明与全局扩展用来告诉 TypeScript：某些名字虽然不是当前模块显式导出的，但它们确实会在全局环境中存在，或者需要在现有全局对象上补充类型信息。

核心机制 / 工作原理

全局声明

全局声明最常出现在 .d.ts 文件里，用来直接向全局作用域补充类型。

全局扩展

如果当前文件已经是模块（含 import / export），想修改全局类型，就要通过 declare global 进入全局作用域。

模块扩展

如果目标不是全局对象，而是某个已有模块的导出类型，就需要模块扩展，而不是全局扩展。

最小例子 / 最小场景

在 .d.ts 中补充 Window

interface Window {
  appConfig: {
    apiUrl: string;
  };
}

在模块文件中扩展全局

export {};

declare global {
  interface Window {
    appConfig: {
      apiUrl: string;
    };
  }
}

常见应用场景

• 给 window 挂全局配置
• 给第三方脚本注入的全局变量补类型
• 给测试环境补充全局 helper 类型
• 给 SSR 注入的首屏数据补类型

边界与易混淆点

Window 扩展只是其中一种场景

很多旧资料会把“全局声明”直接等同于“扩展 Window”，但这只是最常见案例，不是完整范围。

类型存在不代表运行时一定存在

全局声明只影响编译阶段。运行时如果没有真正挂上这个对象，代码依然会出错。

模块扩展不等于全局扩展

如果你在改的是某个库的模块类型，而不是浏览器或 Node 的全局对象，就应该用模块扩展的写法，而不是 declare global。