TypeScript 如何配置声明文件

刚接触TypeScript的开发者，多半都踩过“认不出第三方JS库”的坑——比如用一个很火的日期处理库，写代码时IDE明明没提示，但一编译就报“找不到模块‘xxx’或其相应的类型声明”。这其实就是没搞懂声明文件的配置，今天就用生活化的例子讲明白，TypeScript到底怎么配置声明文件。

什么是声明文件？先打个比方

把TypeScript比作懂规则的外卖骑手，它要准确知道“送什么餐、送到哪、餐的温度范围”才能顺利干活；而第三方JS库（比如刚才说的日期库）就像没有标注清楚的外卖——只写了“一份餐”，没写是“热粥还是沙拉”，骑手（TypeScript）自然不知道怎么处理。

声明文件就是给这些“无标注外卖”写的说明卡，上面写清楚：这个第三方库有哪些函数、参数要传什么类型、返回什么结果，让TypeScript能顺利“接单配送”。它的后缀一般是.d.ts，核心作用就是给JS库补类型信息，不需要改动原来的JS代码。

最基础的配置：自动识别的简单情况

如果用的是npm上的热门库，那配置起来几乎不用手动写代码——大部分热门库都会自带声明文件，或者有专门的社区维护声明包。举个例子，你想在项目里用lodash（一个常用的数组工具库），只要两步：

正常安装库：`npm install lodash`

• 安装对应的声明包：npm install @types/lodash --save-dev

这时候你打开TypeScript配置文件（tsconfig.json），完全不用额外写配置，直接写代码就能用lodash了。比如你写_.chunk([1,2,3],2)，IDE会自动提示参数、返回的是number[][]类型，再也不会报错。

这里要注意：@types/开头的包，是 DefinitelyTyped 社区维护的第三方声明库，相当于官方的“类型说明书合集”，大部分常用库都能在这里找到，不用自己瞎写。

需要手动配置的两种场景

要是遇到冷门库，或者自己写的JS工具，找不到现成的声明文件，就得手动配置了，分两种情况：

第一种情况：把声明文件直接放在项目里。比如你有个自己写的JS文件utils.js，里面有个计算总价的函数calcTotal(price, count)，你想给它加声明，只要在同一个文件夹里建个utils.d.ts，内容写：

`typescript

export function calcTotal(price: number, count: number): number;

`

这时候TypeScript会自动识别这个声明文件，不用改其他配置，直接导入就能用。

第二种情况：声明文件不在默认位置，需要手动告诉TypeScript在哪。比如你把所有声明文件都放在项目的types文件夹里，这时候要改tsconfig.json的typeRoots和types字段：

`json

{

"compilerOptions": {

// 告诉TypeScript，声明文件都在types文件夹里

"typeRoots": ["./types"],

// 自动加载types文件夹里的所有声明包

"types": []

}

}

`

举个生活化的例子：这就像你把所有外卖说明卡都放在玄关的小抽屉里，TypeScript默认会去餐厅找，你得告诉它“以后先去玄关抽屉找说明卡”，这样就能顺利拿到需要的信息了。

新手最容易踩的坑

最后说两个新手常犯的错：一是把声明文件写成.ts后缀，其实声明文件必须是.d.ts，否则TypeScript会把它当成普通的TypeScript代码，解析时会出错；二是乱删@types/包，要是用了热门库，别随便删，不然IDE会失去类型提示，代码写起来全靠猜。

其实配置声明文件的核心逻辑，就是“给TypeScript补全它看不懂的代码类型信息”，不管是用现成的社区包，还是自己写说明卡，都是为了让TypeScript能准确理解代码，减少运行时的错误。只要掌握了这几种配置方式，再遇到“找不到类型声明”的报错，就不会慌了。