AI 辅助老项目 TypeScript 升级：从 TS 3.8 到 5.x 的完整实践

最近我花了一个周末，把一个 2019 年就开始积累的老 TS 项目从 TypeScript 3.8 + Webpack 4 + 遍地 any 的状态，捞到了 TS 5.x + moduleResolution bundler + 严格模式。推动我完成这事的核心动能，不是毅力，是 VS Code 生态里刚冒头的 AI 自动升级工具。

这工具不叫"重构插件"，定位比那大得多：它扫描整个 JS/TS 项目的语法树、配置、依赖关系，然后基于 AI 批量生成升级补丁。你不需要逐个人肉去改 var 改 let、给 Promise 补类型、把 import 语法从 CommonJS 搬到 ESM，它能先啃下大头，你只负责 review 它改不懂的边角料。

这篇不是什么官方评测，就是我实际操作一个真实老项目的完整记录。里面有这个工具的原理拆解、完整升级流程、几个特别容易翻车的隐藏角落，以及升级后我用了哪几道关卡来挡住 AI 误改。如果你手里也压着一个不敢动的老项目，这篇应该能帮你少走不少弯路。

1. 老旧 JS/TS 项目的技术债到底压在哪几层

先说个让我很感慨的事实：大部分老旧 JS/TS 项目的技术债不是靠代码堆出来的，是靠版本断层堆出来的。你项目里真正恶心的那几千行代码，往往不是"本来就写得烂"，而是"用旧语法和旧配置写完后，再也没人敢动"。

1.1 从 TS 3.x 到 TS 5.x，中间隔了一整个时代

拿我那个老项目举例，它锁死在 TypeScript 3.8.3，表面原因是"当时团队觉得稳定"，真实原因是"升级过一次，类型报错铺天盖地，就放弃了"。这一放弃，直接错过了从 3.8 到 5.x 的四次大版本迭代。这期间的语法和类型能力变化，几乎是两个世界。

而 JavaScript 老项目那边情况更典型：大量 var、回调地狱、手写 Promise 队列。不是开发者当年水平差，是 ES5/ES6 时代的工具链只能写那种代码。这些代码放到今天，可读性和可维护性都已经跌到谷底。

1.2 配置债和依赖债往往比代码债更难还

升级老项目时，真正让人崩溃的不是 .ts 文件里的代码，而是三个"隐形炸弹"：

第一是 tsconfig.json。旧配置里常见 "target": "es5"、"module": "commonjs"、"strict": false、"noImplicitAny": false。这意味着编译器一直在纵容代码里的 any 和隐式类型错误，多年攒下来的类型垃圾都在这里沉淀。改这些配置项，立刻冒出几百条类型报错。

第二是 @types 包和依赖库的版本错位。老项目里的 @types/react 可能还停在 16.x，而 React 已经跑到 18/19；@types/node 版本跟 node_modules 里的声明对不上，全局类型已经失真。AI 升级工具扫描后，第一轮报出来的问题大头往往不是业务代码，而是这些类型声明错位。

第三是构建工具链脱节。Webpack 4 的 ts-loader 或者更老的 awesome-typescript-loader，对现代 TS 的兼容性已经接近阈值。升级 TS 版本后，经常是"代码没错、构建挂了"。这类问题不是 AI 工具能直接修的，需要配合升级构建链。

2. AI 升级工具的工作原理与能力边界

在动手升级之前，我花了不少时间研究这个工具到底是怎么工作的。搞懂它的原理，你才知道哪些步骤可以放心交给它，哪些环节必须自己盯。

2.1 不是字符串替换，是"AST 精读 + LLM 推演"的双层流水线

最开始我以为这类工具无非是做个正则替换，比如把 var 改成 let、把函数改成箭头函数。真用了才发现完全不是一回事。它跑的是双层流水线：

第一层是 AST（抽象语法树）级静态分析。工具会把项目里每个 .ts、.tsx、.js 文件解析成语法树，识别出所有"可升级点"：旧语法、类型缺失、模块系统不兼容、配置过期等。这一步是确定性的，不涉及 AI 判断，保证不会漏掉任何符合规则的问题。

第二层才是 LLM 参与的部分。对于静态分析无法处理的场景，比如一个 any 类型到底该推断成什么、一段回调风格代码怎么重构才算保留原意、一个复杂泛型要怎么调整……这些需要"理解代码意图"的问题，工具会交给大语言模型推演生成补丁。

我的理解是：AST 分析负责"在哪里改"，LLM 负责"怎么改才不改坏语义"。前者保证覆盖率，后者保证准确率。这个设计比纯 AI 生成靠谱得多——因为纯 LLM 面对大型老项目时，最容易犯的问题就是漏改或者改过头。

2.2 它和传统 codemod、ts-migrate 的本质区别

老一代的迁移工具里，jscodeshift 和 Airbnb 出的 ts-migrate 其实已经能处理不少机械性重写了。ts-migrate 的玩法是：先把 TS 编译错误找出来，再用 codemod 做批量替换，最后拿不准的地方全部转换成 any 先让项目跑起来。说白了，那是用 any 换取迁移速度。

这套新工具的思路不一样，它明确把"unsafe any"列为要消除的目标，而不是逃生舱。AI 会尝试推断具体类型，只有推断置信度足够高的时候才会直接写进补丁；置信度不足的，会以"待确认"的方式在报告里标注出来，等人工决策。

另外，传统 codemod 只能处理它被编程好的规则，比如"把所有 var 换成 let"。但真实项目里，一个改动往往牵连多个文件。比如把一个 CommonJS 模块改成 ESM 导出，不只是改 module.exports = 那一行，还会影响所有 require 它的文件。AI 工具在这类跨文件联动的场景里，处理能力天然强于规则引擎。

2.3 能力边界：它擅长什么，不擅长什么

实测下来，工具的能力边界非常清晰：

擅长的是语法现代化、模块系统迁移、配置项更新、重复模式重构。这些属于"有标准答案"的改动，AI 处理得又快又稳。

中等水平的是类型推断补齐。如果一个 any 的真实类型能从上下文明显看出来，比如 const x = JSON.parse(str) 然后被当数组用，它能推断成 any[] 甚至更精确的结构。但如果是那种传了三四层、经过各种中间处理的变量，AI 也会犯懵。

不擅长的是依赖库的 breaking change 适配。比如老项目用的某个内部 UI 库在新版本里改了组件 API，这种"外部语义变化"它推断不出来。它有看代码的能力，但没法阅读你 node_modules 里那个库的升级文档。

3. 实操记录：把一个 2019 年的老项目捞回现代 TS

下面进入正题，我用一个具体项目完整走了一遍升级流程，把每个环节都记录下来。你照着这个路径走，基本能避开大部分坑。

3.1 准备阶段：先立好退路，再让 AI 动手

升级老项目最忌讳的就是闷头开干，改到一半发现回不去了。我动手前做了两件事：

第一，给当前状态打了 Git 标签。升级前把主分支拉到 release/legacy，再开一个工作分支 refactor/ai-migrate。这样 AI 改出来的任何文件，我都能用 git diff 看清楚到底改了什么，随时可以 git checkout 单文件回滚。

第二，跑通一遍基线构建和测试。升级前先确保 npm run build、npm test 在旧状态下是绿的。这一步至关重要——如果基线就是红的，升级完成后你根本无法区分"AI 改坏了"还是"之前就坏了"。

这个项目本身的情况可以参考一下：React 16.13 + TS 3.8.3 + Webpack 4.41 + 40 多个 TS 文件 + 近万个类型报错（在 strict: false 下也有一大堆）。其中约 60% 的代码还是 .js 文件，需要用 allowJs 才能编过。属于非常典型的大龄项目。

3.2 扫描阶段：先看报告，不要急着让 AI 改

这个工具的第一步是跑全项目扫描，生成一份迁移报告。报告会按风险等级把发现的问题分类：

• safe 级别：纯机械改动，比如 var 到 let/const、类型导入位置调整、无效类型断言清理。这些可以全自动批量应用。
• suggested 级别：建议性改动，比如把显式 any 改成推断类型、把函数参数解构补上类型。AI 会生成补丁，但需要人工确认。
• manual 级别：工具明确标注"我需要人工介入"。比如某个模块的导出方式重构会牵扯到循环依赖、某个类型系统层面的结构性调整。

我第一次跑扫描，报告列了 300 多个待处理事项。看着吓人，但其实 safe 级别的占了六成以上，真正需要逐个人工决策的不到 30 项。

3.3 分批执行：从安全到危险，逐层递进

我没有让工具一次性把所有补丁全打上去，而是按风险从低到高分了几个批次：

第一批跑的是 safe 级别。点一下应用，脚本自动把所有 .js 文件里的 var 替换成 let/const、把类型导入整理好、清理无用的类型断言。这一批改动完全无脑，但效果立竿见影——代码看起来立刻"现代"了不少。

第二批跑的是 tsconfig 基础配置升级。工具把 target 从 es5 升到 es2020，module 从 commonjs 改成 esnext，然后开启了 strict 模式。当然，开 strict 的瞬间，项目里立刻炸出上百条类型错误——这是预期内的。工具开始用 AI 逐个处理这些新的报错。

第三批才是真正让 AI 发挥价值的环节：处理那些 suggested 级别的类型推断和模块系统迁移。比如老代码里有个函数：

ts复制// 升级前
function fetchData(url: string, callback: any) {
  request(url, (res: any) => {
    callback(res.body);
  });
}

AI 生成的升级版本是：

ts复制interface ApiResponse {
  body: unknown;
  statusCode: number;
}

function fetchData(
  url: string,
  callback: (data: ApiResponse) => void
): void {
  request(url, (res: ApiResponse) => {
    callback(res);
  });
}

虽然 unknown 有点保守，但方向是对的，代码意图保住了，类型边界也建立起来了。这比 ts-migrate 一顿操作猛如虎最后全部变 any 强太多。

3.4 全程盯住 diff，不放过任何一行修改

这是整个流程里我最想强调的一点：AI 工具生成的补丁，我用 git diff 逐文件看过。40 多个文件，我花了一个下午去 review，一个都没跳过。

看 difF 的时候关注点有三类：一是看 AI 有没有改变代码逻辑（比如把 === 改成 ==、把 || 改成 ?? 导致默认值逻辑变化）；二是看类型推断有没有"过度自信"（明明有多重可能，它硬选了一个）；三是看它有没有删除"看起来没用但运行时确实需要"的语句。

实测下来，AI 工具在绝大多数 diff 里表现是称职的，但确实有一些改动是不能直接接受的。我有一个函数，AI 把 if (a) { return b; } return c; 简化成了 return a ? b : c;，逻辑没变，能接受。但另一个地方，它把 undefined 的默认值处理改成了 ?? 操作符，导致 null 传入时的行为发生了变化——这在旧代码逻辑里是不允许的。

4. 最容易翻车的四个隐蔽角落

升级过程中的多数问题都集中在几个特定的场景，单独拿出来说一下。这些都是我实际踩过、或者认真推演过风险的坑。

4.1 any 类型推断的"过度自信"陷阱

AI 工具处理 any 时有一个倾向：如果一处代码看起来"明显"属于某种类型，它会毫不犹豫地把类型写死。但有些"明显"其实是假象。

举个例子，有个变量在旧代码里被 JSON.parse 赋值，紧接着被取出一堆字段来用。AI 据此推断了一个非常具体的 interface，包含所有这些字段。表面看没问题，但这段代码的来源其实是一个外部 API 的响应，响应结构由后端决定，前端未必总能拿到完整字段。AI 把它推断成"必然包含这些字段"的结构类型之后，运行时一旦缺字段，类型检查不会报错，但页面会白屏。

处理方式很朴素：凡是数据来自外部边界（接口响应、用户输入、文件内容），我一律把 AI 推断出的具体 interface 降级成"核心字段 + 索引签名"或者 Record<string, unknown>，不接受过度自信的固化类型。

4.2 CommonJS 到 ESM 迁移时的默认导出陷阱

工具在把 module.exports = xxx 转成 ESM 时，有一个非常容易踩的坑：原始代码里 module.exports = { a, b, c } 这种写法，被 AI 转成 export default { a, b, c }，而正确做法应该是 export { a, b, c }。

这两者的差异在于消费端。如果另一个文件里写的是 import utils from './utils'，它期望的是默认导出；如果写的是 import { a } from './utils'，它期望的是命名导出。升级工具在判断"导出对象是被默认导入还是命名导入"时，经常会出现偏差，尤其是当一个文件同时被两种方式引入的时候。

我在升级过程中遇到三个模块都出现了这个情况，修法也简单：跑完工具后，全局搜索所有 require( 和 import ... from 的引用关系，逐个确认导出的形式是不是跟消费端匹配。

4.3 装饰器与元数据反射在 TS 5.x 下的行为变化

这个坑主要影响用过 NestJS、TypeORM 这类依赖装饰器元数据的项目。TypeScript 5.0 对装饰器做了标准化，但标准化的装饰器语法和旧版实验性装饰器有一个关键差异：旧版 emitDecoratorMetadata 生成的设计类型元数据是基于"变量声明时的类型"，新版标准装饰器不再自动生成这些元数据，需要额外的 polyfill 或显式传递。

如果你的老项目里有用到 reflect-metadata 和自定义装饰器做依赖注入或参数校验，升级 TS 版本后这些能力会静默失效。AI 工具在升级过程中会帮你改写装饰器语法，但它不会自动帮你补上元数据生成逻辑。

我的建议是：升级前先搞清楚项目里哪些装饰器是"运行时依赖"的。如果确实依赖 design:type 和 design:paramtypes，升级后要在 tsconfig 里保留 "experimentalDecorators": true 和 "emitDecoratorMetadata": true，或者显式迁移到标准装饰器并引入 reflect-metadata 的适配方案。

4.4 全局类型声明与 .d.ts 文件的隐式丢失

老项目里往往会有 global.d.ts 或者 types/ 目录下的声明文件，用来声明全局变量、window 扩展属性、非 TS 模块的类型。这类文件经常在升级过程中被 AI 误判为"冗余代码"——因为它们在大多数编译路径下不直接被 import，AI 扫描器容易认为它们没有被引用而建议删除。

但这类文件的删除后果是灾难性的：项目里几十处 window.someGlobal 的调用会瞬间失去类型定义，甚至编译直接失败。而且因为错误信息散布在各个调用点，不会有人第一时间想到是声明文件被删了。

我的处理方式是：动手升级前，把所有 .d.ts 文件提前加入 .gitignore 的"保护名单"，具体做法是给它们加一行注释标记，并通知工具跳过这些文件。这类全局声明文件，建议升级完成后人工重新审查一遍是否仍与代码匹配，而不是让 AI 随手处理。

5. 升级完成之后：五道关卡挡住 AI 误改

AI 工具把所有补丁应用完成，TypeScript 编译错误清零，这不代表项目已经可以上线了。编译通过只是最低标准，我用下面五道关卡做最终验证，确保 AI 的改动没有引入运行时行为偏差。

5.1 从编译到构建产物的全链路比对

对于前端项目，我建议做一次"升级前后构建产物差异分析"。做法是：在升级前的旧分支上打一个 npm run build，把产物目录打包留存；然后切换到升级后的分支，再次构建，对两次产物做目录级别的 diff。

如果 AI 只是改了类型声明、语法糖、模块系统，理论上构建产物的体积和内容不应有本质变化。如果产物 diff 中出现了"多余的大段代码"或"缺失了某段初始化逻辑"，说明升级过程中有语义变化被偷偷带进来了。这一步能过滤掉绝大多数类型系统层面的"潜在运行时事故"。

5.2 单元测试与关键路径的回归验证

有测试先跑测试。但如果老项目测试覆盖率本身很低，就需要额外做关键路径的手工冒烟。

我当时的做法是：把项目核心业务链路（登录、数据列表加载、详情页跳转、表单提交）在本地起服务跑了一遍，用浏览器开发者工具观察 Console 有没有报错、Network 请求有没有异常。重点看那些被 AI 改过类型推断的模块，比如前面提到的 JSON.parse 数据源、外部 API 消费点。

这一步耗时不多，但价值极高。很多类型层面的问题在编译期根本暴露不出来，只有运行时才能发现。

5.3 Lint、格式化和静态检查兜底

升级完 TS 版本后，旧的 ESLint 配置很可能部分失效（比如 @typescript-eslint 规则集的版本和 TS 版本不匹配）。我会顺手把 ESLint 相关依赖升级到兼容版本，然后让 lint 工具全量跑一遍，修复它报出的规则问题。

这里要注意，@typescript-eslint 的 recommended 规则集在不同大版本之间有明显差异，升级后可能会出现大量"新规则暴露出的老问题"。这些一般是低风险的代码风格问题，但值得过一遍。

5.4 类型错误"清零"的验收标准

我所说的清零，不是指 strict: false 下的编译通过，而是在 strict: true、noImplicitAny: true、strictNullChecks: true 的前提下，tsc --noEmit 完全无错误。启动严格模式后，旧的隐藏问题基本都会被曝光，AI 工具会把它们一个个解析处理掉，但你要做的验收是确认它没有把任何一个报错用"粗暴的 any"或"不安全的类型断言"压下去。

验收方法很简单：在项目里搜索 any 关键字，逐个检查新增的 any 和 as unknown as。升级后项目里仍然存在 any 是可以接受的，但必须确保它们不是 AI 为了"让编译过"而新造出来的。正常升级后的代码，any 数量应该明显减少，而不是增加。

5.5 代码评审视角的"语义保真"检查

最后一道关卡是带着"语义保真"的视角做代码评审。AI 升级工具擅长语法和类型层面的转换，但它不真正理解业务含义。如果一个函数叫 submitOrder，内部逻辑从"提交订单"变成了"提交订单并触发通知"，这种改动在纯类型视角下根本看不出来。

我把升级后 diff 里所有涉及逻辑改动的文件挑出来，重点看三类操作：一是条件表达式是否被合并或拆分；二是 &&、||、?? 之间的替换；三是循环和回调是否被重构成了新写法。这三类操作最容易在"代码等价"的外衣下悄悄改变执行时序或求值次数。

6. 一次升级后的复盘：工具的意义不在省时间

升级完成的时候，我自己也愣了一下。原本以为需要两三周才能啃下的项目，实际在 AI 工具的辅助下，周末两天加上工作日两个晚上就搞定了。要说这工具最大的价值，我觉得不是省下了多少人工修改的时间，而是它把"这件事的门槛"拉低了。

过去一个老项目升级到新 TS，最大的障碍不是工作量，是"不知道从哪里开始"。几百个错误、几十个文件、改了这头炸了那头，无从下手才是劝退人的根源。AI 工具给你一份分级清单，把"从哪开始"这个问题直接解决了。它未必比人更会改代码，但它能帮你在漫无边际的代码库里建立秩序。

我更想说的是，AI 自动升级工具不能替代人做技术决策。项目最终选择哪种模块系统、严格模式怎么开、哪些技术债留给未来，这些决定还是得有经验的人来拍板。工具做了它该做的事，剩下的判断和把关，才是工程师真正的价值所在。

不过话说回来，如果有下一次升级需求，我会从第一天就把这类工具纳入流程。不是因为它多聪明，而是因为它让"升级"这个动作从"开天辟地的工程"变成了"有章法的例行维护"。时代的进步大概就是这样——以前觉得遥不可及的事，后来不过是点几下按钮的事。