TypeScript 项目引用 References

项目引用是 TypeScript 为大型工程提供的一项组织能力，说白了，就是把一个体量较大的 TypeScript 项目拆分成更小、更清晰的模块来管理。

它可以实现增量构建、更好的代码组织和更快的编译速度。

为什么需要项目引用

随着项目增长，单一的 tsconfig.json 会导致编译速度变慢。

项目引用允许将项目拆分为独立的子项目，每个子项目可以独立编译。

这不仅提高了编译速度，还提供了更好的代码组织方式。

概念：项目引用允许一个 TypeScript 项目引用其他项目，实现增量编译和更好的代码组织。

创建引用项目

首先创建被引用的子项目。

packages/utils/tsconfig.json

{
    // 继承基础配置
    "extends": "../../tsconfig.base.json",
    // 编译器选项
    "compilerOptions": {
        // 输出目录
        "outDir": "./dist",
        // 声明文件目录
        "declarationDir": "./dist/types",
        // 生成声明文件
        "declaration": true,
        // 生成 sourcemap
        "sourceMap": true,
        // 是否为库
        "composite": true
    },
    // 包含的文件
    "include": ["src/**/*"],
    // 排除的文件
    "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

composite：设置为 true 启用项目引用功能，这是被引用的项目必须设置的选项。

主项目配置

在主项目的 tsconfig.json 中配置 references。

tsconfig.json (主项目)

{
    // 继承基础配置
    "extends": "./tsconfig.base.json",
    // 编译器选项
    "compilerOptions": {
        // 输出目录
        "outDir": "./dist",
        // 声明文件目录
        "declarationDir": "./dist/types",
        // 生成声明文件
        "declaration": true,
        // 生成 sourcemap
        "sourceMap": true
    },
    // 项目引用配置
    "references": [
        // 引用 utils 项目
        { "path": "./packages/utils" },
        // 引用 ui 项目
        { "path": "./packages/ui" },
        // 引用 types 项目
        { "path": "./packages/types" }
    ],
    // 包含的文件
    "include": ["src/**/*"],
    // 依赖包含的节点模块
    // "files": []
}

references：数组中的每个对象指定一个引用的项目路径，path 相对于当前项目。

类型引用

在代码中使用被引用项目的类型。

src/index.ts

// 导入工具函数（来自 utils 包）
import { formatDate, formatCurrency } from '@my-utils/format';
// 导入组件（来自 ui 包）
import { Button, Modal, Input } from '@my-ui/core';
// 导入类型（来自 types 包）
import { User, ApiResponse } from '@my-types/common';
// 定义用户数据
const user: User = {
    id: 1,
    name: "Alice",
    email: "alice@example.com"
};
// 格式化日期
const dateStr = formatDate(new Date(), "YYYY-MM-DD");
console.log("日期: " + dateStr);
// 格式化货币
const price = formatCurrency(999);
console.log("价格: " + price);
// 创建用户界面
const button = new Button({
    text: "提交",
    variant: "primary"
});
console.log("应用初始化成功");

导入方式：被引用项目的导出可以直接导入，TypeScript 会自动解析类型。

增量构建

项目引用支持增量构建，只编译修改的部分。

构建命令

# 构建整个项目（包括所有引用）
npm run build
# 只构建主项目（不重新构建依赖）
npm run build -- --build
# 清理并重建
npm run clean
npm run build
# 增量构建（推荐）
# 修改某个包后，只重新编译该包和依赖它的包
npx tsc -b packages/utils
npx tsc -b packages/ui
npx tsc -b .

增量构建：使用 -b（build）选项后，TypeScript 会自动判断哪些项目需要重新编译，不必每次都从头来一遍。

注意事项

• composite 选项：被引用的项目必须设置 composite: true
• 输出目录：每个项目需要独立的输出目录
• 声明文件：被引用项目需要生成声明文件
• 构建顺序：依赖的项目需要先构建

最佳实践：将公共代码拆分为独立包，使用项目引用进行管理，提高编译效率。

总结

项目引用是 TypeScript 管理大型项目的核心功能。

• references：配置项目引用关系
• composite：启用项目引用
• 增量构建：只编译修改的部分
• 代码组织：拆分为独立模块

建议：在大型项目中，使用项目引用来组织代码，提高开发效率。