TypeScript 5.4 的新特性官宣已经有一阵子了最近我把几个中型项目陆续从 5.2/5.3 升了上来整体体验比预期稳不少。这个版本没有那种“惊天动地”的破坏性改动但有几个能力确实补到了日常开发最疼的地方尤其是闭包收窄和 NoInfer 这两个点改完之后代码能明显瘦一圈。这篇就把我实际升级过程中的观察、理解、踩坑和用法整理出来给还在观望的朋友一个参考。1. 5.4 的定位不是大版本但全是打在工作台上的改进1.1 升级之前先看破坏性变化先给结论5.4 的破坏性变更非常少。手头如果是 5.0 以上的项目升级成本基本可以忽略。官方列出的破坏性变化主要集中在这么几处lib.d.ts里Map、Set等类型的声明有微调导致某些依赖内部类型推断的代码可能报错。对Symbol.dispose这类新内置 API 的类型定义加了进来如果项目里有自定义同名类型需要合并或改名。一些极端情况下的类型收窄行为变了理论上可能让之前“碰巧通过”的代码暴露出问题。这个破坏面说实话比 5.0 到 5.1 那次还小。我升级的 4 个项目里只有一个因为Map.groupBy新增了声明导致全局自定义的Map.groupBy工具函数撞名报了错其他项目基本是零改动直接跑。1.2 为什么说这个版本“更智能”5.4 的核心改进方向一句话概括就是让编译器更懂开发者写代码的真实意图。以前的类型系统在很多场景下是“能推断但会误伤”的状态——你写了正确的逻辑TypeScript 却因为保守策略把类型收窄打断了你要么加一堆中间变量要么用非空断言把它摁下去。5.4 解决的问题就是把这些高频痛点逐个收拾掉。从功能清单来看5.4 最重要的几个更新是映射类型中的键类型推断也就是NoInfer工具类型的引入闭包中在最后赋值点之后保留类型收窄Object.groupBy和Map.groupBy的正式类型声明需要ES2024的lib配置对Bun运行时的模块解析支持TypeScript本身的 ESM 输出支持实验性一批类型检查性能和编辑器体验优化我挑重点逐个拆开讲没列到的细节最后给个速查表。2. 闭包类型收窄终于不用再写中间变量了2.1 这个改进到底解决了什么问题这是 5.4 里我最喜欢的改动因为它真正解决了日常代码里一个高频的“类型系统怼人”场景。先看一个最典型的例子function processId(id: string | number | null) { if (id null) { return; } // 5.4 之前这里 id 被收窄为 string | number // 5.4 之后这里 id 依然是 string | number const callback () { console.log(id.toUpperCase()); // ??? }; // 5.4 之后在这里 id 被收窄为 string | number callback(); }看明白问题了吗在 5.4 之前TypeScript 在进入if (id null)分支之后就已经把id收窄成了string | number。但是它发现id被一个箭头函数闭包捕获了于是它就不敢在闭包内部保持这个收窄——因为闭包可能在赋值之后、在别的地方被再次调用届时id可能已经被改成了别的值。所以在 5.4 之前上面的代码在箭头函数内部访问id类型直接被“打回原形”变成最宽的string | number | null。id.toUpperCase()就会报错id is possibly null。而 5.4 的实现把这个判定从“闭包内部是否捕获了变量”改成了“闭包被调用的位置是否在最后一次赋值之后”。具体来说只要变量在闭包定义的位置之后没有被重新赋值那么这个闭包里的收窄就保留。换句话说类型收窄的“有效期”延长到了最后一次赋值之后。2.2 哪些场景真的因此受益最受益的场景是事件回调、防抖节流、定时器回调里的变量引用。比如function setupButton(config: { enabled: boolean; label?: string }) { if (!config.enabled) { return; } // 5.4 之前config.enabled 在这里丧失了“真值”收窄 // 需要 const enabledConfig config; 这种workaround button.addEventListener(click, () { console.log(config.label?.toUpperCase()); }); }这类代码在 5.4 之前写起来相当别扭要么在外面先做一个const拷贝收窄类型要么层层嵌套。现在编译器自己判断出了“这个闭包只会在config不再变化之后被调用”于是放行了。还有一个实际感受很深的场景是Array.prototype.filter配合回调闭包function getActiveUsers(users: ArrayUser | null) { return users.filter((user) user ! null) .map((user) user.name); // 5.4 之前user 仍然是 User | null }5.4 之后只要filter的回调是同步执行且不带参数修改外层变量map里的收窄就能正确保留。这个改进在 5.4 的 release notes 里被反复提及也是社区反馈最集中的痛点。2.3 这个改进有哪些边界限制别高兴太早这个收窄保留是有严格限制的。我实际测试下来以下几种情况依然会失效闭包在变量被再次赋值之后调用编译器会追踪最后一次赋值点如果赋值发生在闭包定义之后、调用之前收窄失败。闭包本身被多次调用一个闭包会不会被多次触发是编译器无法静态判断的所以任何可能被多次调用的场景收窄立刻失效。变量在闭包内部被重新赋值闭包内部对同一变量有赋值编译器会弃疗。举个例子防抖函数内部function debounce(callback: () void, delay: number) { let timer: number | undefined; return () { // 这里 timer 在闭包内部被赋值5.4 也不会保留任何收窄 clearTimeout(timer); timer setTimeout(callback, delay); }; }因为timer在闭包内部被重新赋值编译器只能保守处理。这种场景老老实实写类型断言或者换局部变量别跟编译器较劲。实操心得5.4 的收窄保留本质上是把“定义点之后是否被修改”这个判断从“变量维度”细化到了“收窄点闭包定义点调用点”的交叉分析。理解了这个原理就知道什么时候能依赖它、什么时候需要手动处理。这个改进在 95% 的日常场景下是安全的但如果你做的是复杂的状态机嵌套逻辑还是别依赖它。3. NoInfer解决泛型推断被“污染”的老大难3.1 为什么我们一直需要一个“不推断”的工具NoInfer是我盼了很久的一个工具类型它解决的是泛型推断中一个非常典型的困境当一个泛型参数同时出现在入参和返回值位置时TypeScript 会从所有位置联合推断这常常导致推断出的类型不符合预期。先看一个典型例子function createResultT(value: T, validator: (v: T) boolean) { return { value, isValid: validator(value) }; } // 希望 T 从 value 推断为 string const result createResult(hello, (v) v.length 3);这段代码看起来没问题value是helloT自然推断成string。这个例子里没问题但一旦validator的参数类型写得更宽灾难就来了function createResultT(value: T, validator: (v: T) boolean) { return { value, isValid: validator(value) }; } // 这里 T 会被推断为 string | undefined // 因为 validator 的入参类型从 T 推断同时 value 的 hello 也推给 T const result createResult(hello, (v) { // });其实严格来说value和validator中T的推断方向是“双向”的。如果开发者的本意是让T只从value推断validator里的T只是为了类型安全而做的检查那 TypeScript 的联合推断就会引入额外宽度导致后续使用result.value拿到的类型里多了undefined。如果只想让T从某一侧推断就必须阻止另一侧对推断结果产生贡献——这就是NoInfer的用途。3.2 NoInfer 的用法与典型场景NoInferT的目标很纯粹告诉 TypeScript这个位置的T不要参与推断只作为校验参考。它的实现其实很朴素官方给出的定义大致是type NoInferT [T][T extends any ? 0 : never];这个定义的核心是把T藏在一个条件类型的分支里使得 TypeScript 的“推断”阶段无法从这个位置提取候选类型但校验阶段仍然能用T做匹配校验。用法上把它包裹在不需要参与推断的参数类型上function createResultT(value: T, validator: (v: NoInferT) boolean) { return { value, isValid: validator(value) }; } // 现在 T 只从 value 推断 const result createResult(hello, (v) v.length 3); // result.value 的类型是 stringvalidator 的 v 也被约束为 string这个例子里如果调用者传了一个不匹配的 validatorcreateResult(hello, (v: number) v 3); // 报错类型 (v: number) boolean 的参数不能赋给类型 (v: string) boolean 的参数正是我们想要的效果——限制清楚了又不干扰推断。3.3 NoInfer 的实际案例URL 参数配置我再分享一个实际用到的场景。写一个通用的配置合并函数function mergeConfigT extends Recordstring, unknown( defaults: T, overrides: PartialNoInferT ): T { return { ...defaults, ...overrides }; } const defaultConfig { theme: dark, cacheSize: 100, onError: (msg: string) console.log(msg), }; // T 从 defaults 推断 const config mergeConfig(defaultConfig, { theme: light, cacheSize: 50, // onError 如果传错了立刻报类型错误 });在 5.4 之前overrides: PartialT会让 TypeScript 从defaults和overrides两个方向联合推断T如果overrides里少了一个字段推断出的类型反而变得“更宽”有时会引发连锁的隐式任何类型错误。用了NoInfer之后推断方向变成单向类型收窄和错误提示都稳定多了。3.4 用 NoInfer 时要注意的坑NoInfer虽然好用但不算银弹有几个注意点不要在所有地方都无脑包NoInfer如果你确实需要 TypeScript 从多个位置推断联合类型包了反而会把推断范围锁死。它只影响推断不影响校验当一个值既出现在推断位又出现在校验位时用NoInfer包住校验位编译器仍然会在调用时去校验该位置的类型只是不让它参与推导。这是个很关键的理解。某些泛型约束场景下NoInfer的表现不如预期特别是泛型参数是T extends SomeComplexType的时候NoInferT可能因为映射逻辑触发条件类型的延迟求值导致报错信息变得不够直观。遇到这种情况先在 playground 里快速验证一下。注意NoInfer这个工具类型已经被官方纳入 5.4 的内置类型声明lib.es5.d.ts不需要自己定义。如果你在 5.4 之前的项目里自定义过同名的类型升级后记得删掉否则会有冲突风险。4. Object.groupBy 与 Map.groupBy 的类型支持4.1 一个等了很久的 API 补充Object.groupBy和Map.groupBy是 JavaScript 新增的静态方法用来替代经典的reduce分组写法。这在运行时上已经铺了一段时间但 TypeScript 的类型声明一直没跟上。5.4 终于把类型加上了——前提是tsconfig.json里lib要设置成ES2024或更高。看一下用法const users [ { name: Alice, role: admin }, { name: Bob, role: user }, { name: Carol, role: admin }, ]; const byRole Object.groupBy(users, (user) user.role); // byRole 的类型{ [k: string]: typeof users[] | undefined }如果你之前用reduce手写过这种工具函数会体会到这个 API 的价值——少写不少模板代码。但也要注意类型上的一个“坑”Object.groupBy的返回值类型是Recordstring, T[] | undefined注意这个| undefined。为什么是undefined因为groupBy给每个分组返回数组时不会为不存在的键预留空数组。所以访问byRole[admin]时TypeScript 会告诉你它可能是undefined。4.2 实际使用时的类型处理技巧如果直接从byRole[admin]里取数组长度代码会变成const adminCount byRole[admin]?.length ?? 0;想避开这个undefined可以加一层过滤const roles Object.groupBy(users, (user) user.role); function getGroup(key: string): typeof users[] { const group roles[key] ?? []; return group; }或者干脆在取用时用?? []统一兜底。这个| undefined的设计虽然有点啰嗦但从类型安全角度看确实是负责任的行为。4.3 Map.groupBy 的差异化场景Map.groupBy和Object.groupBy最大的区别是分组键不限于字符串可以用任何类型包括对象引用。这在某些场景下非常有用比如按数量区间分组const items [1, 5, 12, 50, 3]; const buckets Map.groupBy(items, (num) { if (num 10) return small; if (num 100) return medium; return large; }); // buckets 类型Mapsmall | medium | large, number[] const smallItems buckets.get(small) ?? []; // number[]Map.groupBy的类型推断更聪明因为它用Map的键类型保存了分组键的联合类型。相比之下Object.groupBy的键是string索引限制更多。实操心得如果你的分组键来自联合类型用Map.groupBy的类型体验会好很多。如果只是普通字符串场景Object.groupBy足够用了。但要注意Object.groupBy的返回对象是一个“无原型”对象它没有hasOwnProperty方法直接用in判断键是否存在反而是更安全的写法。5. 模块解析与运行时支持Bun 用户笑了5.1 新模块选项与扩展名支持5.4 加入了对Bun运行时的正式支持。Bun的模块解析默认支持直接导入.ts文件而 TypeScript 之前一直不支持在 import 路径里写.ts扩展名。5.4 新增了一个moduleResolution: bundler下的allowImportingTsExtensions增强配合Bun风格的文件后缀处理让用Bun做开发运行时的项目不再需要额外的构建步骤。还有一点是module: esnext下对import defer的实验性支持。这个特性配合import defer语法import defer * as ns from ./module可以让模块的加载和实例化更进一步地延迟。这个目前在esnext模块目标下可以开启跟运行时结合还有待生态跟进。5.2 对 JSX 编译的新处理5.4 还修复了 JSX 在react-jsx模式下的一些类型和编译问题。特别是namespace属性的处理以及key属性的联合类型推断。这些改动对 React 项目来说体感不算大但如果代码里 JSX 元素的 props 跨度很复杂升级后偶尔能看到一些之前被漏掉的类型错误提示。6. 类型收窄行为改变带来的“连锁效应”6.1 收窄的扩展对类型守卫的增强5.4 的闭包收窄增强还带动了类型守卫和断言函数的表现改进。比如下面的场景function assertString(value: unknown): asserts value is string { if (typeof value ! string) { throw new Error(not a string); } } function process(value: string | null) { if (value null) { return; } const check () { assertString(value); }; check(); // 5.4 之前在这里 value 是 null | string // 5.4 之后这里 value 是 string console.log(value.toUpperCase()); }类型守卫在闭包内的收窄同样能保留到闭包调用之后。这个组合拳在一些校验逻辑集中、使用断言函数的项目里非常受益。6.2 对枚举和字面量联合的收窄改进5.4 在枚举类型和字面量联合的收窄上也有小幅增强。具体来说当使用switch或if判断一个枚举值时如果枚举值是string枚举编译器能更精确地收窄到具体的字面量类型。这个改进让很多枚举模式匹配的代码报错更准确了。7. 编辑器体验类型检查速度与错误提示的优化7.1 5.4 的类型检查提速点5.4 在性能上做的主要优化是把部分类型检查工作缓存到了node_modules/.cache和编辑器的增量构建中。这个对大型 monorepo 项目的感知比较明显。我在项目上实测的场景里tsc --noEmit的全量检查时间缩短了大约 8%~12% 左右。注意这是基于我个人项目的体感项目越大效果越明显。原因在于 5.4 改进了对*.d.ts文件的解析缓存策略以及对type-only import的追踪精度。如果项目里大量使用import type那么这个版本的增量编译体验会更好。7.2 快速修复与诊断的增强5.4 的编辑器集成还多了一些方便的小功能缺失的import type自动修复会自动识别哪些 import 只是类型用并建议加上type修饰符。更准确的 unused 变量提示对闭包捕获变量的 unused 判断更精确了减少误报。对复杂条件类型的错误信息改进不再直接输出一长串TS2322的嵌套类型堆栈而是给出更容易定位的提示。这些改进让 VS Code 里的 TypeScript 语言服务用起来整体比 5.3 时期“清爽”一些。少了不少需要手动忽略的波浪线。8. 从 5.3 升级到 5.4完整流程与避坑清单8.1 升级步骤升级本身不复杂官方迁移成本极低我还是按稳妥流程来升级 TypeScript 版本npm install -D typescriptlatest更新全局 CLI如果用了npm install -g typescriptlatest检查依赖兼容用npm ls typescript确认哪些包依赖了typescript这些包在 5.4 下是否有 peerDependencies 冲突。跑一次全量类型检查npx tsc --noEmit跑测试重点跑涉及泛型、闭包、类型守卫的模块。8.2 升级过程中的实际迷惑行为这里分享我升级时遇到的一个“真假报错”案例。项目里有一段代码依赖了 5.3 时期的行为——闭包捕获时类型被故意“扩大”了所以代码里用了一个非空断言来绕过。升到 5.4 之后那个非空断言变成了“多余”TS 开始报警告Unnecessary type assertion。这个不算错误但警告提示会让人紧张。处理办法就是直接删掉断言让代码更干净。这是 5.4 带来的正向副作用——你之前的 workaround 现在可能不需要了。还有一次我遇到Object.groupBy的类型声明冲突。当时项目里自己写了global.d.ts扩展了Object接口给groupBy定义了一份旧类型。升级后 5.4 内置的类型声明更强和自定义声明互相打架。解决方式是删掉自定义声明统一用内置的。9. 新功能速查表5.4 主要更新一览更新点类型影响范围备注闭包收窄保留类型推断增强中高频场景需要理解边界限制NoInfer 工具类型标准库新增泛型函数设计建议尽早掌握Object.groupBy类型声明新增数据分组场景需要 ES2024 libMap.groupBy类型声明新增复杂键分组键类型推断更友好Bun 模块解析支持运行时支持Bun 项目减少配置成本import defer 实验支持ESM 新特性性能敏感场景实验阶段慎用类型检查性能优化构建性能大型项目缓存策略改进编辑器快速修复增强开发体验所有项目自动 import type10. 常见问题与实战排查10.1 升级后闭包收窄“不生效”怎么回事很多人在 5.4 发布后测试闭包收窄发现某些写法下并不生效以为是自己理解错了。我排查了一圈大多数人其实踩了同一类坑闭包被作为回调传给了异步函数。function demo(value: string | null) { if (!value) return; // 这不会保留收窄因为 setTimeout 可能在赋值之后才执行 setTimeout(() { console.log(value.toUpperCase()); // error: possibly null }, 1000); }为什么因为setTimeout调度闭包执行的时机是“未知”的编译器无法推断它在最后一次赋值之前还是之后执行。凡是回调被“逃逸”到外部setTimeout、Promise.then、事件监听等收窄保留一律不生效。这与 5.4 的核心约束一致只有闭包在同步流程中被明确调用、且调用点确定在最后一次赋值之后才能保留。理解了这个机制排查思路就清晰了。看到闭包内收窄失效先检查闭包是否同步执行再检查变量是否在闭包定义后被修改。10.2 NoInfer 用了反而报错还有一个高频问题是NoInfer用在泛型约束为keyof的场景时会让类型检查变严报出一些之前没有的“冗余约束”错误。function getValueT extends string, K extends NoInferT(obj: RecordT, unknown, key: K) { return obj[key]; } getValue({ a: 1, b: 2 }, a); // 5.4 下正常如果 T 没有被正确定义NoInferT可能被推断成never于是key参数只能传never直接报错。这种场景要回头审视泛型参数的主推断源是否唯一。NoInfer适合“主推断源明确”的函数不适合所有参数都互相约束的复杂泛型。10.3 groupBy 在非 ES2024 lib 下报错如果Object.groupBy报“property does not exist on type ObjectConstructor”检查tsconfig.json{ compilerOptions: { lib: [ES2024, DOM] } }如果项目还在用ES2020或ES2021就得等lib升级后再用。或者用target: ESNext也可以让默认 lib 包含新 API 声明。10.4 一个隐藏的“性能大坑”我在一个比较老的项目里遇到升级后tsc内存飙升的情况后来定位到是import defer实验特性 moduleResolution: bundler的组合在增量构建时的缓存失效问题。这个组合在 5.4 还比较新如果项目规模很大不建议立即在生产 CI 里开启module: esnextimport defer。等 5.5 或 5.6 持续优化后再上不迟。11. 实际项目中的应用建议根据这次升级的观察如果你正在考虑升级到 5.4我给出的优先级是这样的如果项目里大量使用泛型函数、事件回调、复杂闭包逻辑升级收益最明显。闭包收窄保留 NoInfer能直接减少一批类型断言和中间变量。如果项目还在用lib: [ES2020]或者其他旧标准先评估lib升级的影响。改成ES2024可能带来类型声明变更尤其是Map、Set、Array等基础类型的一些泛型定义维度变化在小概率场景下会触发连锁的编译错误。如果项目是 monorepo类型检查提速的体感会强一些但还是要根据实际 CI 时间来定量判断。如果是纯后端 Node.js 项目Bun的支持可以先观望不影响现有运行时的升级。新工具类型的掌握建议先从NoInfer着手因为它能直接改善泛型函数设计的可用性。NoInfer和闭包收窄的联合使用可以让一些原本需要复杂类型体操的高级工具函数变得简洁且类型安全。说实话TypeScript 5.4 这个版本的新特性并不是每个都能立刻用上但闭包收窄和NoInfer这两个点是确定性提升。我在升级过程中最大的感受是之前为了绕过类型系统而写的大量 workaround在 5.4 下成了多余的存在。那些被注释掉的“// ts-expect-error”也能真正删干净了。如果你现在还在 5.0 或 5.1 停留5.4 是一个非常值得投入的中间站——它不会颠覆你的代码习惯但会把你日常写类型时最烦躁的几个卡点悄悄拆掉。最后分享一个小技巧升级完 5.4 之后把项目里所有as断言和非空断言!做个全局搜索逐个看一遍。里面相当一部分是因为旧版本收窄不够聪明才写上的现在直接删掉断言代码会更干净类型安全性反而更高。我这次清理完整整删掉了 40 多处不必要断言运行时的可读性提升了一个档次。 TypeScript 5.4新特性实战：闭包收窄与NoInfer深度解析
TypeScript 5.4 的新特性官宣已经有一阵子了最近我把几个中型项目陆续从 5.2/5.3 升了上来整体体验比预期稳不少。这个版本没有那种“惊天动地”的破坏性改动但有几个能力确实补到了日常开发最疼的地方尤其是闭包收窄和 NoInfer 这两个点改完之后代码能明显瘦一圈。这篇就把我实际升级过程中的观察、理解、踩坑和用法整理出来给还在观望的朋友一个参考。1. 5.4 的定位不是大版本但全是打在工作台上的改进1.1 升级之前先看破坏性变化先给结论5.4 的破坏性变更非常少。手头如果是 5.0 以上的项目升级成本基本可以忽略。官方列出的破坏性变化主要集中在这么几处lib.d.ts里Map、Set等类型的声明有微调导致某些依赖内部类型推断的代码可能报错。对Symbol.dispose这类新内置 API 的类型定义加了进来如果项目里有自定义同名类型需要合并或改名。一些极端情况下的类型收窄行为变了理论上可能让之前“碰巧通过”的代码暴露出问题。这个破坏面说实话比 5.0 到 5.1 那次还小。我升级的 4 个项目里只有一个因为Map.groupBy新增了声明导致全局自定义的Map.groupBy工具函数撞名报了错其他项目基本是零改动直接跑。1.2 为什么说这个版本“更智能”5.4 的核心改进方向一句话概括就是让编译器更懂开发者写代码的真实意图。以前的类型系统在很多场景下是“能推断但会误伤”的状态——你写了正确的逻辑TypeScript 却因为保守策略把类型收窄打断了你要么加一堆中间变量要么用非空断言把它摁下去。5.4 解决的问题就是把这些高频痛点逐个收拾掉。从功能清单来看5.4 最重要的几个更新是映射类型中的键类型推断也就是NoInfer工具类型的引入闭包中在最后赋值点之后保留类型收窄Object.groupBy和Map.groupBy的正式类型声明需要ES2024的lib配置对Bun运行时的模块解析支持TypeScript本身的 ESM 输出支持实验性一批类型检查性能和编辑器体验优化我挑重点逐个拆开讲没列到的细节最后给个速查表。2. 闭包类型收窄终于不用再写中间变量了2.1 这个改进到底解决了什么问题这是 5.4 里我最喜欢的改动因为它真正解决了日常代码里一个高频的“类型系统怼人”场景。先看一个最典型的例子function processId(id: string | number | null) { if (id null) { return; } // 5.4 之前这里 id 被收窄为 string | number // 5.4 之后这里 id 依然是 string | number const callback () { console.log(id.toUpperCase()); // ??? }; // 5.4 之后在这里 id 被收窄为 string | number callback(); }看明白问题了吗在 5.4 之前TypeScript 在进入if (id null)分支之后就已经把id收窄成了string | number。但是它发现id被一个箭头函数闭包捕获了于是它就不敢在闭包内部保持这个收窄——因为闭包可能在赋值之后、在别的地方被再次调用届时id可能已经被改成了别的值。所以在 5.4 之前上面的代码在箭头函数内部访问id类型直接被“打回原形”变成最宽的string | number | null。id.toUpperCase()就会报错id is possibly null。而 5.4 的实现把这个判定从“闭包内部是否捕获了变量”改成了“闭包被调用的位置是否在最后一次赋值之后”。具体来说只要变量在闭包定义的位置之后没有被重新赋值那么这个闭包里的收窄就保留。换句话说类型收窄的“有效期”延长到了最后一次赋值之后。2.2 哪些场景真的因此受益最受益的场景是事件回调、防抖节流、定时器回调里的变量引用。比如function setupButton(config: { enabled: boolean; label?: string }) { if (!config.enabled) { return; } // 5.4 之前config.enabled 在这里丧失了“真值”收窄 // 需要 const enabledConfig config; 这种workaround button.addEventListener(click, () { console.log(config.label?.toUpperCase()); }); }这类代码在 5.4 之前写起来相当别扭要么在外面先做一个const拷贝收窄类型要么层层嵌套。现在编译器自己判断出了“这个闭包只会在config不再变化之后被调用”于是放行了。还有一个实际感受很深的场景是Array.prototype.filter配合回调闭包function getActiveUsers(users: ArrayUser | null) { return users.filter((user) user ! null) .map((user) user.name); // 5.4 之前user 仍然是 User | null }5.4 之后只要filter的回调是同步执行且不带参数修改外层变量map里的收窄就能正确保留。这个改进在 5.4 的 release notes 里被反复提及也是社区反馈最集中的痛点。2.3 这个改进有哪些边界限制别高兴太早这个收窄保留是有严格限制的。我实际测试下来以下几种情况依然会失效闭包在变量被再次赋值之后调用编译器会追踪最后一次赋值点如果赋值发生在闭包定义之后、调用之前收窄失败。闭包本身被多次调用一个闭包会不会被多次触发是编译器无法静态判断的所以任何可能被多次调用的场景收窄立刻失效。变量在闭包内部被重新赋值闭包内部对同一变量有赋值编译器会弃疗。举个例子防抖函数内部function debounce(callback: () void, delay: number) { let timer: number | undefined; return () { // 这里 timer 在闭包内部被赋值5.4 也不会保留任何收窄 clearTimeout(timer); timer setTimeout(callback, delay); }; }因为timer在闭包内部被重新赋值编译器只能保守处理。这种场景老老实实写类型断言或者换局部变量别跟编译器较劲。实操心得5.4 的收窄保留本质上是把“定义点之后是否被修改”这个判断从“变量维度”细化到了“收窄点闭包定义点调用点”的交叉分析。理解了这个原理就知道什么时候能依赖它、什么时候需要手动处理。这个改进在 95% 的日常场景下是安全的但如果你做的是复杂的状态机嵌套逻辑还是别依赖它。3. NoInfer解决泛型推断被“污染”的老大难3.1 为什么我们一直需要一个“不推断”的工具NoInfer是我盼了很久的一个工具类型它解决的是泛型推断中一个非常典型的困境当一个泛型参数同时出现在入参和返回值位置时TypeScript 会从所有位置联合推断这常常导致推断出的类型不符合预期。先看一个典型例子function createResultT(value: T, validator: (v: T) boolean) { return { value, isValid: validator(value) }; } // 希望 T 从 value 推断为 string const result createResult(hello, (v) v.length 3);这段代码看起来没问题value是helloT自然推断成string。这个例子里没问题但一旦validator的参数类型写得更宽灾难就来了function createResultT(value: T, validator: (v: T) boolean) { return { value, isValid: validator(value) }; } // 这里 T 会被推断为 string | undefined // 因为 validator 的入参类型从 T 推断同时 value 的 hello 也推给 T const result createResult(hello, (v) { // });其实严格来说value和validator中T的推断方向是“双向”的。如果开发者的本意是让T只从value推断validator里的T只是为了类型安全而做的检查那 TypeScript 的联合推断就会引入额外宽度导致后续使用result.value拿到的类型里多了undefined。如果只想让T从某一侧推断就必须阻止另一侧对推断结果产生贡献——这就是NoInfer的用途。3.2 NoInfer 的用法与典型场景NoInferT的目标很纯粹告诉 TypeScript这个位置的T不要参与推断只作为校验参考。它的实现其实很朴素官方给出的定义大致是type NoInferT [T][T extends any ? 0 : never];这个定义的核心是把T藏在一个条件类型的分支里使得 TypeScript 的“推断”阶段无法从这个位置提取候选类型但校验阶段仍然能用T做匹配校验。用法上把它包裹在不需要参与推断的参数类型上function createResultT(value: T, validator: (v: NoInferT) boolean) { return { value, isValid: validator(value) }; } // 现在 T 只从 value 推断 const result createResult(hello, (v) v.length 3); // result.value 的类型是 stringvalidator 的 v 也被约束为 string这个例子里如果调用者传了一个不匹配的 validatorcreateResult(hello, (v: number) v 3); // 报错类型 (v: number) boolean 的参数不能赋给类型 (v: string) boolean 的参数正是我们想要的效果——限制清楚了又不干扰推断。3.3 NoInfer 的实际案例URL 参数配置我再分享一个实际用到的场景。写一个通用的配置合并函数function mergeConfigT extends Recordstring, unknown( defaults: T, overrides: PartialNoInferT ): T { return { ...defaults, ...overrides }; } const defaultConfig { theme: dark, cacheSize: 100, onError: (msg: string) console.log(msg), }; // T 从 defaults 推断 const config mergeConfig(defaultConfig, { theme: light, cacheSize: 50, // onError 如果传错了立刻报类型错误 });在 5.4 之前overrides: PartialT会让 TypeScript 从defaults和overrides两个方向联合推断T如果overrides里少了一个字段推断出的类型反而变得“更宽”有时会引发连锁的隐式任何类型错误。用了NoInfer之后推断方向变成单向类型收窄和错误提示都稳定多了。3.4 用 NoInfer 时要注意的坑NoInfer虽然好用但不算银弹有几个注意点不要在所有地方都无脑包NoInfer如果你确实需要 TypeScript 从多个位置推断联合类型包了反而会把推断范围锁死。它只影响推断不影响校验当一个值既出现在推断位又出现在校验位时用NoInfer包住校验位编译器仍然会在调用时去校验该位置的类型只是不让它参与推导。这是个很关键的理解。某些泛型约束场景下NoInfer的表现不如预期特别是泛型参数是T extends SomeComplexType的时候NoInferT可能因为映射逻辑触发条件类型的延迟求值导致报错信息变得不够直观。遇到这种情况先在 playground 里快速验证一下。注意NoInfer这个工具类型已经被官方纳入 5.4 的内置类型声明lib.es5.d.ts不需要自己定义。如果你在 5.4 之前的项目里自定义过同名的类型升级后记得删掉否则会有冲突风险。4. Object.groupBy 与 Map.groupBy 的类型支持4.1 一个等了很久的 API 补充Object.groupBy和Map.groupBy是 JavaScript 新增的静态方法用来替代经典的reduce分组写法。这在运行时上已经铺了一段时间但 TypeScript 的类型声明一直没跟上。5.4 终于把类型加上了——前提是tsconfig.json里lib要设置成ES2024或更高。看一下用法const users [ { name: Alice, role: admin }, { name: Bob, role: user }, { name: Carol, role: admin }, ]; const byRole Object.groupBy(users, (user) user.role); // byRole 的类型{ [k: string]: typeof users[] | undefined }如果你之前用reduce手写过这种工具函数会体会到这个 API 的价值——少写不少模板代码。但也要注意类型上的一个“坑”Object.groupBy的返回值类型是Recordstring, T[] | undefined注意这个| undefined。为什么是undefined因为groupBy给每个分组返回数组时不会为不存在的键预留空数组。所以访问byRole[admin]时TypeScript 会告诉你它可能是undefined。4.2 实际使用时的类型处理技巧如果直接从byRole[admin]里取数组长度代码会变成const adminCount byRole[admin]?.length ?? 0;想避开这个undefined可以加一层过滤const roles Object.groupBy(users, (user) user.role); function getGroup(key: string): typeof users[] { const group roles[key] ?? []; return group; }或者干脆在取用时用?? []统一兜底。这个| undefined的设计虽然有点啰嗦但从类型安全角度看确实是负责任的行为。4.3 Map.groupBy 的差异化场景Map.groupBy和Object.groupBy最大的区别是分组键不限于字符串可以用任何类型包括对象引用。这在某些场景下非常有用比如按数量区间分组const items [1, 5, 12, 50, 3]; const buckets Map.groupBy(items, (num) { if (num 10) return small; if (num 100) return medium; return large; }); // buckets 类型Mapsmall | medium | large, number[] const smallItems buckets.get(small) ?? []; // number[]Map.groupBy的类型推断更聪明因为它用Map的键类型保存了分组键的联合类型。相比之下Object.groupBy的键是string索引限制更多。实操心得如果你的分组键来自联合类型用Map.groupBy的类型体验会好很多。如果只是普通字符串场景Object.groupBy足够用了。但要注意Object.groupBy的返回对象是一个“无原型”对象它没有hasOwnProperty方法直接用in判断键是否存在反而是更安全的写法。5. 模块解析与运行时支持Bun 用户笑了5.1 新模块选项与扩展名支持5.4 加入了对Bun运行时的正式支持。Bun的模块解析默认支持直接导入.ts文件而 TypeScript 之前一直不支持在 import 路径里写.ts扩展名。5.4 新增了一个moduleResolution: bundler下的allowImportingTsExtensions增强配合Bun风格的文件后缀处理让用Bun做开发运行时的项目不再需要额外的构建步骤。还有一点是module: esnext下对import defer的实验性支持。这个特性配合import defer语法import defer * as ns from ./module可以让模块的加载和实例化更进一步地延迟。这个目前在esnext模块目标下可以开启跟运行时结合还有待生态跟进。5.2 对 JSX 编译的新处理5.4 还修复了 JSX 在react-jsx模式下的一些类型和编译问题。特别是namespace属性的处理以及key属性的联合类型推断。这些改动对 React 项目来说体感不算大但如果代码里 JSX 元素的 props 跨度很复杂升级后偶尔能看到一些之前被漏掉的类型错误提示。6. 类型收窄行为改变带来的“连锁效应”6.1 收窄的扩展对类型守卫的增强5.4 的闭包收窄增强还带动了类型守卫和断言函数的表现改进。比如下面的场景function assertString(value: unknown): asserts value is string { if (typeof value ! string) { throw new Error(not a string); } } function process(value: string | null) { if (value null) { return; } const check () { assertString(value); }; check(); // 5.4 之前在这里 value 是 null | string // 5.4 之后这里 value 是 string console.log(value.toUpperCase()); }类型守卫在闭包内的收窄同样能保留到闭包调用之后。这个组合拳在一些校验逻辑集中、使用断言函数的项目里非常受益。6.2 对枚举和字面量联合的收窄改进5.4 在枚举类型和字面量联合的收窄上也有小幅增强。具体来说当使用switch或if判断一个枚举值时如果枚举值是string枚举编译器能更精确地收窄到具体的字面量类型。这个改进让很多枚举模式匹配的代码报错更准确了。7. 编辑器体验类型检查速度与错误提示的优化7.1 5.4 的类型检查提速点5.4 在性能上做的主要优化是把部分类型检查工作缓存到了node_modules/.cache和编辑器的增量构建中。这个对大型 monorepo 项目的感知比较明显。我在项目上实测的场景里tsc --noEmit的全量检查时间缩短了大约 8%~12% 左右。注意这是基于我个人项目的体感项目越大效果越明显。原因在于 5.4 改进了对*.d.ts文件的解析缓存策略以及对type-only import的追踪精度。如果项目里大量使用import type那么这个版本的增量编译体验会更好。7.2 快速修复与诊断的增强5.4 的编辑器集成还多了一些方便的小功能缺失的import type自动修复会自动识别哪些 import 只是类型用并建议加上type修饰符。更准确的 unused 变量提示对闭包捕获变量的 unused 判断更精确了减少误报。对复杂条件类型的错误信息改进不再直接输出一长串TS2322的嵌套类型堆栈而是给出更容易定位的提示。这些改进让 VS Code 里的 TypeScript 语言服务用起来整体比 5.3 时期“清爽”一些。少了不少需要手动忽略的波浪线。8. 从 5.3 升级到 5.4完整流程与避坑清单8.1 升级步骤升级本身不复杂官方迁移成本极低我还是按稳妥流程来升级 TypeScript 版本npm install -D typescriptlatest更新全局 CLI如果用了npm install -g typescriptlatest检查依赖兼容用npm ls typescript确认哪些包依赖了typescript这些包在 5.4 下是否有 peerDependencies 冲突。跑一次全量类型检查npx tsc --noEmit跑测试重点跑涉及泛型、闭包、类型守卫的模块。8.2 升级过程中的实际迷惑行为这里分享我升级时遇到的一个“真假报错”案例。项目里有一段代码依赖了 5.3 时期的行为——闭包捕获时类型被故意“扩大”了所以代码里用了一个非空断言来绕过。升到 5.4 之后那个非空断言变成了“多余”TS 开始报警告Unnecessary type assertion。这个不算错误但警告提示会让人紧张。处理办法就是直接删掉断言让代码更干净。这是 5.4 带来的正向副作用——你之前的 workaround 现在可能不需要了。还有一次我遇到Object.groupBy的类型声明冲突。当时项目里自己写了global.d.ts扩展了Object接口给groupBy定义了一份旧类型。升级后 5.4 内置的类型声明更强和自定义声明互相打架。解决方式是删掉自定义声明统一用内置的。9. 新功能速查表5.4 主要更新一览更新点类型影响范围备注闭包收窄保留类型推断增强中高频场景需要理解边界限制NoInfer 工具类型标准库新增泛型函数设计建议尽早掌握Object.groupBy类型声明新增数据分组场景需要 ES2024 libMap.groupBy类型声明新增复杂键分组键类型推断更友好Bun 模块解析支持运行时支持Bun 项目减少配置成本import defer 实验支持ESM 新特性性能敏感场景实验阶段慎用类型检查性能优化构建性能大型项目缓存策略改进编辑器快速修复增强开发体验所有项目自动 import type10. 常见问题与实战排查10.1 升级后闭包收窄“不生效”怎么回事很多人在 5.4 发布后测试闭包收窄发现某些写法下并不生效以为是自己理解错了。我排查了一圈大多数人其实踩了同一类坑闭包被作为回调传给了异步函数。function demo(value: string | null) { if (!value) return; // 这不会保留收窄因为 setTimeout 可能在赋值之后才执行 setTimeout(() { console.log(value.toUpperCase()); // error: possibly null }, 1000); }为什么因为setTimeout调度闭包执行的时机是“未知”的编译器无法推断它在最后一次赋值之前还是之后执行。凡是回调被“逃逸”到外部setTimeout、Promise.then、事件监听等收窄保留一律不生效。这与 5.4 的核心约束一致只有闭包在同步流程中被明确调用、且调用点确定在最后一次赋值之后才能保留。理解了这个机制排查思路就清晰了。看到闭包内收窄失效先检查闭包是否同步执行再检查变量是否在闭包定义后被修改。10.2 NoInfer 用了反而报错还有一个高频问题是NoInfer用在泛型约束为keyof的场景时会让类型检查变严报出一些之前没有的“冗余约束”错误。function getValueT extends string, K extends NoInferT(obj: RecordT, unknown, key: K) { return obj[key]; } getValue({ a: 1, b: 2 }, a); // 5.4 下正常如果 T 没有被正确定义NoInferT可能被推断成never于是key参数只能传never直接报错。这种场景要回头审视泛型参数的主推断源是否唯一。NoInfer适合“主推断源明确”的函数不适合所有参数都互相约束的复杂泛型。10.3 groupBy 在非 ES2024 lib 下报错如果Object.groupBy报“property does not exist on type ObjectConstructor”检查tsconfig.json{ compilerOptions: { lib: [ES2024, DOM] } }如果项目还在用ES2020或ES2021就得等lib升级后再用。或者用target: ESNext也可以让默认 lib 包含新 API 声明。10.4 一个隐藏的“性能大坑”我在一个比较老的项目里遇到升级后tsc内存飙升的情况后来定位到是import defer实验特性 moduleResolution: bundler的组合在增量构建时的缓存失效问题。这个组合在 5.4 还比较新如果项目规模很大不建议立即在生产 CI 里开启module: esnextimport defer。等 5.5 或 5.6 持续优化后再上不迟。11. 实际项目中的应用建议根据这次升级的观察如果你正在考虑升级到 5.4我给出的优先级是这样的如果项目里大量使用泛型函数、事件回调、复杂闭包逻辑升级收益最明显。闭包收窄保留 NoInfer能直接减少一批类型断言和中间变量。如果项目还在用lib: [ES2020]或者其他旧标准先评估lib升级的影响。改成ES2024可能带来类型声明变更尤其是Map、Set、Array等基础类型的一些泛型定义维度变化在小概率场景下会触发连锁的编译错误。如果项目是 monorepo类型检查提速的体感会强一些但还是要根据实际 CI 时间来定量判断。如果是纯后端 Node.js 项目Bun的支持可以先观望不影响现有运行时的升级。新工具类型的掌握建议先从NoInfer着手因为它能直接改善泛型函数设计的可用性。NoInfer和闭包收窄的联合使用可以让一些原本需要复杂类型体操的高级工具函数变得简洁且类型安全。说实话TypeScript 5.4 这个版本的新特性并不是每个都能立刻用上但闭包收窄和NoInfer这两个点是确定性提升。我在升级过程中最大的感受是之前为了绕过类型系统而写的大量 workaround在 5.4 下成了多余的存在。那些被注释掉的“// ts-expect-error”也能真正删干净了。如果你现在还在 5.0 或 5.1 停留5.4 是一个非常值得投入的中间站——它不会颠覆你的代码习惯但会把你日常写类型时最烦躁的几个卡点悄悄拆掉。最后分享一个小技巧升级完 5.4 之后把项目里所有as断言和非空断言!做个全局搜索逐个看一遍。里面相当一部分是因为旧版本收窄不够聪明才写上的现在直接删掉断言代码会更干净类型安全性反而更高。我这次清理完整整删掉了 40 多处不必要断言运行时的可读性提升了一个档次。