TypeScript .d.ts 声明文件完全指南：原理、语法与工程配置

我第一次意识到 .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.tsTS 项目会寸步难行TypeScript 之所以能帮你提前发现 bug靠的是它在上手阶段就建立一个“类型系统”对所有进出的数据做静态检查。可现实是前端项目里大量依赖都是 JavaScript 写的而 JavaScript 本身没有类型TS 编译器默认情况下对没有声明的 JS 模块是什么态度一团黑。举个最常见的场景import _ from lodash; _.chunk([1, 2, 3], 1);如果lodash没有自带类型也没有types/lodashTS 会直接报错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 chunkT(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 requestT any(url: string, options?: RequestInit): PromiseT; 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 typesnode /这表示当前声明文件依赖 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.ts3.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.tsdeclare 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 srchttps://example.com/sdk.js/script script window.analytics new Analytics({ key: xxx }); /script业务代码中直接window.analytics.track(click)时TS 并不知道analytics是什么。这时候建一个global.d.tsinterface AnalyticsInstance { track(event: string, payload?: Recordstring, 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 typesvite/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: nodeTS 会按 CommonJS 的解析规则去找模块——先找node_modules下的同名模块再去找模块里的types字段最后找index.d.ts。如果你用moduleResolution: bundlerTS 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-toolnpm 上没有 types。一开始我写declare module graphics-tool;报错倒是消失了但后来调用它的 API 时全是 anyIDE 也做不了任何提示。我花了一个下午翻它的源码文档最后写成了一个比较接近实际 API 的声明declare module graphics-tool { export interface CanvasOptions { width: number; height: number; } export function createCanvas(options: CanvasOptions): CanvasRenderingContext2D; export function loadImage(src: string): PromiseHTMLImageElement; }虽然不完整但核心函数的类型都有了后续维护方便得多。所以我的建议是能写精确就别写 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 moduleResolutionCould 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、Promisevoid也比 any 强十倍。关于 .d.ts 的内容大概就是这些。从用途、语法、实战案例到报错排查我也都过了一遍希望能帮你把这个文件彻底弄明白。它算不上什么高深技术但确实是 TypeScript 项目里绕不开的基础功值得花点时间吃透。