TypeScript中如何增强全局window类型且不影响其他上下文的Window类型？

问题背景 #

之前通过扩展全局Window接口给window添加自定义属性类型：

declare global {
  interface Window {
    myCustomProperty: number
  }
}

window.myCustomProperty = 123;

但这种方式会污染所有Window接口实例，比如iframe的contentDocument.defaultView也会被推断拥有myCustomProperty，不符合需求——希望只有全局window有自定义属性类型，iframe和依赖库中的Window类型保持原样。

解决方案：不修改Window接口，直接覆盖全局window变量类型 #

TypeScript在lib.dom中对全局window的定义是：

declare var window: Window & typeof globalThis;

我们可以通过重新声明全局window变量的类型，把自定义属性绑定到这个变量上，而非修改Window接口本身：

步骤1：定义全局window专属类型 #

在全局声明文件（比如src/types/global.d.ts）中添加：

declare global {
  // 继承原始Window和globalThis类型，添加自定义属性
  interface GlobalWindow extends Window, typeof globalThis {
    myCustomProperty: number;
  }

  // 覆盖全局window变量的类型
  var window: GlobalWindow;
}

// 确保文件被当作模块处理
export {};

步骤2：验证效果 #

declare function getFrameElement(): HTMLIFrameElement;

// ✅ 无TS错误，全局window拥有自定义属性
console.log(window.myCustomProperty);

// ❌ TS报错：Property 'myCustomProperty' does not exist on type 'Window | null'
console.log(getFrameElement().contentDocument.defaultView?.myCustomProperty);

原理说明 #

• 没有修改原始Window接口，所以所有基于Window接口的实例（iframe的defaultView、依赖库中的Window类型）都保持原有定义
• 仅通过重新声明全局window变量的类型，让这个特定变量拥有自定义属性，实现了全局window和其他Window实例的类型区分
• 无需手动类型断言或工具函数，TypeScript会自动推断全局window的正确类型

内容的提问来源于stack exchange，提问作者Kevin Fleischman