TypeScript 编译器升级：用严格选项识别隐蔽的兼容性变化

TypeScript 的版本升级经常伴随更准确的类型推断、更新的语法支持和更严格的诊断。它们有助于发现问题，也会让原先能够通过检查的代码暴露出假设不完整之处。与其急着关闭报错，不如把诊断当作一次梳理边界的机会。由于编译器选项和生态声明包都可能变化，本文只给出可重复执行的方法；具体选项含义应以当前版本文档与发布说明为准。

固定基线，避免把多项变化混在一起

升级前先记录 Node.js 版本、包管理器版本、typescript 版本以及实际使用的 tsconfig 文件。许多仓库通过 extends 继承基础配置，编辑应用层文件并不一定等于改变最终配置；可使用编译器提供的配置展示能力确认解析结果。第一轮只更换编译器版本，暂不同时升级构建插件、框架和类型声明包。这样，新增错误更可能来自类型系统变化，而不是由一串依赖更新共同造成。

按错误类别处理，而不是逐行压制

面对新增诊断，可先将其分为三类：真实的空值或越界风险、第三方声明不准确、以及项目刻意采用但编译器难以表达的模式。第一类应优先修正代码，例如在读取可选字段前完成收窄；第二类应核对依赖版本与运行时 API 是否匹配；第三类才考虑小范围断言，并把断言靠近边界而非扩散到业务逻辑。若大量错误集中在空值处理，可评估是否逐步启用或强化 strictNullChecks，但不要为了短期安静而在全局关闭严格模式。

检查声明文件与运行时是否同步

TypeScript 能验证静态约束，却不能替代运行时兼容性测试。一个库的类型定义可能先于或晚于实际实现更新，因此升级后应选取关键请求、解析逻辑和错误分支做一次实际执行。浏览器、Node.js 与边缘运行环境对全局对象和模块解析的支持也未必一致；这类差异可结合JavaScript 运行时差异：同一代码为何在不同环境表现不同理解。若服务运行在 Node.js 中，还应把编译器升级与Node.js 版本选择：运行时、包管理器与部署镜像一起看中的镜像检查放在同一变更记录里。

把配置变化写成可审查的意图

moduleResolution、target、lib 和 verbatimModuleSyntax 等选项会影响发射代码、模块查找和可用的环境声明。升级时不要复制网络片段直接覆盖配置，而应说明每项调整解决了哪个现象，并通过最小示例观察输出。例如，改变模块解析策略后，应检查测试、开发服务器和生产构建是否解析到同一入口；改变目标语法后，应核对旧环境是否仍由构建链负责转换。涉及包元数据时，依赖锁定文件：版本更新后怎样保持构建可复现可帮助避免本地与构建机拿到不同的声明包版本。

结论：把更严格的检查变成长期收益

TypeScript 升级的目标不只是消除红线，而是让类型、配置与真实运行环境重新对齐。固定升级范围、分类处理诊断、验证声明和实现、审查最终配置，能够使每一次编译器更新留下可解释的结果。若项目还使用 Kotlin 构建链，可参考Kotlin 与 Gradle 协同升级：处理编译插件版本边界，其中关于插件边界的思路同样适用于前端工程。