TypeScript declaration 怎么生成

在日常开发中，你可能遇到过这样的场景：用JavaScript写了一个工具函数，想分享给其他同事用，对方却找不到函数的类型提示；或者引入第三方库时，编辑器里全是看不懂的类型报错。这时候，TypeScript的声明文件（TypeScript Declaration）就派上用场了——它相当于给JavaScript代码“贴”了一张类型标签，让TypeScript能读懂你的代码，也让其他开发者用你的JS代码时能获得智能提示。

什么是TypeScript声明文件？

简单来说，声明文件就是后缀为.d.ts的文件，里面不写具体的代码逻辑，只描述代码的“样子”：比如某个函数叫什么，接收几个参数，返回什么类型；某个对象有哪些属性，每个属性是什么类型。举个生活化的例子：你开了家奶茶店，菜单（.d.ts）上不会写每杯奶茶怎么煮，只会写“珍珠奶茶：茶底+珍珠，甜度可选”，客人看菜单就知道要点什么，不用知道制作细节。

自己写还是自动生成？

很多人会纠结：声明文件是自己手写还是生成？如果代码很简单，手写声明文件确实快，但一旦代码逻辑变了，手写的声明很容易跟不上，最后出现“声明和实际代码不一致”的bug。比如你写了个function add(a, b) { return a + b }，手写声明可能是declare function add(a: number, b: number): number，但如果后来你改成了支持字符串拼接，手写的声明就错了。这时候，自动生成声明文件就成了更高效、更准确的选择。

怎么用tsconfig.json自动生成？

生成声明文件的核心配置，都在TypeScript的配置文件tsconfig.json里，只要改两个小选项就行。

首先打开你的项目里的tsconfig.json，找到或者添加compilerOptions这个对象，里面加上两个配置：

• "declaration": true：告诉TypeScript编译的时候要生成.d.ts文件；
• "outDir": "./dist"：把生成的.js和.d.ts文件都放到dist文件夹里，避免和原源码混在一起，方便管理。

举个实际操作的例子：你的项目里有个src/utils.js文件，写了一个格式化时间的函数：

`javascript

// src/utils.js

function formatTime(date, pattern) {

const year = date.getFullYear();

const month = String(date.getMonth() + 1).padStart(2, '0');

return ${year}-${month};

}

module.exports = formatTime;

`

你把tsconfig.json配好后，运行tsc命令编译，就会在dist文件夹里生成两个文件：utils.js（编译后的JS）和utils.d.ts（自动生成的声明文件）。打开utils.d.ts，里面的内容是：

`typescript

declare function formatTime(date: Date, pattern: string): string;

export default formatTime;

`

完美对应了你的函数，不用自己手写，省了很多功夫。

注意几个小细节

生成声明文件时，有几个容易踩的坑要留意：

第一，如果你用的是ES模块（import/export），declaration配置同样生效，生成的声明会自动匹配模块语法；

第二，如果你的代码里有私有变量、只在内部用的函数，TypeScript不会把它们的声明写到.d.ts里，只会公开需要给别人用的部分，保证声明的简洁性；

第三，如果你只需要生成声明、不编译JS，也可以用tsc --declaration --emitDeclarationOnly命令，专门生成.d.ts文件，适合纯类型库的项目。

现在你已经掌握了生成TypeScript声明文件的核心方法，下次开发工具库或者公共组件时，不用再纠结手动写声明了，用自动生成的方式，既高效又准确，还能让你的代码更友好，给其他开发者更好的使用体验。