如何用TypeScript提升大型前端项目的可维护性

结论：TypeScript 提升大型前端项目可维护性的本质，是把「接口约定、数据结构、调用关系」从人的记忆和口头约定，变成编译期就能校验的显式契约——重构时改错了字段，本地 tsc 立刻报错，而不是等测试或线上暴露。落地靠三件事：tsconfig 打开 strict 全家桶、在系统边界用运行时校验库兜底、CI 用 tsc --noEmit 卡住类型回归。

TypeScript 靠什么减少大型项目的维护成本？

结论：靠「编译期失败」替代「运行时失败」，把错误暴露时间从线上提前到保存文件的那一秒。

具体是三条路径。第一，类型即文档：函数签名写明参数与返回值，新人不用逐个翻调用方就知道怎么用。第二，重构可验证：改一个 interface 字段名，配合 IDE 的「查找所有引用」和 tsc 报错，能列出全部受影响位置；纯 JS 项目只能靠 grep 加运气。第三，IDE 的跳转、重命名、内联提示只有在类型完整时才准确，JS 项目里这些功能退化成文本搜索。

前提是类型要「真」。一旦代码里出现 as any，这条链路就断了。

tsconfig 里哪些选项必须打开？

结论：strict: true 是底线，noUncheckedIndexedAccess、exactOptionalPropertyTypes、verbatimModuleSyntax 是大型项目与中小项目拉开差距的开关。

strict 本身是一套开关的合集，包含 noImplicitAny、strictNullChecks、strictFunctionTypes、strictBindCallApply、strictPropertyInitialization、noImplicitThis、alwaysStrict、useUnknownInCatchVariables。它不包含下面两个关键项：

• noUncheckedIndexedAccess（TS 4.1 起）：让 arr[0] 的类型从 T 变成 T | undefined，逼你在访问前判空。数组越界是前端运行时错误的主要来源之一。
• exactOptionalPropertyTypes（TS 4.4 起）：区分 { a?: string } 与 { a?: string | undefined }，避免可选属性被显式赋 undefined。

再加 isolatedModules: true 保证单文件转译安全，verbatimModuleSyntax: true（TS 5.0 起）强制 import type 写法，避免把类型当运行时值引入。

构建速度方面：skipLibCheck: true 跳过 node_modules 里 .d.ts 的检查，incremental: true 配合 tsBuildInfoFile 做增量编译。monorepo 用 Project References（TS 3.0 起）：子包 tsconfig 加 composite: true，根 tsconfig 用 references 指向子包，tsc --build 只重编译改动过的包。

系统边界为什么必须做运行时校验？

结论：类型在编译后被擦除，JSON 响应、localStorage、URL 参数在运行时全是未知数据，必须在进入业务代码的第一层做校验。

import { z } from 'zod';
const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  age: z.number().int().nonnegative(),
});
type User = z.infer<typeof UserSchema>;
const user = UserSchema.parse(await res.json());

用 z.infer 从 schema 反推类型，一份定义同时管住运行时和编译期，避免「接口改了、手写类型没改」的漂移。边界只有四处：HTTP 响应、本地存储、URL/路由参数、跨窗口消息。内部函数之间不要再重复校验，否则类型系统就白建了。

类型文件怎么组织？

结论：类型就近定义、就近导出，全局 .d.ts 只留给「给第三方库补类型」这一种用途。

大型项目常见的坏味道是 src/types/global.d.ts 里堆几百行 interface，谁都能改、谁都不敢删。改成每个模块自己导出类型，跨模块复用走 export type。第三方库缺类型时用 declare module 'xxx' 补，并注明对应的库版本。

再用品牌类型区分同构的字符串：

type UserId = string & { readonly __brand: 'UserId' };

这样把 OrderId 传进需要 UserId 的函数会直接编译报错，而不是等到数据库查询返回空。

CI 里怎么防止类型退化？

结论：把 tsc --noEmit 和 ESLint 类型规则设为 CI 必过项，并对 @ts-ignore 零容忍。

1. package.json 加 "typecheck": "tsc --noEmit -p tsconfig.json"，在 CI 里先跑这一步再跑测试。
2. ESLint 接 typescript-eslint 的 recommended-type-checked，开启 no-explicit-any、no-unsafe-assignment。
3. 存量迁移期用 @ts-expect-error（TS 3.9 起）替代 @ts-ignore：前者在类型错误被修好后自身会报错，等于自动生成待办清单；后者永远静默。
4. 用 knip 或 ts-prune 扫无人引用的导出类型与函数，定期清理。

整套做下来，维护成本的变化体现在一处：改动不再依赖「记得住」，而是依赖「编译器查得出」。strict 选项、边界校验、CI 卡点三件配套，缺任何一件，类型覆盖率都会在半年内回落。