28 | 配置tsconfig.json（3）：工程引用-TypeScript开发实战

当前位置:　首页>> 技术小册>> TypeScript开发实战

28 | 配置`tsconfig.json`（3）：工程引用

在TypeScript项目中，随着项目规模的扩大，代码库的复杂性和维护难度也会显著增加。为了有效地管理这些大型项目，TypeScript提供了一项强大的功能——工程引用（Project References）。通过利用工程引用，我们可以将大型项目拆分成多个较小的、更易于管理的子项目（也称为引用项目或子包）。这些子项目可以独立编译，提高了编译效率，同时也支持增量编译，即只重新编译更改过的部分，进一步提升了开发效率。

一、工程引用的基础概念

工程引用是TypeScript 2.7及以后版本中引入的一个特性，它允许你将一个大型项目拆分成多个tsconfig.json配置文件管理的子项目。每个子项目都可以独立编译，并且它们之间可以相互依赖。当一个子项目被另一个子项目引用时，TypeScript会智能地处理这些依赖关系，确保编译顺序的正确性，并只重新编译受影响的子项目。

二、为什么要使用工程引用

提高编译速度：通过并行编译多个独立的子项目，可以显著减少大型项目的编译时间。
增量编译：仅重新编译修改过的子项目及其依赖项，而不是整个项目。
更好的代码组织：促进代码模块化，使得代码库更加清晰、易于管理。
增强类型检查：TypeScript能够利用工程引用之间的依赖关系，提供更精确的类型检查。

三、如何配置工程引用

1. 创建子项目

首先，你需要在项目中创建多个子目录，每个子目录代表一个子项目。每个子项目都应该有自己的tsconfig.json文件。

my-project/
│
├── packages/
│   ├── lib-a/
│   │   ├── src/
│   │   │   ├── index.ts
│   │   ├── tsconfig.json
│   │
│   ├── lib-b/
│   │   ├── src/
│   │   │   ├── index.ts
│   │   ├── tsconfig.json
│   │
│   └── app/
│       ├── src/
│       │   ├── index.ts
│       ├── tsconfig.json
│
└── tsconfig.base.json

2. 配置`tsconfig.base.json`

为了避免在每个子项目的tsconfig.json中重复配置相同的编译选项，可以创建一个基础配置文件tsconfig.base.json，并在各个子项目的tsconfig.json中通过extends属性继承这些基础配置。

// tsconfig.base.json
{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

3. 配置子项目的`tsconfig.json`

每个子项目的tsconfig.json需要配置为工程引用项目，并指定其输出目录和依赖关系。

// packages/lib-a/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "composite": true, // 启用工程引用
    "declaration": true, // 生成声明文件
    "declarationMap": true // 生成声明文件的映射文件，便于调试
  },
  "include": ["src/**/*"],
  "references": [] // 当前项目无直接依赖，留空
}
// packages/lib-b/tsconfig.json，假设它依赖于lib-a
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "composite": true,
    "declaration": true,
    "declarationMap": true
  },
  "include": ["src/**/*"],
  "references": [
    { "path": "../lib-a" } // 指定对lib-a的依赖
  ]
}
// packages/app/tsconfig.json，假设它依赖于lib-a和lib-b
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "composite": false, // 通常最终应用层不需要设为composite
    "moduleResolution": "node",
    "baseUrl": ".",
    "paths": {
      "*": ["node_modules/*", "packages/*/dist/*"] // 解析模块时查找的路径
    }
  },
  "include": ["src/**/*"],
  "references": [
    { "path": "../lib-a" },
    { "path": "../lib-b" }
  ]
}

注意：在最终的应用层（如packages/app），通常不需要将composite设置为true，因为它不是作为被引用的库存在，而是直接编译成可执行文件或网页的。

4. 编译项目

使用TypeScript的命令行工具tsc，并指定根项目的tsconfig.json（如果有的话）或任意一个子项目的tsconfig.json进行编译。TypeScript会自动识别并处理工程引用关系。

tsc -b packages/app/tsconfig.json

或者使用-b选项不带任何参数，TypeScript会查找当前目录及其子目录下所有配置了工程引用的tsconfig.json文件进行编译。

tsc -b

四、工程引用的高级用法

1. 增量构建与缓存

TypeScript在编译时会利用缓存来加速后续的编译过程。当使用工程引用时，TypeScript会智能地识别哪些子项目被修改过，并仅重新编译这些项目及其依赖项。

2. 依赖管理

通过references字段明确指定子项目之间的依赖关系，使得项目结构更加清晰，也便于团队成员理解和维护。

3. 模块化部署

每个子项目都可以独立编译成npm包或其他格式的分发包，便于在不同项目间复用和共享代码。

五、结语

工程引用是TypeScript为大型项目提供的一项非常有用的特性，它不仅能够提高编译效率，还能帮助开发者更好地组织和管理代码。通过合理配置tsconfig.json，你可以轻松地将大型项目拆分成多个易于管理的子项目，并在它们之间建立清晰的依赖关系。希望本章内容能够帮助你更好地理解和应用TypeScript的工程引用功能，从而提升你的开发效率和项目质量。