在 typescript 中，使用 declare global 扩展 window 接口需将声明置于无 import/export 的全局上下文（如 global.d.ts），正确声明后可获得类型提示与编译检查，接口支持合并扩展，函数或对象应标注具体类型而非 any。

在 TypeScript 中，使用 declare global 扩展 Window 接口，是为了让自定义挂载到 window 上的全局变量获得类型提示和编译时检查。关键在于正确声明全局命名空间，并确保声明文件被 TypeScript 识别。

确保声明在全局作用域中

不能把 declare global 写在模块（即含 import 或 export 的文件）内部，否则它只会扩展该模块的局部作用域，不会影响全局 Window。必须放在“无导入导出”的全局上下文中，例如：

• 新建一个 global.d.ts 文件（推荐，且需位于项目根目录或 types 目录下，并被 tsconfig.json 包含）
• 文件内容以 declare global 开头，且不包含任何 import 或 export

正确扩展 Window 接口

在 global.d.ts 中写入：

declare global {
  interface Window {
    myGlobalVar: string;
    __APP_ENV__: Record<string string>;
    $bus: EventEmitter;
  }
}</string>

这样之后，在任意地方访问 window.myGlobalVar 或 self.__APP_ENV__ 都会有类型提示和类型校验。注意：接口是“合并”的，不是覆盖，所以可多次声明扩展。

Add Typescript Best Practices

在 CLAUDE.md 中配置 TypeScript 最佳实践和代码风格规则

下载

处理值为函数或复杂对象的情况

如果挂载的是函数，建议用函数类型或调用签名；如果是类实例，可引用已定义的类型：

• myUtils: { format: (s: string) => string };
• SDK: typeof import('./sdk').default;（需配合 /// <reference types="..."></reference> 或确保类型可见）
• 避免直接写 any，优先用具体类型提升安全性

验证是否生效

重启 TypeScript 服务（如 VS Code 中重启 TS Server），然后测试：

• 输入 window.，看提示中是否出现你定义的属性
• 尝试赋值错误类型，如 window.myGlobalVar = 123，应报类型错误
• 确保 tsconfig.json 的 include 或 typeRoots 覆盖了声明文件路径

不复杂但容易忽略。