TypeScript 如何做项目引用

刚接触 TypeScript 的开发者，常会在写中型项目时陷入“文件乱成麻”的困境——比如把工具函数全堆在一个 utils.ts 里，想复用却找不到，复制粘贴又容易改出bug。其实用它自带的“项目引用”功能，就能像整理桌面抽屉一样，把不同功能的代码分模块放，还能让它们互相调用，清爽又高效。

什么是项目引用？

简单说，就是把一个大 TypeScript 项目拆成多个“小项目”（专业叫项目配置组），每个小项目有自己的 tsconfig.json 文件。这些小项目不是孤立的，通过配置告诉 TypeScript：“这个模块依赖那个模块，编译时得先编译依赖的部分”。

举个生活化的例子：你做一份生日宴策划，拆成“食材采购”“场地布置”“流程设计”三个小任务。采购完的食材才能布置场地，场地布置好才能顺流程。项目引用就像给这三个任务排了依赖顺序，不用手动按顺序做，工具会自动帮你理顺。

为啥要给项目加引用？

不少人会疑惑：直接把所有文件放一个 tsconfig 里不行吗？小项目勉强可以，但到了几十上百个文件的中型项目，问题会冒出来：比如改了 utils.ts 里的工具函数，TypeScript 要重新编译整个项目，等半天；不同功能的代码混在一起，找 bug 像在乱书堆里找字；团队协作时，每个人改同一个文件容易冲突。

用项目引用就能解决这些：编译时只改当前模块，速度快很多；每个模块职责明确，找功能像找对应抽屉的东西；多人改不同模块，冲突概率大幅降低。

怎么在项目里加引用？

步骤很简单，跟着做就能上手。

首先，把原项目拆成模块。比如做一个电商后台，拆成 shared（公共工具）、admin（管理后台）、client（用户端）三个文件夹，每个文件夹里建自己的 tsconfig.json。

• shared/tsconfig.json 是最基础的，只放公共配置，比如编译输出目录、允许的语法：

`json

{

"compilerOptions": {

"outDir": "./dist",

"rootDir": ".",

"strict": true

}

}

`

• 然后是 admin/tsconfig.json，它依赖 shared，所以要加 references 项告诉 TypeScript：先编译 shared 再编译我：

`json

{

"compilerOptions": {

"outDir": "./dist",

"rootDir": ".",

"strict": true

},

"references": [{ "path": "../shared" }]

}

`

• 最后是根目录的 tsconfig.json，用来统一管理所有模块，把刚才的三个模块列进去：

`json

{

"compilerOptions": {

"composite": true // 这个选项很关键，标记当前项目是能被引用的模块

},

"references": [

{ "path": "./shared" },

{ "path": "./admin" },

{ "path": "./client" }

]

}

`

日常用的小技巧

配置完后，不用手动挨个编译模块，用 tsc --build 命令就行——它会自动按依赖顺序编译，还能只编译修改过的模块，省时间。

另外要注意，引用的模块里导出的内容，得是用 export 公开的，不然别的模块调用时会报错，就像你买的食材没拆包装，没法用来做菜。

其实项目引用的核心，就是把“大项目”拆成“可复用的小单元”，既解决了代码混乱的问题，又能让团队协作更顺畅，是 TypeScript 从入门到做中型项目的必备技能。