在 TypeScript 中征服 `window`：如何添加自定义属性而不破坏代码

轻松学习Python，无需理论负担。在浏览器中直接解决带自动检查的实践任务，无需安装任何东西。

引言：为什么向 `window` 添加属性是每个 TypeScript 开发者的头疼问题？

想象一下这个场景：您正在用 TypeScript 编写一个现代 SPA 应用。一切进展顺利，直到您需要保存全局状态或与外部脚本（例如分析工具、地图或支付网关）集成。您写下：

window.myAppConfig = { apiKey: '123' };

然后 TypeScript 给您显示一个红色错误："Property 'myAppConfig' does not exist on type 'Window & typeof globalThis'"。熟悉吗？这个问题在 Stack Overflow 上获得了数千次浏览，今天我们不仅会给出现成的解决方案，还会深入 TypeScript 的内部，理解为什么会发生这种情况，以及如何优雅且安全地处理它。

在本文中，我们将探讨几种方法——从初学者的“权宜之计”到高级开发人员使用的专业模式。我们开始吧！

内部机制：为什么 TypeScript 会对 `window.myProp` 报错？

要理解这个问题，我们需要记住 TypeScript 是 JavaScript 的一个超集，它添加了静态类型检查。浏览器中的 window 对象是一个全局对象，具有预定义的类型（Window）。该类型在 TypeScript 的标准库（lib.dom.d.ts）中定义，包含所有标准属性：document、location、setTimeout 以及数百个其他属性。

当您尝试赋值 window.myProp 时，TypeScript 会检查：“Window 接口中是否有这个属性？”。如果没有——就会报错。这是为了防止拼写错误和意外污染全局作用域。但是，如果您故意想要扩展 window，该怎么办？

方法 1：最简单但危险的方法——`as any`

初学者首先想到的第一个方法就是通过类型转换来“堵住”TypeScript 的嘴：

(window as any).myAppConfig = { apiKey: '123' };

优点：快速、有效，无需额外定义。

缺点：您会失去 TypeScript 的所有优势。没有自动补全，没有类型检查。如果您不小心写成了 myAppConfigg——不会报错，但应用会在运行时崩溃。这就像关掉汽车的安全气囊——可以开，但很危险。

何时使用：仅用于快速原型开发，或者当您确信该属性只会使用一次并且会被删除时。

方法 2：扩展全局接口（接口合并）

TypeScript 支持接口合并（declaration merging）。这是一个关键机制，允许您向现有的 Window 类型“添加”新属性。为此，您需要在全局作用域中声明一个同名的接口。

创建一个 global.d.ts 文件（或添加到您项目中的任何 .d.ts 文件）：

// global.d.tsinterface Window {    myAppConfig: {        apiKey: string;        debugMode?: boolean;    };    myAnalyticsFunction: (event: string, data: object) => void;}

现在您可以这样写：

window.myAppConfig = { apiKey: '123' };window.myAnalyticsFunction('page_view', { page: '/home' });

// TypeScript 会提示 apiKey 是 string 类型console.log(window.myAppConfig.apiKey); // ✅ 无错误

内部是如何工作的？ TypeScript 会自动合并所有同名的接口声明。如果 lib.dom.d.ts 中已经存在 interface Window { ... }，您同名的接口只会向其中添加新属性。这被称为全局增强（global augmentation）。