我第一次意识到 .d.ts 文件不是摆设，是在一个跑了几年的 JavaScript 老项目里。当时项目准备整体迁到 TypeScript，但第三方依赖鱼龙混杂，有的库自带类型，有的库连 types 都没有，还有一堆挂在 window 上的全局变量。那段时间我每天的工作就是跟报错搏斗，而所有报错的根源，最后几乎都指向同一个东西——缺一份能描述“数据长什么样”的声明文件。后来我自己动手写了几个 .d.ts，又把 tsconfig 里的编译配置捋了一遍，才算真正弄明白这个文件在前端工程里的分量。
如果你正在写 TypeScript，或者准备从前端切到 TS/迁移老项目，又或者面试时被问到“.d.ts 到底干嘛的”，这篇内容基本能把概念、语法、工程配置、实战坑位一次讲透。我会从“它解决什么问题”讲到“怎么写一份能用的声明文件”，最后附上我在实际项目里踩过的坑和排查思路，保证不是那种背一遍文档就完事的空话。
1. 先搞清楚 .d.ts 在项目里扮演什么角色
1.1 .d.ts 不是业务代码，它是数据的地图
一句话先说结论：.d.ts 是 TypeScript 的类型声明文件，里面没有任何实现逻辑，只描述“某个模块、某个变量、某个函数长什么样”。
你可以把它理解成一张地图。业务代码是城市里的路和楼，.d.ts 是标注了路名、楼号、公交站牌的图册。浏览器运行的时候根本不需要这张图，它只看实际的 JavaScript 代码；但开发的时候，TS 编译器、VSCode 的智能提示、IDE 的自动补全，全都要靠这张图来认路。
所以 .d.ts 有这几个关键特征：
- 文件扩展名是
.d.ts，不是.ts，更不是.js。 - 只包含类型定义、接口声明、变量声明，不包含
console.log、if、for这类运行时代码。 - 编译之后不会生成任何 JavaScript 文件。TS 编译器看到
.d.ts只会把它当“说明书”读取，不会输出xxx.d.js这种产物。 - 它既可以跟同名的
.js文件放在一起（比如lodash.d.ts描述lodash.js），也可以单独存在（比如global.d.ts描述全局变量）。
理解“不会生成 JS”这一点很重要。很多新手把 .d.ts 当成普通 .ts 文件来写，往里塞实现代码，结果编译产物里多出一堆莫名其妙的文件，或者在声明里写了export =又同时写了export default，把自己绕晕。总之，.d.ts 的存在目的只有一个：让 TypeScript 在编译期“知道”某个东西的类型，它不参与运行时。
1.2 为什么没有 .d.ts，TS 项目会寸步难行
TypeScript 之所以能帮你提前发现 bug，靠的是它在上手阶段就建立一个“类型系统”，对所有进出的数据做静态检查。可现实是，前端项目里大量依赖都是 JavaScript 写的，而 JavaScript 本身没有类型，TS 编译器默认情况下对没有声明的 JS 模块是什么态度？一团黑。
举个最常见的场景：
import _ from 'lodash'; _.chunk([1, 2, 3], 1);如果lodash没有自带类型，也没有@types/lodash，TS 会直接报错：
TS7016: Could not find a declaration file for module 'lodash'.这种报错本质就是 TS 在说：“我看到了一个叫 lodash 的东西，但我不知道它导出了什么，不知道chunk函数有几个参数，所以我没法帮你检查。”
你当然可以用// @ts-ignore强行忽略，但那样做等于放弃了这个模块的所有类型检查，函数参数写错、返回值类型对不上，编译器一概不管。真正靠谱的做法是：为这个模块提供一份 .d.ts，让 TS 知道lodash里有哪些函数、参数怎么传、返回什么。
还有一类是全局变量。比如你用了百度地图或高德地图的 JS SDK，它在window上挂了一个BMap或AMap，但你项目里没有任何地方声明过这两个东西。在 TS 里直接写：
const map = new BMap.Map('container');TS 照样报错：找不到名称BMap。这时候就需要一个全局声明文件，把BMap声明成一个全局 namespace，告诉 TS “这东西确实存在于全局环境中，你别乱报”。
所以 .d.ts 解决的其实是一类非常基础但又避不开的问题：让 TypeScript 的静态检查能力，能够覆盖到那些并非由 TS 编写的代码之上。这类代码主要有三种：第三方 JS 库、运行环境注入的全局 API、项目中非 TS 模块（图片、CSS、JSON 等）。
2. 核心语法拆解：声明文件到底怎么写
2.1 模块声明与全局声明的区别，你别搞混
很多人在 .d.ts 里栽跟头，第一个坑就是分不清“模块声明”和“全局声明”。
如果你在 .d.ts 文件的顶层写了import或export，那这个文件就会被 TS 当成一个模块（module），里面所有类型都归属于这个模块，外部想要使用必须通过import引入。如果这个文件里既没有import也没有export，那它就是一份全局脚本声明，里面声明的类型会直接放到全局命名空间中，项目任何文件都能直接用，不需要 import。
这个细节直接决定 .d.ts 是“给某个库用的”还是“给全项目用的”。举个例子：
// types/lodash.d.ts declare module 'lodash' { export function chunk<T>(array: T[], size?: number): T[][]; }这里有declare module，是典型的“模块声明”，文件里没有顶层import/export也没关系，因为declare module 'lodash'本身就定义了一个模块。项目里其他地方import _ from 'lodash'时，TS 就会去找这个声明里描述的内容。
再看全局声明：
// types/global.d.ts interface Window { BMap: { Map: new (container: string | HTMLElement) => any; // 其他 API 方法声明 }; }这里没有declare module，没有import/export，所以Window扩展会直接注入全局。你业务代码里写window.BMap就不会报错了。
这里有个特别容易踩的坑：如果你在global.d.ts顶部写了个import xxx from 'xxx'，这个文件就不再是全局脚本，而是变成模块了。此时你再声明interface Window，它不会作用于全局，而是只在当前模块里生效，业务代码里window.BMap照样报错。
我自己处理这个问题的办法是：全局声明文件里禁止写任何 import/export。如果全局声明需要引用其他模块里的类型，那就用import()类型语法动态引入：
interface Window { axios: typeof import('axios').default; }这样既引用了类型，又不会把文件变成模块。
2.2 几个高频关键词：declare、namespace、export 的实战用法
.d.ts 里最常出现的语法有下面这些，它们各自解决不同的问题：
declare var / declare function / declare class
用来声明一个“已经存在”但 TS 不知道的全局变量、函数或类。比如老项目里用script标签引入 jQuery，没有走模块化，那全局就有个$，你可以这样声明：
declare var $: (selector: string) => any; declare function $(selector: string): any;注意，这里只描述形状，不写实现，所以$后面直接跟类型，不需要= function() {}。
declare namespace
用来把一组相关的类型、变量、函数收拢到一个命名空间里。比如某个全局 SDK 挂在window.MySDK上，里面又有init、config、request等方法，可以这样写：
declare namespace MySDK { function init(options: { appId: string }): void; function request<T = any>(url: string, options?: RequestInit): Promise<T>; interface Config { timeout: number; } }这样项目里可以直接写MySDK.init({ appId: 'xxx' })，TS 能识别。
declare module
用来描述一个没有类型声明的 npm 包，或者给非 TS 模块做“兜底声明”。最常见的写法：
declare module 'some-js-lib' { export function doSomething(arg: string): number; export const version: string; }还有一种懒人写法是“万能模块声明”：
declare module 'some-js-lib';这是把模块声明成 any，任何导入都直接通过。这种写法适合你只是想“让报错消失”的临时场景，但也意味着整个模块没有任何类型检查，所以我不建议在核心业务代码上这么干。
export = 与 export default
如果你的库是通过 CommonJS 方式导出（module.exports = xxx），而且用import xxx from 'xxx'这种默认导入方式引入，那声明文件可能得用export =：
declare module 'legacy-lib' { const legacyLib: { method(): void }; export = legacyLib; }注意，export =和export default不能混着用，否则 TS 会报语法冲突。我见过不少人在 .d.ts 里同时写export default和export =，结果编译直接失败。
2.3 三斜线指令：声明文件之间的引用关系
如果你把声明文件拆成了多个 .d.ts，需要在文件之间建立依赖关系，那就要用到三斜线指令。最常见的是：
/// <reference types="node" />这表示当前声明文件依赖 Node.js 的类型定义。另一个是：
/// <reference path="./other.d.ts" />这用来手动引入另一个 .d.ts 文件。一般在全局声明场景下，如果你的global.d.ts里引用了一个user.d.ts里的接口，那你就得在global.d.ts顶部加一个/// <reference path="./user.d.ts" />，让 TS 知道它依赖的文件在哪。
注意，三斜线指令只能放在文件最顶部，前面不允许有任何 import/export 语句。它跟 ES Module 的import不同，不能随便写在代码中间。
3. 实战案例：从零到一个项目写 .d.ts
3.1 场景一：给一个没有任何类型的 JS 库写声明
假设你从 npm 装了一个叫my-utils的老库（纯 JS 写的，作者没有提供 types），它的源码是这样的：
// my-utils/index.js module.exports = { sum: (a, b) => a + b, multiply: (a, b) => a * b, };在你的项目里，需要import utils from 'my-utils'使用。但 TS 根本不知道sum和multiply是干嘛的，于是报错。解决方式：在项目里建一个types/my-utils.d.ts：
declare module 'my-utils' { export function sum(a: number, b: number): number; export function multiply(a: number, b: number): number; }如果你用的是export =风格（CommonJS），也可以写成：
declare module 'my-utils' { const utils: { sum(a: number, b: number): number; multiply(a: number, b: number): number; }; export = utils; }然后需要在 tsconfig.json 里把types目录包含进去。否则 TS 不会去找这个文件。具体怎么配，我在第 4 节讲。
3.2 场景二：扩展 window 上的全局对象
又一个高频场景：项目里用了某个第三方 SDK，它把实例挂到了window上，比如：
// 在 index.html 里 <script src="https://example.com/sdk.js"></script> <script> window.analytics = new Analytics({ key: 'xxx' }); </script>业务代码中直接window.analytics.track('click')时，TS 并不知道analytics是什么。这时候建一个global.d.ts：
interface AnalyticsInstance { track(event: string, payload?: Record<string, unknown>): void; identify(userId: string): void; } interface Window { analytics: AnalyticsInstance; }注意，interface Window会跟 TypeScript 内置的Window接口自动合并（interface declaration merging），所以不需要declare namespace Window，直接扩展接口内容就行。这是 .d.ts 里最经典的一个技巧：利用“接口合并”来给全局对象加属性。
3.3 场景三：Vue3 + Vite 项目里那些 “找不到模块” 的报错
Vue3 项目用 Vite 做构建，经常碰到这类报错：
Cannot find module './App.vue' or its corresponding type declarations.原因很简单：TS 不认识.vue文件，它不知道这个文件的默认导出是什么类型。这时候 Vite 官方会提供一个env.d.ts：
/// <reference types="vite/client" /> declare module '*.vue' { import type { DefineComponent } from 'vue'; const component: DefineComponent<{}, {}, any>; export default component; }这个声明文件做了两件事：
- 引用
vite/client类型，让 TS 认识import.meta.env以及.svg、.png、.css等静态资源模块。 - 为
*.vue文件声明默认导出，默认导出类型是 Vue 的组件类型。
同理，如果你用了.png图片导入：
import logo from './assets/logo.png';没有声明的话，TS 同样报错。Vite 的vite/client类型已经默认声明了常见静态资源模块，所以一般不用自己写。
这里提醒一个很多新手容易踩的坑：env.d.ts里写了import type { DefineComponent } from 'vue'，这会让文件变成模块，所以它不能再用“全局”的方式声明其他东西。如果你既想用这个 import，又想给Window加全局属性，得拆成两个文件，或者用import()类型。
3.4 场景四：发布 npm 包时，怎么让别人也能有类型提示
自己写个工具库发布到 npm，如果不想让别人一用就报错，就得在包里带上类型声明。通常做法是：
- 源码用 TS 写，编译时同时输出
.d.ts文件。 - 在
package.json里加一个types（或typings）字段，指向入口 .d.ts 文件。
比如 package.json 里这样配：
{ "name": "my-tool", "version": "1.0.0", "main": "dist/index.js", "types": "dist/index.d.ts", "files": ["dist"] }如果你用的是 tsc 编译，可以在 tsconfig.json 里这样配置：
{ "compilerOptions": { "declaration": true, "emitDeclarationOnly": true, "outDir": "dist" } }declaration: true让编译器生成.d.ts文件；emitDeclarationOnly: true只生成声明文件，不生成 JS（如果你用别的工具打包 JS，比如 Rollup、esbuild，就可以只产出类型）。这样发布出去之后，别人import你的包时就能拿到自动生成的类型提示。
这里有个细节：如果源码里用了不少非显式导出的内部类型，生成的 .d.ts 里可能会带着import('./types.internal')这样的引用。最好确保files列表里把这些文件也一起发布出去，否则使用者会报“找不到类型文件”。
4. 工程配置：tsconfig 里跟 .d.ts 相关的高频设置
4.1 declaration、declarationDir、emitDeclarationOnly 怎么配合
很多人项目里明明写了 .d.ts，但发布时发现没生成，或者生成的位置不对，多半是这 3 个配置没搞清楚。
"declaration": true：告诉编译器“你编译 .ts 的时候顺便生成对应的 .d.ts”。这是开关，默认 false。"declarationDir": "dist/types"：指定 .d.ts 输出目录。如果你希望类型文件和 JS 产物放一起，可以省略，默认跟 JS 放同目录。"emitDeclarationOnly": true：只输出 .d.ts，不输出 .js。适合“JS 交给 Babel/Rollup 处理，类型单独生成”的场景。
一个典型配置：
{ "compilerOptions": { "declaration": true, "emitDeclarationOnly": true, "declarationDir": "types", "outDir": "dist", "strict": true } }这样 tsc 把类型声明全部吐到types目录，JS 产物由其他工具负责。如果你用 tsc 同时编译 JS，就别开emitDeclarationOnly，否则目录里只有 .d.ts 没有 .js，运行起来直接崩。
4.2 include、exclude 对声明文件的影响
tsconfig.json 里include和exclude决定 TS 会把哪些文件纳入编译范围。你手写的 .d.ts 文件如果不在include范围内，TS 根本不会读取它。
最常见的目录约定是src和types分开。如果 .d.ts 放在项目根目录的types文件夹，tsconfig 要写成：
{ "include": ["src", "types", "env.d.ts"], "exclude": ["node_modules", "dist"] }另外要注意：exclude并不等于“不编译 node_modules 里的类型”。TS 在解析 import 时，仍然会去node_modules/@types找类型包；如果你希望所有第三方模块都不自动加载某个类型包，可以用types字段来限制（在下一节讲）。
4.3 “types” 和 “typeRoots”：控制自动包含的类型包
默认情况下，TS 会自动把node_modules/@types下所有包都纳入全局类型范围。所以你会发现，项目里明明没有手动import，但node的类型（process、__dirname等）却能用，原因是@types/node被自动加载了。
有时候这种“全自动”会带来问题。比如一个项目既服务于浏览器又跑在 Node 环境，@types/node会给全局注入require、process，导致浏览器端代码误用 Node API。解决方法是给 tsconfig 加types字段：
{ "compilerOptions": { "types": ["node", "vite/client"] } }这样 TS 只会加载列表中指定的类型包，其他 @types 包不会被自动包含。你声明的全局 .d.ts 文件不受这个字段影响，它由 include 控制，所以全局声明文件还是会被正常加载。
typeRoots则是用来指定类型包的查找目录，一般很少动。只有当你把自定义类型包放在非@types目录下时才需要配置。
4.4 moduleResolution 对声明文件查找顺序的影响
TS 解析模块时，会根据moduleResolution的取值走不同策略。简单说，如果你用"moduleResolution": "node"，TS 会按 CommonJS 的解析规则去找模块——先找node_modules下的同名模块，再去找模块里的types字段，最后找index.d.ts。
如果你用"moduleResolution": "bundler"（TS 5.0+ 新增，适配 Vite/webpack 等打包器），解析规则会更激进，对现代 ESM 和exports字段支持更完整。Vue3 + Vite 项目推荐用"module": "ESNext", "moduleResolution": "bundler"，否则导入某些库时可能出现类型找不到的问题。
这里有个经典坑：某个库的 package.json 里配了exports字段，exports里对types条件的指向是./dist/index.d.ts。如果你用moduleResolution: node（旧版经典模式），TS 可能不读exports，导致它还是找不到类型声明。升级到bundler或node16/nodenext模式后，通常就好了。
4.5 checkJs 与 allowJs：用 .d.ts 给纯 JS 项目补类型
如果你的项目目前还是纯 JS，但又想部分享受到类型检查，可以开启allowJs和checkJs。但问题来了：TS 检查 .js 文件时，如果遇到没有 JSDoc 注释的函数，往往会把参数推断成any，检查效果极其有限。
这时候 .d.ts 可以作为“补充声明”存在。比如你有一个legacy.js文件，模块内部逻辑不想改，但希望外部引用的时候能知道类型，就可以写一个legacy.d.ts，跟 JS 文件同名，TS 会自动用 .d.ts 里的声明来替代推断类型。
注意，allowJs: true时，同名.js和.d.ts文件不能同时被当成编译输入，否则 TS 会报重复声明。通常做法是.d.ts放在types目录，或者通过include单独引入，而不是跟 .js 文件放在同一位置。
5. 我踩过的坑：高频报错与排查思路
5.1 “Could not find a declaration file for module 'xxx'” 的完整处理链
这个报错实在太常见了，几乎每个 TS 项目都会碰到。我一般按下面顺序排查：
- 看这个模块本身有没有自带类型。打开 node_modules 里对应包的
package.json，看有没有types或typings字段，或者包根目录有没有.d.ts文件。如果有但 TS 没找到，多半是moduleResolution配置不对。 - 看有没有对应的 @types 包。去 npm 搜
@types/xxx，有就装上。大多数知名库都有社区维护的类型包。 - 如果都没有，就得自己写 .d.ts。最简单的临时方案是建一个
shims.d.ts，写declare module 'xxx';，把这个模块声明成 any。但长期来看，最好写一份稍完整一点的类型声明，别让核心代码裸奔。
举一个实际排查案例。我之前在项目里用了一个老牌的图形处理库，包名叫graphics-tool，npm 上没有 @types。一开始我写：
declare module 'graphics-tool';报错倒是消失了，但后来调用它的 API 时全是 any，IDE 也做不了任何提示。我花了一个下午翻它的源码文档，最后写成了一个比较接近实际 API 的声明：
declare module 'graphics-tool' { export interface CanvasOptions { width: number; height: number; } export function createCanvas(options: CanvasOptions): CanvasRenderingContext2D; export function loadImage(src: string): Promise<HTMLImageElement>; }虽然不完整，但核心函数的类型都有了，后续维护方便得多。所以我的建议是：能写精确就别写 any，临时用 any 是可以的，但应该尽快补齐。
5.2 “无法重新声明块范围变量” 与 全局污染问题
写 .d.ts 时经常遇到这类报错：
Cannot redeclare block-scoped variable 'xxx'.原因通常是你声明了一个全局变量，但这个变量在别的 .d.ts 或 @types 包里已经被声明过了。比如你在global.d.ts里写：
declare const name: string;但这只name很可能在@types/node的全局声明里已经存在，于是冲突。解决方式：
- 把变量收进
declare namespace或interface Window里，避免裸全局声明。 - 检查 tsconfig 的
types字段，限制自动加载的类型包，减少冲突源。 - 如果确实需要全局命名，用唯一且不容易冲突的命名空间前缀，比如
AppName、ProjectName这类。
还有另一种情况：你写了两个 .d.ts，一个声明了interface Window {}，另一个也声明了interface Window {}。在大多数情况下接口合并是正常的，但如果两个声明里的属性有同名但类型不同，TS 就会报错。遇到这种，检查一下是不是引用了不同的旧类型包导致的。
5.3 用typeof import()解决全局声明里引用模块类型
这是 .d.ts 里非常实用的一个技巧。比如你在global.d.ts里想给Window加一个axios属性，而 axios 的类型是模块内部的类型，你不能直接在全局声明里import axios from 'axios'，否则文件就变成模块了。这时候用typeof import()就能绕开：
interface Window { axios: typeof import('axios')['default']; }typeof import('axios')取得是 axios 模块的类型命名空间，['default']取到的是默认导出的类型。这种方式不会引入真正的运行时导入，保持了全局声明文件的“全局脚本”性质，非常推荐。
5.4 手写 .d.ts 与自动生成的 .d.ts 互相覆盖
如果你在项目里既开了declaration: true自动生成声明，又手动写了同名.d.ts，编译时会报重复声明或者产出目录混乱。我的经验是把两者分开：
- 源码里由编译器生成的类型声明，输出到
dist/types或types目录，不要手动维护。 - 手写的全局声明或模块补充声明，统一放在
src/types或者项目根目录的global.d.ts/env.d.ts中，并确保它们不会被declarationDir覆盖。
简单说：自动生成归自动生成，手写归手写，两个目录别互相干扰。
5.5 排查步骤速查表
我把报错和对应的排查方向整理成一张表，方便你快速定位：
| 报错信息 | 可能原因 | 优先排查项 |
|---|---|---|
| Cannot find module 'xxx' or its corresponding type declarations | 模块未安装、类型缺失、moduleResolution 配置不对 | 检查 node_modules、查找 @types、检查 tsconfig moduleResolution |
| Could not find a declaration file for module 'xxx' | 模块无自带类型、也没有 @types | 写 declare module、或用 @ts-ignore 过渡 |
| Cannot redeclare block-scoped variable 'xxx' | 全局变量冲突、@types 包冲突 | 收进 namespace、限制 types 字段 |
找不到类型定义文件，实际文件是.vue/.png等 | TS 不识别非代码模块 | 用 env.d.ts 声明.vue、.png 等 |
模块只有 CommonJS 导出，但用export default声明 | 导出方式不匹配 | 改用 export =、或按包实际导出方式调整 |
types字段配置后全局类型全部消失 | 你限制了自动加载的类型包范围 | 在 types 数组中手动加入需要的包 |
6. 经验谈：.d.ts 文件的维护节奏
最后说点我自己的体会。很多人把 .d.ts 当成“出问题再补的东西”，但我更建议把它纳入日常开发流程：每引入一个新依赖，先检查它有没有自带类型；没有的，顺手补一份最小可用声明，比事后排查一整天强得多。
在团队协作项目中，我一般把 .d.ts 文件分成三类放在不同目录：
src/types/modules/—— 放第三方库的模块补充声明，命名跟包名对齐，比如lodash.d.ts、my-utils.d.ts。src/types/global.d.ts—— 放全局变量、全局接口扩展，比如Window、Document上的自定义属性。src/types/env.d.ts—— 放环境相关声明，比如import.meta.env、静态资源模块声明。
这样分的好处是，新同事接手时一眼就能看出哪些是给 npm 包补类型的、哪些是全局声明、哪些是构建设置。配合 tsconfig 的include把这些目录都包含进去，项目里类型相关的文件就非常有条理。
还有一点想强调：不要在 .d.ts 里写 any 就完事。至少写下参数和返回值的类型。我自己踩过太多“any 一时爽，重构火葬场”的坑，一个函数如果关键参数是 any，那整个类型系统对这个函数的保护约等于零。哪怕只是粗略地写上string、number、Promise<void>，也比 any 强十倍。
关于 .d.ts 的内容大概就是这些。从用途、语法、实战案例到报错排查我也都过了一遍，希望能帮你把这个文件彻底弄明白。它算不上什么高深技术，但确实是 TypeScript 项目里绕不开的基础功，值得花点时间吃透。
