在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

microsoft/TypeScript

菜单

构建系统

相关源文件

TypeScript 仓库使用基于 hereby 任务运行器构建的自定义构建系统。本文档将介绍构建 TypeScript 编译器及相关工具的构建架构、关键任务和工作流程。构建系统负责编译 TypeScript 源代码、生成库定义文件、打包输出以及运行测试。

有关持续集成和发布流程的信息，请参阅 CI 和发布工作流程。

概述

TypeScript 构建系统旨在从共享代码库编译和打包多个输出。这些输出包括 TypeScript 编译器（tsc）、语言服务（typescript.js）、语言服务器（tsserver）以及其他支持工具。构建系统在仓库根目录的 Herebyfile.mjs 文件中定义。

主要功能

  • 基于任务的构建系统，支持依赖项排序
  • 支持增量编译
  • 开发模式下的监听模式
  • 使用 esbuild 打包输出
  • 生成库定义文件
  • 生成诊断消息
  • 执行测试和代码覆盖率

架构概述

来源：Herebyfile.mjs45-678 package.json90-102

构建任务和输出

构建系统包含多个任务，这些任务可以单独执行，也可以作为更大任务的一部分执行。主要输出包括：

输出描述任务
tsc命令行 TypeScript 编译器tsc
typescript.jsTypeScript 语言服务库services
tsserver.jsTypeScript 语言服务器tsserver
tsserverlibrary.jsTypeScript 服务器库lssl
.d.ts 文件类型声明文件dts
库文件标准库定义文件generateLibs

主要任务目标

  • local：构建完整的编译器和服务
  • min：仅构建编译器（tsc）和服务器（tsserver）
  • tests：构建测试基础设施
  • lint：在编译器和脚本源文件上运行 ESLint
  • runtests：运行测试套件

来源：Herebyfile.mjs416-427 Herebyfile.mjs429-440 Herebyfile.mjs453-465 Herebyfile.mjs534-551 Herebyfile.mjs666-671

构建管道

来源：Herebyfile.mjs132-137 Herebyfile.mjs64-80 Herebyfile.mjs86-92 Herebyfile.mjs310-413

构建流程详解

TypeScript 仓库采用两步构建流程：

  1. 使用 tsc（TypeScript 自身的编译器）编译 TypeScript 文件
  2. 然后使用 esbuild 对编译后的 JavaScript 进行打包

这种方法允许项目使用 TypeScript 自身的特性来开发自身，同时为分发生成优化的包。

项目结构

TypeScript 源代码被组织成多个项目，每个项目都有自己的 tsconfig.json 文件进行定义。

项目描述
src/compilerTypeScript 编译器核心
src/tsc命令行界面
src/typescript公共 API 和语言服务
src/tsserver用于编辑器集成的语言服务器
src/services语言服务功能
src/typingsInstaller类型定义安装程序
src/watchGuard文件监视实用程序

来源：src/tsconfig.json1-19 src/tsc/tsconfig.json1-10 src/tsserver/tsconfig.json1-14 src/typingsInstaller/tsconfig.json1-4

通用构建配置

所有项目都共享在 src/tsconfig-base.json 中定义的基准配置。

{
    "compilerOptions": {
        "rootDir": ".",
        "outDir": "../built/local",
        "lib": ["es2020"],
        "target": "es2020",
        "module": "NodeNext",
        "moduleResolution": "NodeNext",
        "declaration": true,
        "declarationMap": true,
        "sourceMap": true,
        "composite": true,
        "emitDeclarationOnly": true,
        "isolatedDeclarations": true,
        "strict": true,
        ...
    }
}

来源：src/tsconfig-base.json1-32

任务配置和执行

构建系统定义在 Herebyfile.mjs 中，该文件使用 hereby 任务运行器。任务定义了依赖项，以确保正确的构建顺序。

核心任务

生成库文件

generateLibs 任务将头文件与库定义文件合并，生成最终的库 .d.ts 文件。

来源：Herebyfile.mjs64-80

生成诊断信息

generateDiagnostics 任务将 JSON 中的诊断消息处理成 TypeScript 格式。

来源：Herebyfile.mjs86-92

构建源文件

buildSrc 任务编译 TypeScript 源代码。

来源：Herebyfile.mjs132-137

打包

构建系统使用 esbuild 将 JavaScript 文件打包成最终输出。

来源：Herebyfile.mjs180-293 Herebyfile.mjs310-413

增量构建系统

TypeScript 的构建系统支持增量构建以提高构建性能。BuilderProgram 跟踪

  1. 文件依赖关系
  2. 已更改的文件
  3. 最新状态

对于项目引用，SolutionBuilder 协调跨多个项目的构建。

来源：Herebyfile.mjs128-150

构建命令行选项

构建系统支持各种命令行选项

选项描述
--bundle启用或禁用打包（默认：true）
--typecheck启用或禁用类型检查（默认：true）
--workers测试执行的并行工作进程数
--color/--colors在输出中启用或禁用颜色
--light在 light 模式下运行（较少的验证，但执行速度更快）
--dirty构建前跳过清理输出目录

来源：scripts/build/options.mjs6-58

监视模式

构建系统支持监视模式，该模式监视文件更改并自动重建

监视模式已实现用于源文件（watchSrc）、测试（watchTests）和其他组件。

来源：Herebyfile.mjs139-145 Herebyfile.mjs548-551 Herebyfile.mjs705-747

运行测试

测试系统与构建系统集成。runtests 任务编译测试工具并执行测试

来源：Herebyfile.mjs682-703 scripts/build/tests.mjs34-188

代码格式化和 Linting

构建系统包含代码格式化和 linting 的任务

  • format：使用 dprint 格式化代码库
  • lint：在代码库上运行 ESLint
  • knip：运行 knip 来查找未使用的导出和依赖项

来源：Herebyfile.mjs588-592 Herebyfile.mjs559-586 Herebyfile.mjs600-604

发布流程

脚本produceLKG.mjs 用于创建“上次已知良好”（LKG）构建，该构建存储在lib 目录中。此脚本

  1. 将编译后的工件从built/local 复制到lib
  2. 确保包含所有必需的文件
  3. 保留文件属性

来源：scripts/produceLKG.mjs15-26

结论

TypeScript 的构建系统提供了一种灵活而强大的方式来构建 TypeScript 项目的各种组件。它管理任务之间的依赖关系，支持增量构建，并为测试和代码质量提供工具。该系统旨在易于维护和高效，让开发人员能够专注于改进 TypeScript 语言和工具。