第16章：构建与工具链 —— tsc、Babel、Watch 与多环境集成

第16章：构建与工具链 —— tsc、Babel、Watch 与多环境集成

TypeScript 工具链经常由多个工具共同完成：tsc 检查和生成声明，Babel/SWC/esbuild 转译，bundler 解析依赖并打包，测试工具执行代码。本章明确每个工具的职责。

一、tsc 的三种常见角色

检查并输出

npx tsc

只检查

npx tsc --noEmit

构建项目引用图

npx tsc --build

CLI 选项可以临时覆盖配置，但团队项目应把稳定设置写入 tsconfig.json。

二、报错时是否输出

TypeScript 历史上可在存在类型错误时仍输出 JavaScript。需要阻止错误构建产物时设置：

{
  "compilerOptions": {
    "noEmitOnError": true
  }
}

若构建工具负责输出，则 CI 应单独运行 tsc --noEmit 并以退出码阻断发布。

三、Babel 与 tsc

Babel 可以移除类型语法并执行语法降级，但通常不完成 TypeScript 的完整类型检查，也不一定生成 .d.ts。

推荐分工：

Babel/SWC/esbuild：快速转译
TypeScript：类型检查
TypeScript：库声明文件生成

不要看到 Babel 能处理 .ts 就删除类型检查步骤。

四、Bundler 的职责

Webpack、Rollup、Vite 等通常负责：

• 解析依赖图。
• 处理资源。
• Tree Shaking。
• 代码分割。
• 开发服务器和热更新。
• 生成浏览器或服务端 bundle。

它们对模块解析的支持可能不同，因此 TypeScript 应使用与 bundler 相符的解析模式，别名也要同步配置。

五、Watch 模式

npx tsc --watch --noEmit

大型项目的文件监听可能受操作系统能力、网络盘和目录规模影响。可以通过 watchOptions 调整策略，但应先确认症状：CPU 过高、漏更新、文件句柄不足还是网络文件系统不支持事件。

{
  "watchOptions": {
    "watchFile": "useFsEvents",
    "watchDirectory": "useFsEvents"
  }
}

六、构建工具集成

官方资料还覆盖 Babel、Browserify、Grunt、Gulp、Rollup、Svelte、MSBuild 等。现代项目不必逐个掌握旧工具，但应提炼共同模型：

谁读取 TypeScript？
谁做类型检查？
谁决定模块解析？
谁做语法降级？
谁生成声明？
谁打包与压缩？
谁执行测试？

只要这些职责有空缺或重叠不一致，就会出现构建问题。

七、Node、浏览器与 ASP.NET Core

Node

需要匹配 Node 模块格式、版本和运行方式。

浏览器

需要处理模块 URL、bundle、polyfill 和目标浏览器语法支持。

ASP.NET Core / MSBuild

TypeScript 可通过项目文件或 tsconfig 集成到 .NET 构建中。即使不使用该技术栈，也应理解：企业宿主可能有自己的构建生命周期，避免同时让 MSBuild 和 npm 脚本重复编译同一份代码。

八、target 与运行环境

target 控制输出语法降级，不自动提供缺失的运行时 API。例如把代码降级到旧语法，不会自动为 Promise、Map、fetch 添加 polyfill。

• target：输出语法。
• lib：编译器假定可用的 API 类型。
• Polyfill：运行时实现。

三者必须分别考虑。

九、source map 与调试

{
  "compilerOptions": {
    "sourceMap": true,
    "inlineSources": true
  }
}

Source Map 让调试器从输出 JavaScript 映射回 TypeScript。发布到生产环境时应评估源码泄露风险和错误监控需求。

十、声明与 source map

库可生成：

{
  "compilerOptions": {
    "declaration": true,
    "declarationMap": true
  }
}

声明映射改善编辑器跳转到源码的体验，但发布包必须包含对应源文件或正确映射路径。

十一、每日构建版本

TypeScript Nightly 可提前验证新修复和特性，但不应无控制地进入生产：

• 锁定明确版本。
• 在独立 CI 任务验证。
• 记录是为了验证哪项修复。
• 正式版发布后回归稳定通道。

十二、构建性能观察

npx tsc --extendedDiagnostics
npx tsc --generateTrace trace-output

关注：

• 文件数量。
• 类型数量和实例化次数。
• 解析、绑定、检查耗时。
• I/O 与监听开销。
• 声明生成成本。

工具链优化必须先确认瓶颈属于 TypeScript、bundler、测试还是文件系统。

十三、常见误区

1. Babel 能编译 .ts 就认为完成类型检查。
2. target 较低就认为自动获得 polyfill。
3. 多个工具重复转译，输出规则不一致。
4. Watch 异常时直接切换轮询，导致 CPU 激增。
5. 构建和 CI 使用不同 TypeScript 版本。
6. 应用配置直接复制给库发布。
7. Source Map 发布策略没有安全评估。
8. 旧工具教程中的配置未经核对直接用于现代项目。

十四、练习

1. 建立“bundler 转译 + tsc 检查”的双流程。
2. 故意制造类型错误，确认构建是否仍输出。
3. 对比 target 改变后的 JavaScript，并检查缺失 API 是否需要 polyfill。
4. 运行 --extendedDiagnostics 记录基线。
5. 列出当前项目每个工具的明确职责。

十五、总结

1. tsc 可以检查、输出和构建引用图。
2. Babel、SWC、esbuild 等转译工具不能默认替代类型检查。
3. Bundler 决定依赖图和运行产物，TypeScript 配置应模拟它的解析方式。
4. target、lib 与 polyfill 是三件事。
5. 工具链优化先定位责任和瓶颈，再调整配置。

请继续阅读：第17章：版本演进。

原始资料引用

• tsc CLI Options
• Configuring Watch
• Using Babel with TypeScript
• Integrating with Build Tools
• ASP.NET Core
• Compiler Options in MSBuild
• Nightly Builds

Related Documents

• 第15章：浏览器开发
• 第17章：版本演进