《TypeScript编程入门》附录 C 常用工具、库与资源

本附录目标：把 TypeScript 生态里真正会被反复用到的工具按类别列成表，只讲「它是干什么的」与「什么情况下该选它」，不绑定任何具体版本，也不替你决定技术栈——选型永远取决于团队与场景。

附录 C 常用工具、库与资源

TypeScript 生态的一个特点是：官方只提供编译器和语言服务，其余全部由社区承担。这既是活力所在，也是新手最容易迷路的地方——同一个问题往往有五六种解法。

本附录只列类别与用途，不列具体版本号，也不给出任何外部链接。版本与 API 请以你所用工具自身随包发布的文档为准。表格里的「什么时候选它」是经验判断，不是硬性规则。

编译器与运行时

关键认知：esbuild、swc、bun 只做转译，不做类型检查。它们的速度优势正来自「跳过类型」。所以典型组合是「构建用快工具，类型检查用 tsc --noEmit 单独跑一遍」。

// package.json 中常见的双轨脚本
{
  "scripts": {
    "build": "esbuild src/index.ts --bundle --outdir=dist",
    "typecheck": "tsc --noEmit"
  }
}

打包与构建

选型经验：应用选 vite，库选 tsup 或 rollup，存量项目别轻易迁移 webpack。迁移成本往往远高于收益，除非你确实卡在启动速度上。

本书第 16 章 esbuild/swc/tsup 与打包产物 详细讲了转译与类型检查的分工，以及为什么「构建产物里没有类型」。

类型检查与 lint

重要区分：类型检查（tsc）与 lint 是两件事。tsc 回答「类型对不对」，lint 回答「代码风格与潜在缺陷」。二者不能互相替代，CI 里应各跑一次。开启 strict 之后仍有一批规则（如浮空 Promise、未使用变量）需要 lint 兜底。

严格模式的配置细节见 16.1 编译目标与严格模式配置 。

编辑器与语言服务

编辑器体验的绝大多数问题都出在「编辑器用的 TS 版本与项目不一致」上。先确认版本，再谈配置。语言服务的能力边界（哪些重构能做、哪些不能）由编译器决定，与编辑器无关。

包管理与工作区

Monorepo 的典型难点不是「如何装依赖」，而是「如何只检查/构建受影响的包」。这需要包之间的依赖图，而依赖图的正确性又依赖 tsconfig 的 references 配置。相关做法见 16.3 Monorepo 与 Project References 。

文档与类型来源

一个容易被忽略的事实：@types/* 的版本号与原包不同步。原包升级后 @types 可能仍停留在旧 API，这类不一致往往表现为「运行时正常、类型报错」。遇到时先核对两者版本，再决定是升级 @types 还是自己打补丁。

测试

运行测试验证「行为」，类型测试验证「类型」。发布库时两者都需要：前者防止逻辑回归，后者防止类型回归——类型回归尤其隐蔽，因为它在运行时毫无表现。

类型测试的具体写法见 15.2 类型测试（tsd/expect-type） 。

运行时校验

这一类的存在理由只有一个：类型在运行时被擦除，任何来自网络、文件、localStorage 的数据在类型层面都是「声称」而非「事实」。在系统边界处校验一次，内部就能放心使用静态类型。

Zod 的推导机制见 13.2 Zod 模式验证与类型推导 。

后端框架

三个框架代表三种哲学：fastify 重性能与插件、hono 重可移植与轻量、nestjs 重架构与约定。选型时先问「我的部署环境是什么」，再问「团队需要多少约束」。

ORM 与数据访问

两者的共同点是把数据库表结构变成 TypeScript 类型，让「字段改名漏改一处」这类错误在编译期暴露。差别在于 prisma 把 schema 放在独立文件并用代码生成，drizzle 把 schema 直接写成 TS 代码。

前端

前端的类型收益集中在两处：组件 props 与 API 响应。前者靠框架自身的泛型支持，后者靠前后端共享类型。共享类型的做法见 17.2 前后端共享类型与 API 契约 。

迁移与渐进采用

渐进迁移的顺序建议是：先让编译器参与（allowJs + checkJs），再逐文件加 // @ts-check，最后重命名 .js 为 .ts 并收紧 strict。反过来做（一上来全开 strict）几乎必然失败，因为错误数量会淹没团队。完整方法论见 18.1 JavaScript 项目渐进式迁移 。

学习资源类型

资源按「用途」分四类，比按「形式」分更有用：

使用建议：官方手册当字典查，类型挑战当习题做，社区规范当约束用，开源源码当范本读。四者角色不同，不要拿其中一种替代另一种——尤其是不要只靠碎片化文章学类型系统。

本书也提供了成体系的自学路径：18.3 学习路径与生态选型 。

组合建议

把上面的表拼起来，三条常见技术栈组合如下：

无论选哪条，CI 里都必须有一条独立的 tsc --noEmit。这是整个工具链里唯一不可省略的一环：其他工具都可以替换，只有它真正做类型检查。

把选型拆成三个问题，答案会更清晰：

先回答第一个问题，因为它决定的上限最多；第三个问题最容易引发争论，但通常影响最小。

三个常见反模式

选型阶段有三个反复出现的错误，值得单独列出：

判断某个工具是否值得引入，只需问一句：它替代的那件事，现在真的在疼吗？ 如果答案是否定的，那就是在给未来的自己增加维护面。

一份最小可用的工具清单

如果不想在一开始就做复杂选型，下面这套组合足以支撑绝大多数中小型项目，之后按需替换即可：

• 类型检查：tsc --noEmit，接入 CI，作为唯一的类型真相来源。
• 开发运行：tsx 或 bun，直接执行 .ts 文件，省去构建步骤。
• 构建产物：tsup（库）或 vite（应用），转译快、配置少。
• 测试：vitest，与 TypeScript 的集成开箱即用。
• Lint：typescript-eslint，其中带类型信息的规则能发现普通 lint 找不到的问题。
• 运行时校验：zod，只用在接口边界与配置读取处。

这套组合的共同点是「每一件工具都只负责一件事」，替换其中任意一件都不需要动其他部分。等到某个环节真的成为瓶颈，再针对它做替换，比一开始就搭一套复杂流水线要稳妥得多。

延伸阅读

本站另有几篇偏工程实践的文章，可作为本附录的补充：

• TypeScript CLI 开发 ：把 TS 用于命令行工具时的参数解析与产物组织。
• TypeScript 模块解析与 ESM/CJS 互操作 ：第 8 题与第 9 题的完整背景。
• TypeScript Monorepo 与 Turborepo ：工作区与增量构建的落地细节。
• TypeScript 类型安全测试 ：类型测试在 CI 中的接入方式。
• TypeScript 运行时校验与类型安全 ：校验库的取舍与边界划定。
• TypeScript 与 Node.js 后端 ：后端技术栈的整体组织。
• TypeScript 项目架构与 tsconfig ：配置文件的组织方式。
• TypeScript 构建性能优化 ：编译变慢时先看什么。

小结

• TypeScript 生态只有编译器与语言服务是官方的，其余全部由社区提供，因此「同一问题多种解法」是常态而非异常。
• tsc 负责类型检查，esbuild / swc / bun 负责快速转译，二者职责不同、必须并存，CI 中独立的 tsc --noEmit 不可省略。
• 类型检查与 lint 是两件事，前者管类型正确性，后者管代码风格与潜在缺陷，应各跑一次。
• 运行时校验库（zod 等）存在的唯一理由是「类型在运行时被擦除」，只应在系统边界使用，不必全站铺开。
• 后端框架、ORM、前端框架的选择本质是「团队与部署环境」的选择，没有普适最优解；先确定部署环境，再确定约束强度。
• 学习资源要按用途分工：官方手册当字典、类型挑战当习题、社区规范当约束、开源源码当范本。