如何为含全局变量的原生JS库编写正确的.d.ts声明文件

场景说明 #

你的库加载后直接在全局作用域暴露变量（比如window.MyLib或全局MyLib），需要让TypeScript项目自动识别这些全局类型，无需手动导入。

正确写法 #

基础全局声明（仅全局挂载场景） #

创建types.d.ts文件，内容如下：

// 关键：添加空导出，将文件转为外部模块，解决全局增强的语法限制
export {};

declare global {
  // 声明挂载在window上的全局变量
  interface Window {
    MyLib: {
      doSomething: (input: string) => boolean;
      version: string;
      // 补充你的库的其他类型定义
    };
  }

  // 如果库直接暴露全局变量（无需window前缀），直接声明
  const MyLib: typeof window.MyLib;
}

然后在package.json中指定类型入口：

{
  "types": "./types.d.ts"
}

兼容模块导入+全局挂载的场景 #

如果你的库同时支持import MyLib from 'your-lib'和全局挂载，可同时声明模块导出与全局类型：

// 先声明模块的导出类型
export interface MyLibAPI {
  doSomething: (input: string) => boolean;
  version: string;
}

// 模块默认导出
declare const MyLib: MyLibAPI;
export default MyLib;

// 增强全局作用域
export {};

declare global {
  interface Window {
    MyLib: MyLibAPI;
  }

  const MyLib: MyLibAPI;
}

错误原因拆解 #

• "Augmentations for the global scope can only be directly nested in external modules..."：
  未添加export/import的.d.ts会被视为全局脚本，不属于外部模块，无法使用declare global。添加export {}即可将文件转为外部模块，满足语法要求。

• "A 'declare' modifier cannot be used in an already ambient context."：
  declare module块本身已是环境上下文，内部无需再用declare修饰global块，直接写global { ... }即可（但更推荐用上述基础方案，避免嵌套复杂度）。

验证方式 #

其他项目安装你的库后，新建.ts文件直接使用MyLib.doSomething("test")，若编辑器能自动提示类型、无类型报错，说明配置生效。

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