作为一个天天跟 TypeScript 打交道的前端我几乎每次新建项目都会跟.d.ts文件碰面。但说实话这玩意儿在很多人心里一直是个“玄学”好像删了也不影响运行留着又不知道里面写啥面试被问到要么背两句八股文要么直接卡壳。这不行。今天我就把.d.ts文件从原理到实操彻底掰开讲清楚。它不是 TypeScript 的附属品而是整个类型系统的“地基”。无论是你用的 Vue3、Element Plus还是自己写的工具函数库类型推导能丝滑跑起来全靠它在背后撑着。这篇文章适合刚入门 TypeScript 的前端新人也适合写了几年业务代码但对类型声明一知半解的同学。我会从设计思路、手写方法、工程化配置到问题排查一条龙拆完保证你看完能直接在自己的项目里用起来。1. .d.ts 到底是什么从一次“红色报错”说起1.1 最早遇到 .d.ts 的场景先说说我自己最早被.d.ts支配的恐惧。那会儿刚把项目从 JavaScript 迁移到 TypeScript装了个第三方的图表库结果import进来之后满屏红色波浪线报错信息写的是“无法找到模块‘xxx’的声明文件”。我当时第一反应是这不扯吗依赖都装进node_modules了怎么还找不到后来才明白报错的关键不是“模块文件不存在”而是“模块的类型信息不存在”。JavaScript 本身没有类型而 TypeScript 编译器在检查代码时必须要知道每个变量、每个函数参数的类型。对于用 TS 写的包编译时会自动生成类型声明但对于那些纯 JS 的老库或者从 CDN 引的 UMD 包TS 根本无从推断这时候就需要一个.d.ts文件来“补课”。简单来说.d.ts文件就是 TypeScript 世界的“说明书”。它不包含任何实际逻辑只描述“这里有哪些变量、函数、类以及它们的类型长什么样”。它的后缀名里的d就是declaration声明的意思。1.2 .d.ts 与 .ts、.js 的本质区别要理解.d.ts先要分清三个文件类型文件类型扩展名是否执行逻辑是否包含类型主要用途JavaScript.js是否运行时代码TypeScript.ts是是带类型的业务代码类型声明.d.ts否是为 JS 模块或全局变量提供类型描述从编译角度看.d.ts只参与类型检查阶段编译打包后不会生成任何产物。这也是为什么有些项目里你删掉.d.ts文件页面照样能跑——因为运行时根本不需要它但类型检查和 IDE 智能提示会立刻罢工。我经常用一个类比来跟新人解释.ts文件是施工图纸加实际建筑.js文件是纯建筑而.d.ts是房屋的模型沙盘。你不需要沙盘来住人但你要规划布局、确认房间数量时沙盘最直观。1.3 前端工程里 .d.ts 文件放到哪里d.ts文件的位置有讲究。一般分三种情况随包发布每个 npm 包内部会带types字段或index.d.ts文件包安装后会存放在node_modules/包名/下面。全局声明项目的src目录下通常放一个global.d.ts或env.d.tsVue 项目里常见的是src/env.d.ts用来声明.vue文件、图片模块等类型。根目录独立文件像vite-env.d.ts、shims-vue.d.ts这类一般放在项目根目录或src目录由tsconfig.json的include属性控制范围。这里有一个关键认知.d.ts文件的位置决定了它的作用范围。放在src目录下并且被 tsconfig 包含它就会对当前项目的所有文件生效放在node_modules里则是跟随某个包起作用。很多人在项目里写了一个types文件夹新建了index.d.ts却发现不生效大概率就是 tsconfig 的include没覆盖到那个路径。2. 为什么需要 .d.ts类型系统背后的设计逻辑2.1 TypeScript 编译器的“翻译官”机制TypeScript 编译器有两个核心职责一是把 TS 语法转成 JS 语法二是做类型检查。类型检查的过程本质上是建立一个“类型空间”的完整地图。编译器每遇到一个变量、一个函数调用都要去地图上查这个标识符的类型信息。这个地图从哪里来一部分来自源码里显式的类型注解和推导另一部分就来自.d.ts文件。你可以把.d.ts理解成编译器与外部模块之间的“翻译官”JS 里的一切对编译器来说都是“外语”.d.ts负责把它翻译成编译器能理解的“类型母语”。这也是为什么很多用 TS 写的包编译产物里除了.js文件还有一堆.d.ts。它们把源码中的类型信息以纯声明的方式剥离出来既保留类型又不暴露实现细节。设计上非常巧妙——类型安全与代码封装同时满足。2.2 全局类型、模块类型与声明合并.d.ts里有几种常见的作用域组织方式理解了它们你就能看懂任何人都能写任何.d.ts全局声明不包含import/export的.d.ts文件会被视为全局脚本里面的declare声明的变量、接口直接挂到全局命名空间。比如declare const APP_VERSION: string项目里任何文件都能直接用。模块声明文件里只要有export就是模块声明。用declare module xxx可以给某个模块路径声明类型这在给 npm 包补类型时非常常见。声明合并TypeScript 允许同名接口合并允许命名空间跟函数、类合并。比如你想给axios的实例加点自定义属性可以声明一个同名的module扩展或者用declare global把类型注入全局。这里有个常见误解很多人以为.d.ts里所有东西都得用declare包裹。其实对于模块文件declare不是必须的你直接写export interface Foo {}也有效。declare主要用于“描述一个已存在的运行时对象”比如描述全局window上的属性。2.3 对第三方库的适配策略types 与内置类型大多数时候我们不需要自己写.d.ts因为社区已经写好了。这就涉及types机制。TypeScript 默认会扫描node_modules/types目录下的所有包自动加载类型。比如你要用lodash装一个types/lodash就能获得完整的类型提示。为什么lodash自身不携带类型而要单独装types因为lodash是很早以前的 JS 项目作者没空维护类型社区就通过 DefinitelyTyped 仓库统一维护。这是一种“类型与实现分离”的策略好处是类型更新不需要发版主包坏处是偶尔会出现types版本跟主包版本不匹配的情况。再说内置类型。TypeScript 自带一套标准库声明比如lib.dom.d.ts、lib.es2020.d.ts它们定义了document、window、Promise等运行时 API 的类型。这些内置.d.ts在安装 TypeScript 时就一并被放进了安装目录你写代码时压根没察觉它的存在但它确确实实参与了每一次类型检查。所以严格来说每个 TS 项目背后都有一堆自动加载的.d.ts文件不只是那些手写的。3. 手把手写出可用的 .d.ts 文件3.1 核心语法declare、export、namespace 怎么用写.d.ts之前先把核心语法过一遍。这些语法不是.d.ts专属但在.d.ts里用法最集中declare声明一个全局存在的东西。后面可以跟var、function、class、enum、namespace、module、type等。export把类型导出供其他模块import。.d.ts里也可以写export default。namespace组织一批相关声明避免全局污染。在老代码里经常看到declare namespace Foo {}现在更多被 ES module 替代但旧库声明里还是经常见。interface与type定义对象结构和类型别名这是.d.ts里的主力军。declare module 模块名为没有类型的三方模块声明一个模块类型。一个典型的手写.d.ts长这样// src/types/my-lib.d.ts declare module my-lib { export interface Config { name: string retries?: number } export function init(config: Config): void const version: string export default version }注意几点模块名必须跟导入路径完全一致如果模块有默认导出需要export default声明如果没有默认导出用export function或export const就够了。3.2 场景一为纯 JS 模块补类型这是最常见也最实际的需求。公司老项目里有一个用 JS 写的内部工具库没有类型定义大家import进来全是any。这时候手动补一个.d.ts文件是最划算的方案。比如utils/format.js里暴露了三个方法我一般这样写// src/types/format.d.ts declare module /utils/format { export function formatDate(date: Date | string | number, pattern?: string): string export function formatNumber(num: number, digits?: number): string export function parseQuery(url?: string): Recordstring, string }注意这里的路径/utils/format必须和你真正 import 时的解析路径一致。如果项目里用了别名d.ts里的模块名也得跟着解析到同一条路径否则类型不会生效。这是很多新人踩坑的地方。实测下来与其一次写完不如先给高频使用的那几个函数补类型用到哪个补哪个。因为手写.d.ts本质上是“逐步完善”的过程一次追求完美容易被公司里那些奇奇怪怪的 JS 老代码劝退。3.3 场景二为图片、CSS 等静态资源声明模块Vue 项目里经常会遇到这个报错Cannot find module ./logo.png。原因很简单TS 默认只认识.ts、.js、.d.ts这类文件图片、CSS、SVG 对编译器来说是“未知文件格式”。解决办法就是创建一个env.d.ts把常见静态资源全部声明成模块declare module *.png declare module *.jpg declare module *.jpeg declare module *.gif declare module *.svg declare module *.css declare module *.less declare module *.scss declare module *.vue { import type { DefineComponent } from vue const component: DefineComponent{}, {}, any export default component }这里的declare module *.vue很重要Vue3 项目里如果没有这句.vue文件里的 template 一律没法获得类型提示。官方脚手架默认生成env.d.ts时已经写好了/// reference typesvite/client /这句话会引用 Vite 的客户端类型声明其中就包括静态资源模块。如果你用其他构建工具或自定义配置最好自己把资源模块声明补上。3.4 场景三扩展第三方库类型以 Vue3 Element Plus 为例实际开发中我们经常要给第三方库“加料”。比如 Element Plus 的ElMessage默认只有success、warning、error、info四种方法但我想加一个loading方法并统一返回类型又或者我想给AxiosInstance扩展一个requestId属性。这时候要用“声明合并”或“模块扩充”。拿 Axios 举例// src/types/axios.d.ts import axios declare module axios { export interface AxiosRequestConfig { showLoading?: boolean skipErrorHandler?: boolean } }只要在项目里某处import axios过然后对这个模块做扩充所有使用 axios 的地方都会自动带上新增的配置项。这个模式我在中后台项目里经常用配合拦截器能省很多重复代码。再说回 Element Plus。很多人不知道自定义全局组件类型的方式// src/types/element-plus.d.ts import type { ElMessage } from element-plus declare module vue/runtime-core { export interface GlobalComponents { // 给全局注册的组件补类型 AppHeader: typeof import(./components/AppHeader.vue)[default] AppFooter: typeof import(./components/AppFooter.vue)[default] } export interface ComponentCustomProperties { $message: typeof ElMessage } }这个做法利用了 Vue3 提供的vue/runtime-core模块扩充点。声明了GlobalComponents后模板里的AppHeader组件就能获得完整的 props 类型推断而this.$message也有了对应类型。需要提醒的是declare module扩充第三方模块时d.ts文件里必须要有至少一个顶层import或export否则会被当作全局脚本处理扩充逻辑不会生效。这个坑我踩过不止一次排错时可以先检查这一点。4. 工程化落地从生成到发布全流程4.1 自动生成tsc --declaration 的正确打开方式手写.d.ts是给老库补课的方案。如果你自己写的就是 TypeScript 库更推荐让编译器自动生成声明文件。方式特别简单编译时加一个--declaration参数或者在 tsconfig 里设置{ compilerOptions: { declaration: true, emitDeclarationOnly: true, outDir: dist/types } }注意emitDeclarationOnly这个选项它在declaration: true基础上更进一步只输出.d.ts文件不输出.js。如果你想构建一个纯类型包或者想确认一下当前项目的类型“面”长什么样这是个极佳的方式。就拿我最近一个工具函数库举例源码写在src/下配置好之后运行tsc几个utils函数的类型声明会全部落到dist/types结构跟源代码一一对应。拿到这些自动生成的.d.ts我一般会快速扫一眼导出的类型是否符合预期再手动补一些publicAPI 的 JSDoc 注释因为这些注释最终会出现在 IDE 的悬浮提示里。4.2 package.json 中的 types 字段搭建 npm 包时package.json除了常用的main、module、exports字段还要加一个types字段老项目里也可能写作typings。它的作用就是告诉 TypeScript我这个包的类型声明文件入口在哪。{ name: my-utils, main: dist/index.js, module: dist/index.js, types: dist/types/index.d.ts, exports: { .: { types: ./dist/types/index.d.ts, import: ./dist/index.js, require: ./dist/index.js } } }如果你设置了exports字段最好把types子条件放到最前面。因为 TS 解析类型时用的是条件导出的第一个匹配项顺序不对可能导致类型加载不出来。再补充一个建议发布前在本地跑一下npm pack然后解压产物看看dist目录里是不是真的包含了.d.ts文件。因为npm publish默认会忽略部分文件如果你忘了配files字段很可能发布到 npm 上的包根本没带上类型文件。4.3 配置项解析include、exclude、typeRoots 与 types工程上最容易出错的就是 tsconfig 配置。四个关键配置要拎清include决定哪些文件参与编译和类型检查。手写的.d.ts文件必须在 include 范围内。exclude排除文件一般把node_modules、dist、public排除掉。typeRoots指定类型声明的加载目录默认是node_modules/types。types只加载指定列表中的types包。例如types: [vite/client, element-plus/global]表示只加载这两个声明包其他types全部忽略。一个容易忽略的点typeRoots在 Vue3 Vite 项目里经常有人误配。Vite 的客户端类型是通过types字段加载的比如types: [vite/client]如果你在typeRoots里改动了默认值但types没写好就会出现import.meta.env没有类型提示的情况。实际项目里我的推荐配置是这样{ compilerOptions: { typeRoots: [./node_modules/types, ./src/types], types: [vite/client, element-plus/global] }, include: [src/**/*.ts, src/**/*.d.ts, src/**/*.tsx, src/**/*.vue, vite.config.ts] }把src/types加进typeRoots自定义的全局声明就能被自动扫描到不需要每个文件都手动/// reference引用。这个技巧能省不少事。4.4 常见加载冲突与路径别名问题.d.ts生效不了十有八九是“路径对不上”或“作用域不对”。我总结了两类高频问题第一模块路径别名解析不一致。比如写declare module utils/format但项目里的实际导入是相对路径../../utils/format。类型系统不会自动把这两个看成同一个模块。解决办法是统一用别名并且保证tsconfig.json里paths配置与.d.ts里的模块名完全一致。或者干脆用相对路径写模块名但可读性会差一些。第二全局声明和模块声明互相污染。当一个.d.ts文件里既有declare module又有declare global作用域范围容易混乱。我的经验是全局声明单独放一个文件模块扩充单独放一个文件避免杂糅。还有一个小细节某些构建工具比如 Webpack 的resolve.alias和你tsconfig paths的路径写法可能不一样。像 Vite 里用别名tsconfig 里映射到./src/*但 Vite 配置里需要重新定义一次。如果两边有任何一个不匹配编辑器里类型可能正常但打包时就报模块找不到反之亦然。5. 常见问题与排查技巧实录5.1 高频报错整理开发中反复出现的.d.ts相关报错我整理成了一张速查表报错信息可能原因解决方案Cannot find module xxx or its type declarations.模块路径没有对应.d.ts或types字段没指向正确入口给该模块补declare module xxx或安装对应的types/xxxCannot find type definition file for xxxtypeRoots配置了自定义路径但里面没有这个包检查types列表是否包含包名或把包装到node_modules/types下Property xxx does not exist on type Window给 window 扩充属性的声明缺失新建global.d.ts用declare global { interface Window { xxx: string } }Module xxx has no default export.第三方库没有默认导出声明但业务代码用import xx from xxx在.d.ts里补export default或业务代码改成import * as xx from xxxDuplicate identifier xxx全局声明重复同名接口或变量冲突检查是否在不同.d.ts里重复声明了同一个全局变量改用interface合并或type别名5.2 排查思路从编辑器到命令行的一整套方法遇到类型上报错别急着去编辑器里瞎改。我一般按这个流程排查第一步看编辑器右下角 TypeScript 版本。VSCode 默认用内置 TS 版本但项目可能装了不同版本的 TS。如果版本不一致类型解析结果会有差异。建议在项目里装一份 TypeScript然后tsconfig.json里指定类型检查方式。第二步确认.d.ts文件是否在作用域内。打开 tsconfig人工检查include和typeRoots。一条条核实别凭记忆。尤其项目里有多个层级目录时很容易漏。第三步用命令行跑一次类型检查。不是npm run dev而是直接跑npx tsc --noEmit。这个命令不生成网页只做类型检查能把所有类型错误一次性列出来。编辑器里的波浪线可能有缓存命令行最准确。第四步如果错误只出现在 IDE 里命令行是好的那大概率是 VSCode 的 TS server 缓存问题。按Cmd Shift P输入 “TypeScript: Restart TS Server”重启一下基本能解决。我强烈建议项目里配置一个typecheck脚本{ scripts: { typecheck: tsc --noEmit } }每次 CI 集成或提交前跑一下比单纯依赖编辑器靠谱得多。5.3 设计 .d.ts 时容易踩的坑写.d.ts本身的坑也不少我按踩坑频率排个序第一个坑把所有东西都声明成any。有个同事图省事给整个第三方库declare module temp-lib然后啥也不写导出的东西全是any。这确实解决了“红色波浪线”但等于是把类型检查关掉了后续重构时编译器帮不上任何忙。我的建议是至少把高频 API 的类型补出来低频的部分用[key: string]: any兜底保持类型安全的同时逐步完善。第二个坑用了declare module xxx但没写export或export default。这种声明在部分场景下编译器不认导致导入时依然报“没有默认导出”。核心原因是模块解析时认为这个模块是{}空对象。务必确认你声明的模块至少导出了点什么。第三个坑路径大小写不一致。Windows 上文件系统不区分大小写但 TypeScript 的模块解析默认区分。在 Linux 或 CI 环境就会炸。.d.ts里的模块路径大小写必须和业务代码里的 import 完全一致这一点在跨平台开发时尤其重要。第四个坑全局变量命名冲突。如果你在global.d.ts里declare const appName: string但业务代码里恰好有一个同名的局部变量会出现Cannot redeclare block-scoped variable之类的报错。解决办法是给全局声明加上独特的命名空间前缀或者干脆不声明全局变量改用import导出。我在实际项目里处理这些坑的思路是能不用全局声明就不用能用模块导出就不用declare namespace。全局命名空间看着方便但项目一大合并冲突和命名污染是早晚的事。5.4 我的一个小技巧给业务代码里的 window 扩充属性这个需求太常见了总有人问。比如微前端架构里主应用往 window 上挂一个全局的microAppInfo子应用里要读取并拿到类型提示。写法如下// src/types/window.d.ts export {} declare global { interface Window { microAppInfo?: { name: string baseUrl: string token?: string } } }注意到第一行的export {}没有这个空导出很关键它让整个文件变成模块后续的declare global才能把类型“塞”进全局。如果没有这行interface Window会被当成局部接口而不是扩充全局 Window。这是我建议所有写.d.ts的人记住的“模块上下文”和“全局上下文”的区别是理解.d.ts的一把钥匙。写在最后从最早手写shims-vue.d.ts只为了消掉红波浪线到现在能清楚地知道类型声明在编译器里怎么流转这个过程我走了挺久。回头看.d.ts最大的价值不在于“消除报错”而在于让 JavaScript 生态里那些没有类型的存量代码也能慢慢长出类型。对前端团队来说给老项目补.d.ts的过程其实也是一次代码梳理和接口盘点。比如你把utils里的函数都声明清楚相当于把项目的“公共 API”显式化了一次很多隐式的参数约定、返回值约定都能暴露出来。我个人在实操中一直坚持一个原则类型声明文件和业务代码一样需要 review。any泛滥的.d.ts比没有.d.ts更危险因为它制造了一种“类型安全”的假象让后来的人放松警惕。所以真想用好它别怕多花几分钟把类型写精确哪怕慢一点后面接到这个模块的人会由衷感谢你。最后分享一个小技巧每年把项目里所有.d.ts文件 grep 一遍看到any就顺手排查它出现的理由。有些是历史遗留有些是图省事但每一次清理都能让项目的类型体系更牢固一点。这部分投入在短期看是“不产出功能”但长期来看它换来的是重构时的底气。
