TypeScript 声明文件（.d.ts）从零为无类型库添加类型支持

老前端的功夫

470人浏览 · 2026-04-13 08:00:00

老前端的功夫 · 2026-04-13 08:00:00 发布

TypeScript 声明文件（.d.ts）：从零为无类型库添加类型支持

你在项目中使用了一个 npm 包，安装完后一导入，TypeScript 直接报错：

import * as legacyLib from 'legacy-lib';
// 报错：Could not find a declaration file for module 'legacy-lib'.

这个库确实能用，但因为没有类型声明，TS 只能把它当作 any，或者直接罢工。
这时候就需要你亲自出手，给它写一份声明文件（.d.ts）。

声明文件是 TypeScript 与无类型 JavaScript 代码之间的桥梁。今天我就带你从最简单的补丁，写到完整的类型定义。

一、什么是 .d.ts？

.d.ts 文件只包含类型声明，不包含具体实现。它的作用就是告诉 TypeScript 某个模块、变量、函数长什么样。

// types.d.ts
declare function sayHello(name: string): void;

编译后，这个文件会被完全移除，不会影响运行时。

二、快速解决：本地声明模块

如果你只需要让某个库不报错，或者只用了它的一小部分 API，最快的方式是在项目中创建一个 shims.d.ts 文件，加上：

declare module 'legacy-lib';

这相当于把该模块声明为 any，TypeScript 不会再报找不到模块的错误。
但你调用它的任何方法都不会有类型提示，相当于放弃治疗。

稍微好一点的做法：只声明你需要的 API：

declare module 'legacy-lib' {
  export function init(config: { apiKey: string }): void;
  export function track(event: string, data?: any): void;
}

这样你在调用 init 和 track 时就能得到类型提示和检查。

三、编写完整的声明文件

假如你用的库暴露了一个全局变量 LegacyLib，或者是一个模块，你需要完整描述它的类型。

1. 声明全局变量

有些库通过 <script> 标签引入，挂载到 window 上。比如老版本的 jQuery：

// global.d.ts
declare const $: {
  (selector: string): any;
  ajax(url: string, settings?: any): void;
};

使用：

$('#app');
$.ajax('/api/data');

2. 声明模块

如果是通过 import 导入的模块，需要在 declare module 里写：

// types/legacy-lib.d.ts
declare module 'legacy-lib' {
  export interface Config {
    apiKey: string;
    debug?: boolean;
  }

  export function init(config: Config): void;

  export class Client {
    constructor(token: string);
    get(path: string): Promise<any>;
  }
}

注意：文件名不重要，只要被 TypeScript 加载到即可（通常放在项目内的任意 .d.ts 文件中，会被自动包含）。

3. 声明命名空间

如果库同时提供全局变量和模块形式（比如 UMD），可以用命名空间：

declare namespace LegacyLib {
  function init(config: any): void;
  namespace utils {
    function format(str: string): string;
  }
}

这样既可以通过 LegacyLib.init() 访问，也可以通过 import * as LegacyLib from 'legacy-lib' 访问（如果模块声明兼容）。

四、发布你的声明文件

如果你想让所有人都受益，可以把写好的声明文件贡献给 DefinitelyTyped，或者直接放在库本身。

1. 通过 DefinitelyTyped 发布

大多数流行库的类型都在 @types/ 命名空间下。如果你的库没有被收录，可以去 DefinitelyTyped 提交 PR。

2. 在库中自带类型

如果你是库作者，直接在项目中生成声明文件：

在 tsconfig.json 中开启 declaration: true，编译时会自动生成 .d.ts。
在 package.json 中指定 types 字段（或 typings）：

{
  "name": "my-lib",
  "main": "lib/index.js",
  "types": "lib/index.d.ts"
}

这样使用者安装你的库后就能自动获得类型支持。

五、高级场景：扩充已有类型

1. 为全局对象添加属性

比如你想在 window 上挂载一个自定义属性：

// global.d.ts
interface Window {
  myCustomApi: {
    doSomething(): void;
  };
}

现在 window.myCustomApi 就不会报错了。

2. 扩充第三方模块

假设你想给 Express 的 Request 对象添加一个 user 属性：

// types/express.d.ts
import 'express';

declare module 'express' {
  interface Request {
    user?: {
      id: string;
      name: string;
    };
  }
}