TypeScript 如何做路径映射

平时写代码时，会不会总遇到这种糟心情况：明明项目里有个公共工具函数，可每次要引用它，都得写一串长长的相对路径，比如 ../../../../utils/dateFormat，层级多了，要么数错 ../ 少写漏写，要么路径改了就得全项目搜替换，特别影响效率。其实只要用好 TypeScript 的「路径映射」，就能把这种麻烦彻底解决，像引用本地模块一样简单。

什么是路径映射？

路径映射说白了就是给项目里的常用文件夹起「别名」，代替那串让人头大的相对路径。举个生活化的例子：你家小区里有个快递柜，平时找快递得从单元门出发，走50米到楼下，再拐3个弯才到；给快递柜起个别名「小区快递柜」，不管你在小区哪个地方，直接说「去小区快递柜」就行，不用记复杂路线。TypeScript 的路径映射就是干这个的，把 ../../utils 这种复杂路径，换成一个好记的别名，写代码时直接用别名就行。

怎么快速配置路径映射？

配置特别简单，只要改项目里的 tsconfig.json 文件就行。打开这个文件，找到 compilerOptions 这一项，在里面加两个核心配置：

• 先写 baseUrl：相当于给项目定个「根目录」，所有别名都从这个根目录找文件；一般设成 . 就好，代表项目根文件夹。
• 再写 paths：这里就是给文件夹起别名的地方，格式是「别名: [实际路径]」，比如要把 src/utils 设成别名 @utils，就写 "@utils/*": ["src/utils/*"]，这里的 /* 代表这个文件夹里的所有文件。

举个具体的配置例子：

`json

{

"compilerOptions": {

"baseUrl": ".",

"paths": {

"@utils/*": ["src/utils/*"],

"@components/*": ["src/components/*"]

}

}

}

`

是不是特别好懂？就像给家里常用的东西贴个小标签，不用每次翻抽屉找。

配置后怎么用？

配置完了，写代码时直接用别名就行。比如之前要引用 src/utils/dateFormat.js，得写 import dateFormat from '../../../../utils/dateFormat'；现在直接写 import dateFormat from '@utils/dateFormat' 就可以，少了一堆 ../，还不怕路径写错。

不过要注意，刚才的 /* 不能忘，要是写 @utils: ["src/utils"]，只能引用这个文件夹里的主文件，没法引用里面的子文件，比如 @utils/format/time 就会报错，加上 /* 才能匹配所有子文件，这个细节一定要记牢。

遇到问题怎么排查？

有时候配置完用别名还是报错，别慌，大部分是小问题：

• 先检查 baseUrl 是不是设对了，如果项目根目录是 src 文件夹，那 baseUrl 就设成 src，不然别名会找不到实际路径；
• 再看 paths 里的路径是不是和实际文件夹名对应，比如实际文件夹叫 utils，别写成 util 少了个 s；
• 最后要注意，路径映射是 TypeScript 的配置，要是用打包工具（比如 Webpack、Vite），还得给打包工具也配对应的别名，不然打包时会找不到文件，比如 Vite 里要在 vite.config.ts 里也加 resolve.alias 对应 TypeScript 的别名，两边要保持一致才行。

有了路径映射，项目里的引用路径变得清晰好记，不管项目多大，找公共工具、组件都特别省心，再也不用为复杂路径头疼了。