TypeScript Academy · 课时

TypeScript 项目引用详解

Q: 「TypeScript 项目引用详解」这节课中我会学到什么？

使用 composite 和 references 设置进行多包构建 你通过在浏览器中直接运行的动手代码来练习 TypeScript Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

使用 composite 和 references 设置进行多包构建

TypeScript 项目引用详解 是 CoddyKit 上的免费 TypeScript Academy 课时。这是第 1 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 TypeScript Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 TypeScript Academy 课程共包含 4 节课。

什么是项目引用

项目引用允许您将 TypeScript 代码库拆分为多个 tsconfig 项目，并让这些项目相互声明依赖，从而实现增量且隔离的构建。

// tsconfig.json (root)
{
  "references": [
    { "path": "./packages/core" },
    { "path": "./packages/ui" }
  ]
}

复合项目

每个被引用的项目都必须在其 tsconfig 中设置 "composite": true。这会启用声明缓存和依赖跟踪。

// packages/core/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "outDir": "./dist"
  }
}

使用 tsc --build 构建

请从根目录运行 tsc --build（或 tsc -b），按照依赖顺序构建所有被引用的项目。

# Build all projects
tsc --build

# Build and watch
tsc --build --watch

# Clean build outputs
tsc --build --clean

增量重新构建

首次构建后，tsc --build 只会重新编译源文件或依赖发生变化的项目，从而显著加快大型代码仓库的构建速度。

# Only changed packages are rebuilt
tsc --build
# Output: 2/5 projects up to date — skipping

使用声明文件

被引用的项目通过依赖项目生成的 .d.ts 文件（位于 dist/ 中）使用其依赖，而不是重新解析源 TypeScript 文件。

// packages/ui imports from packages/core
import { Button } from "@myapp/core"; // resolved via dist/index.d.ts

路径配置

请在根目录 tsconfig 中设置 paths，或在 package.json 中使用 exports，以便 TypeScript 在开发期间正确解析包导入。

{
  "compilerOptions": {
    "paths": {
      "@myapp/core": ["./packages/core/src/index.ts"]
    }
  }
}

保持构建顺序

TypeScript 会根据引用关系图自动确定构建顺序。循环引用会被检测出来，并报告为错误。

// Circular reference error example:
// packages/core references packages/ui
// packages/ui references packages/core
// Error: Circular project reference

outDir 与 rootDir

每个复合项目都应配置 outDir 和 rootDir，以控制输出布局，并防止文件跨包边界泄漏。

{
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./dist"
  }
}

与构建工具集成

Turborepo、Nx 和 Lerna 可与项目引用集成，根据依赖关系图缓存并并行执行构建。

// turbo.json — declare TypeScript build as a pipeline step
{
  "pipeline": {
    "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] }
  }
}

监视多个项目

tsc --build --watch 会监视所有被引用的项目，并在每次变更时进行增量重新编译，为单仓库提供近乎即时的反馈。

# Terminal: tsc --build --watch
# [9:00:01 AM] Found 0 errors. Watching for file changes.

回顾：项目引用

项目引用将 TypeScript 拆分为相互隔离且可缓存的构建单元。请设置 composite: true、声明 references，并使用 tsc --build，以便在单仓库中快速、正确地进行增量构建。

快速检查

项目要被另一个项目引用，必须设置哪个 tsconfig 选项？

您学到的内容

TypeScript 项目引用可以在单仓库中实现快速且隔离的构建。请配置 composite: true，通过 references 声明依赖，并使用 tsc --build 进行增量编译。

常见问题解答

「TypeScript 项目引用详解」课时是免费的吗？

是的 — 「TypeScript 项目引用详解」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 TypeScript Academy 课程的其余内容，请升级到 CoddyKit PRO。 TypeScript Academy 课程共包含 4 节课。

「TypeScript 项目引用详解」这节课中我会学到什么？

使用 composite 和 references 设置进行多包构建你通过在浏览器中直接运行的动手代码来练习 TypeScript Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 TypeScript Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 TypeScript Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 1 节课，共 4 节。

「TypeScript 项目引用详解」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 TypeScript Academy 课中编写并运行代码吗？

能。每节 TypeScript Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 TypeScript Academy