项目引用是 TypeScript 3.0 引入的功能，允许将 TypeScript 项目分割成多个子项目。项目引用支持增量编译，提高大型项目的构建速度。
项目引用允许一个 TypeScript 项目引用另一个 TypeScript 项目。被引用的项目会被单独编译，生成声明文件供引用项目使用。
{
"references": [
{ "path": "./shared" },
{ "path": "./app" }
]
}
被引用项目需要设置 composite: true。
{
"compilerOptions": {
"composite": true,
"declaration": true,
"declarationMap": true,
"outDir": "./dist",
"rootDir": "./src"
}
}
composite: true 确保项目可以被引用。
引用项目使用 references 字段。
{
"references": [
{ "path": "../shared" }
],
"compilerOptions": {
"outDir": "./dist",
"rootDir": "./src"
}
}
项目引用有以下优势：
一个典型的项目引用结构：
project/
├── shared/
│ ├── tsconfig.json
│ └── src/
│ └── index.ts
├── app/
│ ├── tsconfig.json
│ └── src/
│ └── index.ts
└── tsconfig.json
根目录的 tsconfig.json 配置所有子项目。
{
"references": [
{ "path": "./shared" },
{ "path": "./app" }
],
"files": []
}
{
"compilerOptions": {
"composite": true,
"declaration": true,
"declarationMap": true,
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src/**/*"]
}
{
"references": [
{ "path": "../shared" }
],
"compilerOptions": {
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src/**/*"]
}
在 app 项目中使用 shared 项目。
import { greet } from "@shared"
console.log(greet("张三"))
需要在 tsconfig.json 中配置路径映射。
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@shared": ["../shared/src"]
}
}
}
项目引用支持增量编译。使用 tsc -b 命令构建项目。
tsc -b
增量编译只编译修改的项目及其依赖。
references 中的 prepend 选项可以将引用项目的输出添加到当前项目的输出中。
{
"references": [
{ "path": "../shared", "prepend": true }
]
}
prepend 适用于需要单一输出文件的场景。
解决方案模式使用一个根 tsconfig.json 管理多个子项目。
{
"files": [],
"references": [
{ "path": "./shared" },
{ "path": "./app" },
{ "path": "./server" }
]
}
IDE 会自动识别解决方案模式，提供更好的开发体验。
一个前后端分离的项目结构。
project/
├── shared/
│ ├── tsconfig.json
│ └── src/
│ └── types.ts
├── frontend/
│ ├── tsconfig.json
│ └── src/
│ └── main.ts
├── backend/
│ ├── tsconfig.json
│ └── src/
│ └── server.ts
└── tsconfig.json
{
"files": [],
"references": [
{ "path": "./shared" },
{ "path": "./frontend" },
{ "path": "./backend" }
]
}
{
"compilerOptions": {
"composite": true,
"declaration": true,
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src/**/*"]
}
{
"references": [
{ "path": "../shared" }
],
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"lib": ["ES2020", "DOM"],
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src/**/*"]
}
{
"references": [
{ "path": "../shared" }
],
"compilerOptions": {
"target": "ES2020",
"module": "CommonJS",
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src/**/*"]
}
项目引用允许将 TypeScript 项目分割成多个子项目。被引用项目需要设置 composite: true。项目引用支持增量编译、代码隔离和并行编译。解决方案模式使用根配置管理多个子项目。项目引用适用于大型项目和前后端分离的项目结构。