TypeScript如何将ambient声明应用到window挂载的未知对象

首先明确你之前写法的两个核心问题：

• @types/gapi是纯类型声明包，不存在任何运行时可执行代码，你尝试导入@types/gapi或者对应路径下的.d.ts文件本身就是错误用法，既无法得到有效运行时实体，也不需要这么做。
• 你写的const gapi = window.gapi as gapi存在变量名和类型名冲突，编译器无法识别第二个gapi是类型还是你声明的变量。

前置准备 #

先确保你已经把@types/gapi安装到开发依赖：

npm install @types/gapi --save-dev

@types/gapi属于ambient全局类型包，TS会自动加载该包的类型声明到全局作用域，不需要你手动导入任何类型文件就能直接使用gapi相关类型。

方案1：直接使用window.gapi（推荐） #

不需要做任何额外赋值操作，默认情况下你使用window.gapi就已经带有完整类型提示。
如果你的TS配置开启了严格检查，识别不到Window上的gapi属性，可以在项目的全局类型声明文件（比如global.d.ts，需放在tsconfig.json的include覆盖范围内）中补充Window接口扩充：

interface Window {
  gapi: typeof gapi
}

配置完成后所有window.gapi的调用都会有正确的类型校验和提示。

方案2：提取为单独变量使用 #

如果你需要把window.gapi提取为单独的变量使用，直接用全局类型做断言即可，注意规避命名冲突：

// 写法1：避开命名冲突，直接用全局类型
const gapi = window.gapi as typeof globalThis.gapi

如果想更规范的显式导入类型，可以用TS的import type语法（仅导入类型，不会产生任何运行时代码）：

// 写法2：显式导入类型，避免全局类型依赖
import type { gapi as GapiType } from "gapi"
const gapi = window.gapi as GapiType

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