TypeScript 实战指南：类型系统、泛型与工程配置
TypeScript 是 JavaScript 的静态类型超集：它在代码运行之前做静态类型检查，把"用错了值类型"这类最常见错误提前拦截。经过多年发展，TypeScript 已成为现代前端工程的事实标配——React、Vue、Next.js 等生态的默认脚手架都内置了对它的支持。
TypeScript 是前端搭建分类下的基础语言能力。更完整的工程化视角可参考前端工具链 2026；若在 React 或 Vue 中落地，可结合React 19 实战指南或Vue 3 组合式 API 指南阅读。
一、为什么需要类型
JavaScript 规模增长后，"函数应返回什么、对象有哪些字段"完全依赖运行时报错才能发现。类型系统的价值不在于消灭所有错误，而在于把错误出现的时机从"上线后"提前到"编辑时"。编辑器里的红色波浪线、Ctrl+点击跳转到定义、重构时跨文件的引用同步，都是类型信息带来的红利。它并不改变运行时代码，编译后仍输出标准 JavaScript——也就是说，类型是纯开发期资产，写得好不好直接决定你的开发体验。这也是为什么"先写类型、再写实现"在很多团队成了约定俗成的流程。
二、基础类型与类型收窄
除 string、number、boolean 等基础类型外，常用组合有：数组 T[]、元组 [string, number]、联合类型 A | B、可选字段 ?、字面量类型 "success" 等。typeof/in/instanceof 判断配合类型守卫，可以在运行时把宽类型收窄成具体类型，这是写健壮代码的关键技巧。
举个例子，一个函数要处理"要么是字符串、要么是带 data 字段的对象"的入参：
type Response =
| { status: "error"; message: string }
| { status: "ok"; data: User }
function handle(res: Response) {
if (res.status === "error") {
// 这里 TS 自动收窄：res 只有 message
console.error(res.message)
} else {
// 这里 res 只有 data，类型是 User
res.data.id
}
}
判等收窄（discriminated union）是最常用的手法：用 status 这样的判别字段把联合类型拆开，分支里 TypeScript 会自动推导出对应的剩余字段，写完基本不会出"空指针"式的低级错误。
三、泛型：可复用的类型组件
泛型让"函数/接口/类"能作用于多种类型而不丢失类型信息。以恒等函数为例：
function identity<Type>(arg: Type): Type {
return arg
}
let output = identity<string>("hello")
约束（extends）限定类型参数的形状：
interface Lengthwise {
length: number
}
function logLength<Type extends Lengthwise>(arg: Type): Type {
console.log(arg.length)
return arg
}
配合 keyof、条件类型与映射类型，可以用极少的样板表达"对象的键到值的映射"等复杂关系。实际工作中最常用到的泛型场景是给接口封装一个统一的请求函数：fetchList<T>(url): Promise<T[]>，调用时传 fetchList<User>("/api/users")，返回值就自动带上了 User[] 的类型，后端接口一变更，前端立刻在编译期知道哪里要改。
四、工程配置：tsconfig.json
合理的 tsconfig.json 让类型检查真正生效。推荐开启的关键项：
| 选项 | 作用 |
|---|---|
strict |
开启全部严格检查，团队建议默认打开 |
target / module |
编译目标与模块规范 |
moduleResolution |
模块解析策略（bundler 适合 Vite 等现代工具） |
paths |
路径别名，如 @/* |
noUncheckedIndexedAccess |
索引访问可能为 undefined 时给出提示 |
配合 @ts-check 可以让纯 JS 文件也获得检查，便于渐进迁移。strict 是其中最值得从第一天就开启的开关：它把 strictNullChecks、noImplicitAny 等一串检查打包打开，旧代码迁移时可能冒出不少报错，但新建项目没有历史包袱，建议直接开。
五、与构建工具的配合
TypeScript 本身只做类型检查与转译，实际打包交给构建工具。使用 Vite 时，esbuild/oxc 负责转译、tsc --noEmit 负责类型检查，职责分离更清晰（详见Vite 构建工具指南）。很多团队在 CI 里专门加一步 tsc --noEmit 作为门禁：代码合入前先过一遍类型检查，比靠开发者本地自觉可靠得多。另外建议在 tsconfig 里开启 verbatimModuleSyntax，强制用 import type 引入纯类型，esbuild 转译时就能直接把这些 import 删掉，不会出现"运行时还在导入一个不存在的值"这类问题。
六、落地建议
- 默认开启
strict：从第一天就避免any蔓延。 - 为公共 API 写类型：组件 props、接口返回结构是收益最高的地方。
- 克制使用
any：用unknown+ 收窄代替，保留类型安全。 - 类型与运行时解耦：优先用 interface/type 描述数据契约，配合运行时校验库处理外部输入。
七、常见问题
any和unknown有什么区别？any放弃所有检查，unknown要求先收窄再用。优先unknown。- interface 和 type 怎么选？ 对象契约用 interface（可合并、可 extends），联合类型、交叉类型这类组合用 type。
- 第三方库没有类型怎么办？ 先装
@types/xxx，实在没有可以声明declare module，但别把整库标成any了事。 - 编译太慢？
tsc --noEmit只做检查，打包交给 esbuild/oxc；大项目开启增量构建（incremental）。 strict开了报错太多？ 分文件逐步修，配合// @ts-expect-error先让流水线跑起来，再按模块清理；不要为了过检查全局关掉strict。
原文来源：https://www.typescriptlang.org/docs/handbook/intro.html
参考：https://www.typescriptlang.org/tsconfig/（tsconfig 选项全解）