Matt Pocock 这个名字只要你在 TypeScript 社区里待过一段时间基本上就绕不开。他主理的 Total TypeScript 课程几乎把日常开发里会踩到的类型坑都编排成了一个个可练习的技能模块。很多人以为类型系统只是“给编译器看的说明书”但在他这一套方法论里类型系统更像是一套约束数据流、降低改动成本的设计工具。我接触这套东西比较晚真正跑过一个项目之后才发现那些看上去偏学术的类型体操绝大多数答案其实是在解决真实接口对接、配置管理、组件复用里的麻烦事。这篇指南就是我把他那套教学体系里最值得拿出来的部分重新整理成一套可以直接照着练的实操路径。主要包含四个板块核心脉络梳理、类型窄化和模式匹配这类关键技能、一个从零到一的接口建模案例以及我平时在项目里遇到的报错排查清单。适合想把 TypeScript 从“能用”推进到“好用”的开发者也适合负责前端技术培训或基础设施的工程师拿去拆成内部的分享材料。1. 整体设计与思路拆解为什么先学“少写类型”1.1 技能地图从收窄到模式匹配再到运行时校验我最早看到 Matt Pocock 的内容时以为他教的是各种炫酷类型体操比如把hello转成hello world这种字符串字面量运算。后来跟着项目走了一遍才明白他那套技能体系真正的主线其实分成三层。第一层是类型窄化。也就是让 TypeScript 在控制流中自动把联合类型收窄成更具体的类型。比如一个变量可能是string | null通过if (value ! null)之后后续代码里它就只剩string了。第二层是类型转换包括泛型、条件类型、infer这些能完成“类型到类型”运算的工具。第三层是运行时校验把编译期的信任延伸到边界典型代表就是 Zod 这类 schema 校验库。这三个层次刚好对应写代码时的三个痛点手上拿到的数据到底是什么、函数要不要支持多种形态、外部接口返回的数据能不能被信任。按这个顺序练习不会一上来就被各种花哨类型操作劝退。我见过不少同学直接冲着一个infer写半天结果连联合类型都没玩明白最后做出来的东西只能在自己玩具项目里跑一进真实业务就露馅。先窄化、再转换、最后补运行时校验这条路线对大多数人来说是阻力最小的。1.2 为什么这套心法提倡“少写类型”很多人一学完类型系统就喜欢到处手动标注类型仿佛是给每一行代码都贴上标签。Matt 的方法论恰恰相反他在教学里反复强调的一个观点是尽量让 TypeScript 自己推断只在边界和真正需要约束的地方显式声明。这句话听起来简单做起来很有讲究。比如下面这段代码const numbers [1, 2, 3]; const doubled numbers.map((n) n * 2); let total doubled.reduce((sum, n) sum n, 0);这段代码从头到尾一个显式类型都没写但numbers会被推断成number[]doubled是number[]total是number。编译器全都能算出来为什么还要手动写一遍手动标注的真正价值在于那些编译器算不准、或者算出来不符合业务预期的地方。比如说一个对象的 key 需要精确到字面量一个函数返回值的类型依赖于另一个类型参数又或者一个变量在运行时才会拿到真实数据。把有限的精力放在这些位置比给几十个变量逐个加类型有用得多。这也是为什么实践中会强调“边界写死内部放养”。函数参数、对外暴露的接口、从外部拿到的数据这些是边界必须写得清清楚楚一个组件内部临时算出来的中间变量能推断就直接用推断。1.3 适用的项目和人群边界这套技能并不是所有项目都值得全套铺开。如果团队维护的是一个生命周期很短的营销活动页业务逻辑就两张 A4 纸的体量那花大量时间在类型建模上确实不划算。但如果是长期维护、多人协作、接口频繁变更的中后台项目或者是对稳定性要求比较高的基础库、算法模块这套方法能省下大量肉眼排查问题的时间。人群上我更推荐那些已经有半年以上 TypeScript 实际使用经验的人来学。完全零基础的话一上来就玩infer、条件类型容易晕。反过来如果在项目里已经写了很久any但对类型为什么报错始终说不清楚那这套技能就正好是你要补的那块短板。简单说会上手、但没体系的人收益最大。2. 核心细节解析与实操要点收窄、泛型和模式匹配2.1 类型窄化把 unknown 驯化成具体类型类型窄化说白了就是在程序的控制流里让 TypeScript 能根据判断条件排除掉一些不可能的类型分支。最常见的用法是判别联合也叫可辨识联合。type ApiResult | { ok: true; value: string } | { ok: false; error: string }; function handleResult(result: ApiResult) { if (result.ok) { // 这里 result 被收窄为 { ok: true; value: string } return result.value; } // 这里 result 被收窄为 { ok: false; error: string } return result.error; }这里只用了一个ok字段就把两个分支切开了。业务数据里很多接口响应其实都长得差不多关键是要分析出那个“判别属性”再用它写收窄逻辑。如果用一张接口响应表大多数情况都能被这一招覆盖。比判别联合更进阶一点的是自定义类型守卫。比如从接口拿到一个unknown你想判断它到底是不是一个用户对象。type User { id: number; name: string; }; function isUser(value: unknown): value is User { if (typeof value ! object || value null) return false; const maybe value as Recordstring, unknown; return typeof maybe.id number typeof maybe.name string; } const raw: unknown JSON.parse(localStorage.getItem(user) ?? null); if (isUser(raw)) { console.log(raw.name); // TS 知道这里 raw 是 User }这里有两点要提醒。第一个是不要随便用as断言当窄化用。value as User只是骗过编译器不承担任何运行时验证责任。如果一个unknown被断言成User但真实数据里没有id代码运行时照样会炸。自定义守卫里用as Recordstring, unknown只是临时把对象变成可索引形式来做检查这个操作是可控的。它不会把错误类型直接吞掉。第二个是filter(Boolean)这类写法要格外小心。学了一堆收窄技巧之后很容易写出const list [1, null, 2].filter(Boolean);这个list的类型在比较新的 TypeScript 版本里会推断成number[]但旧版本里还是(number | null)[]。更稳的写法是写一个类型守卫或者手动判空后再收窄不要把收窄依赖在某个让人看不透的库函数上。2.2 泛型把类型当成函数参数来理解很多初学者把泛型想象得很玄其实它跟函数参数是一个道理。function firstT(items: T[])里的T就是留给调用方填充的“类型参数”你传什么类型进去它就返回什么类型。function wrapInArrayT(input: T): T[] { return [input]; } const a wrapInArray(hello); // string[] const b wrapInArray(42); // number[]这个例子很基础但背后的思路值得放大泛型不是为了让你写出一个“任何情况都能兼容”的东西而是为了在不知道具体类型是什么的情况下仍然保留各类型之间的约束关系。再看一个业务里常见的场景。写一个针对表单配置的辅助函数这时候不应该把所有类型都收成any或Recordstring, unknown而是用泛型把输入的类型保留住。function createFormFieldT extends { required?: boolean }(initial: T) { return { ...initial, dirty: false, }; } const field createFormField({ name: email, required: true }); // field.dirty 存在且 name 仍然是 stringT extends { required?: boolean }是约束表示传入的东西至少要满足required可选这一条。如果你传进来一个没有required但结构完全不一样的对象编译会报错。但一旦通过检查它的原始字段类型都会被完整保留下来不会变成一坨宽泛类型。这也是我想强调的实操要点业务代码里的泛型约束越窄越好。不要写一个T extends Recordstring, unknown把整个对象都吞了那样只会让约束形同虚设。先想清楚调用方最需要保留什么关系再给T加上对应的弦。还有一种常见误用是过早引入泛型。比如一个函数永远只处理string[]有些人也会习惯性地写成T extends string说“以后好扩展”。这种泛型就是负担它让你在调用时凭空多出一层抽象。Matt 那套思路里有一个态度很明确泛型是延迟决定的类型没有延迟需求就没有泛型。2.3 模式匹配用 infer 解包和重组类型模式匹配在 TypeScript 里最核心的操作符就是infer。它的作用是在条件类型里让 TypeScript 去“猜”某一个位置的结构然后把猜到的类型暴露出来。最经典的例子是解包 Promisetype UnwrapT T extends Promiseinfer U ? U : T; type A UnwrapPromisestring; // string type B UnwrapPromise{ code: number }; // { code: number } type C Unwrapstring; // string这里T extends Promiseinfer U的意思是如果T满足“是 Promise 且内部有个未知类型”这一结构就把那个内部未知类型命名为U放在真分支里返回。如果T不是 Promise就直接返回T本身。同样的思想可以用来解包数组type ArrayItemT T extends Arrayinfer U ? U : never; type X ArrayItemstring[]; // string很多人在这一步就开始晕了因为对他们来说U像是凭空冒出来的变量。其实你可以把它理解成一段“类型版的正则匹配”T extends Promiseinfer U就是在做结构匹配U是这个匹配模式里的捕获组。在实际项目中infer最常见的落地是处理 API 函数返回值。比如我要写一个类型把某个函数的返回值从 Promise 里掏出来type UnwrapPromiseT T extends Promiseinfer U ? U : never; declare function fetchUser(): Promise{ name: string; age: number }; type User UnwrapPromiseReturnTypetypeof fetchUser; // User 是 { name: string; age: number }ReturnTypetypeof fetchUser得到的是Promise{ name: string; age: number }交给UnwrapPromise之后内部结构就被解出来了。练习这套内容的时候有一个很方便的自测方法用几个简单类型去“代入”条件类型自己在心里算一遍真分支和假分支。比如Unwrapnumber因为number不满足Promiseinfer U所以走T分支返回number。逐个推导比死记语法更有效。3. 实操过程与核心环节实现从一段烂接口代码开始3.1 打造一个能反复练习的最小环境在开始动项目之前建议先把练习环境准备好。其实不需要部署什么重型框架一个带 TypeScript 编译器的目录就够了。先初始化项目mkdir ts-practice cd ts-practice npm init -y npm install typescript types/node zod npx tsc --init装完依赖之后把tsconfig.json里的几个关键选项开起来。下面这份配置是我平时用来做类型练习的虽然不是官方课程里的标准配置但对于验证这套技能完全够用而且更贴近生产环境要求。{ compilerOptions: { strict: true, noUncheckedIndexedAccess: true, exactOptionalPropertyTypes: true, target: ES2022, module: ESNext, moduleResolution: Bundler, noEmit: true, skipLibCheck: true }, include: [src] }这里我重点解释几个容易忽略的选项。strict: true是底线不开它类型窄化和泛型约束的很多能力都会失效。noUncheckedIndexedAccess会让数组和索引签名访问变成T | undefined一开始会觉得烦但它逼着你在写arr[i]的时候真的考虑“有没有可能越界”。exactOptionalPropertyTypes则是让可选属性更加严格如果你声明{ plugins?: string[] }就不能塞一个undefined进去这能逼你用更清楚的方式表达“这个属性不存在”。这个环境里加 Zod 是因为后面要练运行时校验。如果只是纯类型练习不装 zod 也一样能跑。3.2 从一段真实接口代码开始重构假设原来项目里有这样一段代码async function loadConfig() { const response await fetch(/config.json); const json await response.json(); return json; }这个函数什么问题json被推断成any。any类型会把整个函数变成一个“无类型黑洞”调用方拿到之后无论访问什么属性编译器都不会拦等到运行时报错才发现数据长歪了。第一步要做的是把边界标出来把返回值写成明确的类型把any降成unknown。我常用的是一个小技巧先定义一个守卫函数再让主函数返回收窄后的类型。type LogLevel debug | info | warn | error; type AppConfig { appName: string; logLevel: LogLevel; retryTimes: number; plugins?: string[]; }; function isAppConfig(value: unknown): value is AppConfig { if (typeof value ! object || value null) return false; const maybe value as Recordstring, unknown; const logLevel maybe.logLevel; return ( typeof maybe.appName string (typeof logLevel string [debug, info, warn, error].includes(logLevel)) typeof maybe.retryTimes number (maybe.plugins undefined || Array.isArray(maybe.plugins)) ); } async function loadConfig(): PromiseAppConfig { const response await fetch(/config.json); const json: unknown await response.json(); if (!isAppConfig(json)) { throw new Error(配置文件格式不正确); } return json; }走到这一步这个函数已经有了基本的自保能力数据不对会在入口就抛错后续代码里拿到的json一定是符合AppConfig结构的。这里注意我故意没有检查plugins数组里的每一项是不是字符串因为在这个函数里校验粒度按业务风险来定就够了不一定每个字段都要挖到最底层。不过你可能也感觉到了这种手写守卫函数虽然可靠度高但写起来很啰嗦。字段一多一个isXxx函数能写上百行。这就是下一步用 Zod 的原因。3.3 用 Zod 补上运行时校验的最后一块拼图Zod 做的事情和手写守卫本质一样但它把 schema 描述和类型推导合到了一起。先定义一个 schema类型直接从 schema 里推导出来省掉手写两遍结构的工作。import { z } from zod; const LogLevelSchema z.enum([debug, info, warn, error]); const AppConfigSchema z.object({ appName: z.string(), logLevel: LogLevelSchema, retryTimes: z.number(), plugins: z.array(z.string()).optional(), }); type AppConfig z.infertypeof AppConfigSchema;注意这一行type AppConfig z.infertypeof AppConfigSchema它和前面手写的AppConfig是等价的只是现在只需维护一份 schema 即可。然后主函数变成async function loadConfig(): PromiseAppConfig { const response await fetch(/config.json); const json: unknown await response.json(); const parsed AppConfigSchema.safeParse(json); if (!parsed.success) { throw new Error(配置校验失败${parsed.error.message}); } return parsed.data; }safeParse和parse有什么区别parse在数据不符合 schema 时直接抛异常safeParse返回一个联合类型{ success: true; data }或{ success: false; error }。在真实接口处理里我几乎只用safeParse因为拿到失败分支之后还能做更友好的错误提示或降级处理。这就是编译时和运行时校验的完整拼图TypeScript 解决“代码写错”的问题Zod 解决“数据长歪”的问题。两者不冲突也没有谁替代谁。3.4 配合 satisfies 处理常量配置对象除了外部接口项目内部也经常有“结构像配置类型得过一遍”的场景。比如这么一段代码const appConfig { logLevel: error, retryTimes: 3, };如果直接写const appConfig: Recordstring, string | number ...最大问题是logLevel这个字段在后续使用时就变成string | number了你没法判断它到底是不是合法的LogLevel。如果什么都不标又可能因为某个字段拼错而让logLevel的类型变成string也失去约束。satisfies就是解决这个问题的。它的意思是检查这个对象是否符合某种形状但保留它原本的推断类型。const appConfig { logLevel: error, retryTimes: 3, } satisfies Recordstring, string | number; if (appConfig.logLevel error) { // 这里 appConfig.logLevel 仍然被推断为字符串字面量 error }这么做的好处非常直白既能发现多了不合法字段、少了必填字段之类的错误又不会把整个对象的类型信息磨没。在我自己的项目里它基本上替代了一大批“手写接口类型做常量约束”的用法。4. 常见问题与排查技巧实录4.1 项目里最高频的几类报错这一节直接上实战总结。我整理了平时在业务里见到最多的几类 TypeScript 报错配合解法一起看。报错高频起因推荐解法Type undefined is not assignable to...开启noUncheckedIndexedAccess后数组索引或对象索引访问可能为undefined不要直接断言删掉改成先判空再收窄或者用可选链Object is possibly nullDOM 查询、可选属性、后端字段没做空值判断用守卫函数处理不要用value!硬解Type string is not assignable to type ...字符串字面量联合类型被扩展成了string用as const或satisfies保住字面量类型Property x does not exist on type never联合类型所有分支都被收窄完最后落到never说明某个分支写错了或收窄条件有漏洞检查判断逻辑Excess property ... not assignable对象字面量直接赋给一个窄类型时出现了额外字段先想想是应该扩展目标类型还是这个字段真的不该出现第一条值得展开说。很多人追求尽量开启更多严格的编译器选项但打开了noUncheckedIndexedAccess之后会发现到处都是T | undefined。这时候最错误的做法是给每个访问都加上非空断言!那等于把这个选项白开了。正确的做法是让访问路径上的窄化逻辑真的存在比如function getFirst(arr: number[]): number | undefined { return arr[0]; // 在 noUncheckedIndexedAccess 下arr[0] 是 number | undefined } function useFirst(arr: number[]) { const first getFirst(arr); if (first ! undefined) { console.log(first.toFixed(2)); } }第二行arr[0]我甚至不用手动标注getFirst的返回值会自然带上undefined调用方必须处理。这个“必须处理”恰恰就是减少线上报错的关键。4.2 排错时的几个通用套路遇到一个摸不着头脑的类型错误与其盯着那一行代码发呆不如按下面几步走。第一步把报错拆成最小复现片段。不要在原组件里调试单独开一个repro.ts把相关类型和触发函数抽出来。抽的时候你会被迫理解嵌套关系很多时候问题出在外层类型被收窄得太窄而不是这一行本身。第二步把复杂的条件类型展开。比如你写了一个多层T extends ... ? ... : ...先给中间结果起名字打印出来看。虽然不能真的“打印类型”但可以定义一个中间类型然后悬停查看type UnwrapT T extends Promiseinfer U ? U : T; type Step1 Promise{ code: number }; type Step2 UnwrapStep1; // 悬停时看这里应该已经是 { code: number } type Step3 Step2[code]; // number这样一层层拆很快就能定位是哪一层条件类型走了错误分支。第三步善用ts-expect-error做渐进式排查但必须明确它是临时的。比如你怀疑某一行类型不对但整块代码还没改完可以先在这一行写// ts-expect-error看 TS 是否“确实报错”。如果它没有报错说明你的怀疑是错的而不是那个错误不存在。这是一个很好的对照排错工具。第四步把any暂时关掉。如果你在某段代码里用了any会把整个推断链污染掉。排查问题时可以临时把所有any改成unknown或具体的联合类型看看新的报错出现在哪里。新报错的位置往往就是真正的坑。4.3 让团队少走弯路的类型约定类型技能的落地不只是个人玩法还应该变成团队共识。我在自己项目里沉淀过几条约定每一行都是踩过坑之后补上的。外部数据边界统一用unknown进入再用 schema 或守卫收窄。不允许在fetch或response.json()之后直接写as SomeType因为那只是口头告诉编译器“相信我”一旦接口结构变化风险全部后置。这条规则能拦住大量隐性 bug。不要在业务组件内部写大段复杂条件类型。条件类型适合沉淀在types/或utils/里并配上一两个可复用的测试用例。组件里塞了太多类型运算别人维护起来很容易一脸茫然。给那些“看起来是字符串但语义上不是”的字段建立字面量联合类型而不是直接使用string。比如logLevel、status、actionType都属于这一类。直接上string会让if (status success)失去自动补全和拼写检查这是很多人没意识到的小损失。默认开启strict和相关严格选项除非项目确实有一些历史遗留兼容负担。如果团队还在用旧项目可以分批开启但不要永远停在strict: false。5. 我最后想分享的几个工程化习惯到了实践这一层真正拉开差距的不只是会不会写某个类型工具而是几个看起来不起眼的工作习惯。第一个习惯是“先写使用方再写类型”。我写泛型工具的时候经常会先写一段调用代码想象这个工具应该长什么样再回头去定义类型。比如我希望unwraptypeof fetchProduct能直接掏出来Product那我就先写type Product UnwrapReturnTypetypeof fetchProduct再补全Unwrap的实现。这样写出来的类型永远服务真实用法不会为抽象而抽象。第二个习惯是定期做“类型清理日”。类型代码也会腐化特别是项目经过几次重构之后大量旧接口类型还挂在老文件里没人用。我会用编辑器自带的“查找所有引用”功能把没有引用的类型删一删。类型定义太多会让新人在索引代码时迷失方向适度删减和清理其实也是在维护项目健康度。第三个习惯是把类型变更当成 API 变更来看待。每次改动一个公共函数签名或一个 schema不要只跑一遍编译就完事至少要在调用方那边看两处一个是这个函数被谁调用二是调用处拿到新类型之后的代码逻辑是否仍然合理。很多类型报错不是改不了而是改了之后没人检查调用方的行为结果编译过了业务逻辑却悄悄发生变化。拿下 Matt Pocock 这套技能本质上是把 TypeScript 从“编译检查工具”升级成“设计约束工具”。类型系统能在你动手写业务实现之前就把数据结构和接口约定固定下来这比多写几百行注释靠谱得多。我在实际项目里体会最深的一点是类型收窄和运行时校验配合起来看似多写了一点入口代码却省掉了后续大量的字段缺失排查和接口联调扯皮。如果你正在一个长期项目里被any和未知数据结构折磨按照上面这套路径练习一个月应该会明显感觉到那些莫名的线上错误开始变少了。
