为第三方JS库编写TypeScript声明文件的核心是用类型语法准确描述其运行时行为，仅包含接口、类型、函数签名和变量声明，不包含实现；需根据UMD、ES模块或CommonJS等引入方式选择declare global、export或export =等对应声明策略，并可通过dts-gen生成骨架后手动完善类型。

为第三方 JavaScript 库编写 TypeScript 声明文件（.d.ts），核心是用类型语法准确描述该库的运行时行为，不包含实现，只导出接口、类型、函数签名和变量声明。

理解声明文件的基本结构

声明文件以 declare 开头，不执行任何逻辑，仅用于类型检查。常见形式包括：

• 全局变量声明：如 declare const $: JQueryStatic;
• 模块导出声明：用 export 描述 ES 模块或 CommonJS 导出，例如 export function foo(): string;
• 命名空间声明：适用于通过 window.MyLib 访问的对象，用 declare namespace MyLib { ... }
• 类/接口/类型别名声明：如 export interface Options { timeout?: number; }

针对不同引入方式编写对应声明

根据目标库的实际使用方式选择声明策略：

Alibabacloud Sdk Client Initialization For Java

在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。

下载

• UMD / 全局脚本（如 <script src="xxx.js">）：用 declare global 扩展全局作用域，或直接写顶层 declare const/let/function
• ES 模块（import xxx from 'xxx'）：用 export 或 export default，配合 export =（若库是 CommonJS 默认导出）
• CommonJS（require('xxx')）：常用 export = + declare module 'xxx' { ... } 包裹整个模块
• 同时支持多种引入方式：需在同一个 .d.ts 中组合使用 declare module、declare global 和命名空间

快速生成基础声明并手动完善

不必从零手写全部内容：

立即学习“Java免费学习笔记（深入）”；

• 用 npx dts-gen -m your-lib-name 自动生成骨架（需已安装该库）
• 用 declare module 'your-lib-name' { export * as default; } 临时启用类型检查，再逐步补全具体类型
• 参考源码或文档，把关键函数参数、返回值、对象属性补上类型，例如：
  export function request(url: string, options?: { method?: string; headers?: Record<string, string> }): Promise<any>;
• 对动态属性或不确定结构，合理使用 [key: string]: any、unknown 或 Record<string, unknown>，避免过度 any

发布与使用声明文件

本地开发可直接将 .d.ts 放入项目 types/ 目录，并在 tsconfig.json 中配置：
"typeRoots": ["./types", "./node_modules/@types"]
或通过 /// <reference types="./types/your-lib" /> 单文件引用。

想让社区复用，可向 DefinitelyTyped 提交 PR，或在库包中内建 types 字段指向声明文件。