大版本升级别一口气赌上去:用 AI 做框架升级的检查清单
大版本升级不是改个版本号,而是旧写法到期了。本文按 React 19 与 Next.js 16 官方升级文档讲:升级前的基线、breaking change 清单、codemod、人机分工、回归三层与上线后第一周,附上线检查表。

先把这篇的边界说清楚。站里已经有一篇《依赖升级与维护期 SOP》,讲的是日常依赖维护:小版本怎么升、补丁怎么打、锁文件怎么管。那篇讲的是“经常做的例行事”。这篇讲的是另一件事:框架跨大版本的一次性迁移——从 React 18 到 React 19、从 Next.js 15 到 Next.js 16 这种,带着 breaking change(破坏性变更)来的升级。例行升级可以慢慢来、出了问题回退一个补丁号就行;大版本升级是“一锤子买卖”,升错了,整个应用可能跑不起来。还有一篇《API 版本管理与废弃 SOP》讲的是你自己的 API 怎么废弃旧版本,那是“你让别人升级”;这篇讲的是“别人让你升级”,方向正好反过来。两件事别混在一起。
下面用到的“小卖部”是一个虚构的练手项目:一个给小区小卖部用的下单小程序,能下单、能查库存、能看今日流水。本文所有以它为例的操作、命令和数字,都是为了讲清楚做法编出来的,不是真实记录。所有关于 React 19 与 Next.js 16 的规则、命令和变更内容,都来自两家的官方升级文档,来源见每篇的 meta 信息与 evidence 记录。别的框架也有自己的升级文档,思路相通,但变更清单不一样,照搬之前先对一下它自己的升级指南。
升级之前先做三件事:别一上来就改版本号
大版本升级最常见的死法,是直接把 package.json 里的版本号改掉、装包、跑起来、看哪里红了再修。听起来爽快,实际上是把所有问题一次性引爆:编译报错、类型报错、运行时报错、测试报错全混在一起,分不清哪个是升级引起的、哪个是本来就有的。升级之前,先做三件事,把爆炸半径缩到最小。
第一件:先升到过渡版。React 官方升级指南的第一条建议就是:先升到 React 18.3。这个版本和 18.2 的功能完全一样,唯一的区别是:它会在控制台里把 React 19 要删掉的东西一个一个警告出来——ReactDOM.render、函数组件的 defaultProps、字符串 ref、ReactDOMTestUtils.act,用到了就会报。先把这些警告清干净,再升 19,升级当天要面对的问题就少了一大半。过渡版的意思就是“先听警告、再动手”,别跳过这一步。别的框架也有类似的过渡版:Next.js 的做法是先在旧版本上把废弃警告清掉,再跨大版本。
第二件:冻结功能开发。升级期间别再往里加新功能。升级分支只干一件事:升级。功能分支与升级分支同时改同一批文件,合并的时候冲突能把人逼疯。跟团队约好:升级分支存活期间,新功能先排队;非改不可的 bug 修,先在主分支修、再合进升级分支,别反过来。一个人做的小项目也一样:升级之前先把手头的功能收尾、提交干净,再开升级分支。升级分支的提交历史要干净:codemod 的提交、人工改的提交、修测试的提交,分开提交,别混成一团看不懂的提交。
第三件:先把基线测绿。升级之前,测试套件、类型检查、构建,三样全绿,并且把结果记下来。基线不绿,升级之后红了,你分不清是升级弄坏的、还是本来就坏的。基线就是“升级前世界的样子”,升级之后的所有判断——“这次改动有没有弄坏东西”——都要拿它当参照。测试本来就没跑过的项目,先别升级:先把最核心的几条主流程测起来(下单、查库存、看流水,三条就够),有了这三条,再谈升级。没有基线就升级,等于蒙着眼睛拆炸弹。

先读 breaking change 清单:知道什么会坏,再动手
大版本升级不是“装个新包”,而是“旧写法到期了”。动手之前,先把官方升级文档里的 breaking change 清单读一遍,知道什么会坏,再动手。这份清单就是你的任务清单:每一项后面,都对应着要改的代码。拿 React 19 和 Next.js 16 这两个官方文档里的清单当例子。
React 19 删掉的东西,都是早就警告过几年的老写法。第一,ReactDOM.render 和 ReactDOM.hydrate 没了,改成 createRoot 和 hydrateRoot。这两项从 React 18 就开始废弃,官方文档给的替换写法只有三行,codemod 也能自动改,是最没风险的一项。第二,函数组件的 propTypes 和 defaultProps 没了:propTypes 检查会被静默忽略,写了等于没写;defaultProps 要换成 ES6 默认参数。注意“静默”两个字:它不会报错,只是悄悄不工作——这是最危险的一类变更,测试都不一定抓得住。类组件的 defaultProps 还留着,因为类组件没有 ES6 默认参数这个替代品。第三,字符串 ref、findDOMNode、旧版 Context(contextTypes 与 getChildContext)、React.createFactory、react-test-renderer/shallow,全部删掉,分别换成回调 ref、DOM ref、新版 Context、JSX、直接装 react-shallow-renderer 这个包。第四,测试工具 react-dom/test-utils 里的 act 搬到了 react 包里,其余工具函数直接删掉。第五,渲染里抛错不再重复抛出:没被错误边界接住的错,报给 window.reportError;被接住的错,记到 console.error。如果你生产环境的错误上报依赖“错会被重复抛出”这个行为,得在 createRoot 里配 onUncaughtError 与 onCaughtError 这两个新钩子。
Next.js 16 的清单,重点在三处。第一,Turbopack 默认开启:next dev 与 next build 不再需要 --turbopack 参数。项目里如果还留着自定义 webpack 配置,构建会直接失败来防止配错——要么把 webpack 配置迁到 Turbopack 的配置项,要么用 --webpack 明确退出 Turbopack。第二,运行环境收紧:Node.js 最低 20.9,18 不再支持;TypeScript 最低 5.1。升级之前先看一眼部署环境的 Node 版本,别等部署那天才发现服务器上的 Node 还是 18。第三,异步请求 API 的同步访问彻底移除:cookies()、headers()、draftMode(),还有 params 与 searchParams,在 Next.js 15 里还留着一段同步兼容期,到了 16 就只能异步访问了。官方文档给了专门的 codemod(next-async-request-api)和类型生成工具(npx next typegen),这部分别手改,让工具改。
读清单的时候,顺手做一件事:把清单里的每一项,在自己的代码库里搜一遍。ReactDOM.render 出现几次?defaultProps 出现几次?cookies() 同步调用出现几次?搜出来的数量,就是这次升级的工作量。搜不到的项,先打勾跳过;搜得到的项,一项一项列进任务清单。清单读完、工作量数完,再决定“这次升不升、什么时候升”。没读清单就升,等于不知道自己要面对什么。
codemod 先跑:让机器改机械的部分
官方升级文档里反复出现的一个词是 codemod:一段读你的代码、找到旧写法、自动改写成新写法的脚本。React 19 的升级配方是一条命令:npx codemod@latest react/19/migration-recipe。它一次性打包了五个改写:ReactDOM.render 换成 createRoot、字符串 ref 换成回调 ref、act 的 import 从 react-dom/test-utils 搬到 react、useFormState 改名 useActionState、propTypes 转 TypeScript 类型。Next.js 16 的升级 codemod 是 npx @next/codemod@canary upgrade latest,能处理 Turbopack 配置位置、next lint 迁到 ESLint CLI、旧 middleware 约定迁到 proxy、去掉已经稳定的 API 前面的 unstable_ 前缀。Next.js 官方文档还给了另一条路:用 coding agent 升级(npx next@canary upgrade --agent=latest),让 agent 按官方迁移指南一步一步改、一步一步验证。
跑 codemod 之前,先提交一次。codemod 会改你的文件,改之前工作区必须是干净的——这是官方文档和各家教程共同的提醒。跑完之后,别直接提交,先看 git diff:codemod 改了哪些文件、每处改得对不对。codemod 擅长的是“简单、可预测的改写”,比如把 ReactDOM.render 换成 createRoot;它不擅长任何需要人做决定的事。审 diff 的时候,重点看三类地方:改得对不对(有没有把不该改的也改了)、改全了没有(同一个旧写法是不是有的文件改了、有的文件漏了)、改完之后代码还通顺吗(有的 codemod 改完会留下别扭的写法,顺手理一下)。
还要记住 codemod 改不了什么。React 19 升级指南里明确写着:defaultProps 的静默失效,codemod 不管;类型层面的改动,要另外跑 npx types-react-codemod@latest preset-19 ./src。Next.js 16 的升级 codemod 也一样:它不会跑所有的迁移 codemod,如果项目还在用 Next.js 15 兼容期的同步 params、searchParams、cookies(),得另外跑异步请求 API 的 codemod。codemod 是“很快的第一稿”,不是“最终答案”。把它当第一稿用:先让它改,再人工审、人工补、人工收尾。
拿最常见的 ReactDOM.render 当例子,codemod 改完之后应该是这个样子,审 diff 的时候就按这个样子对:
// 改之前:React 18 的旧写法
import { render } from 'react-dom';
render(<App />, document.getElementById('root'));
// 改之后:React 19 只能这么写
import { createRoot } from 'react-dom/client';
const root = createRoot(document.getElementById('root'));
root.render(<App />);
审的时候别只看“改没改”,还要看“改完之后入口文件还剩什么”:旧的 import 有没有删干净?root 有没有被别的代码复用(比如卸载的时候调 root.unmount(),而不是已经删掉的 unmountComponentAtNode)?入口文件是整个应用的起点,这里改错了,应用连第一屏都出不来。codemod 改完入口文件,一定要亲手跑一次开发服务器、亲眼看到第一屏出来,再往下改。
让 AI 干什么、不让它干什么:升级里的人机分工
框架升级是最适合用 AI 的场景之一,也是最容易被 AI 带偏的场景之一。分工划不清,AI 会把升级做成“看着全改了、其实处处是坑”。先把分工写下来,贴在升级分支的说明里。
让 AI 干四件事。第一,机械改写:按 breaking change 清单,把旧写法批量换成新写法,codemod 覆盖不到的边角也让它补。第二,生成回归清单:读一遍官方升级文档,把“可能受影响的地方”列出来,标上在自己代码库里的位置。第三,解释报错:构建报错、类型报错,一条一条贴给 AI,让它说清楚“这个错是什么意思、对应清单里的哪一项”。第四,写测试补丁:针对改动过的地方,补几条“旧行为 vs 新行为”的对照测试。
不让 AI 干三件事。第一,不让它决定“升还是不升、这次升到哪”。升到 19 还是钉在 18.3、Turbopack 迁过去还是先用 --webpack 顶着,这些是取舍问题,要人根据项目情况定,AI 不知道你的部署环境、不知道你的用户量、不知道你的排期。第二,不让它悄悄改行为。AI 改代码的时候,最爱顺手“修”掉它觉得别扭的地方:一个它不认识的旧 API,它可能直接删掉、而不是按清单替换。审 diff 的时候,凡是清单之外的改动,一律打回去问清楚。第三,不让它替你做上线决定。“测试全绿了,可以上线了”这句话,只能由人说。AI 不知道线上真实流量的样子,也不知道回滚要花多长时间。
还有一条铁规:AI 的每一次改动,都要能通过基线测试。改完一批、跑一遍测试,绿了再改下一批;红了,先停下来,把红的原因弄清楚再继续。别等 AI 把三百处全改完了再跑测试——到时候红了一百条,分不清哪一批改坏的。小步改、小步测,是升级里最省时间的办法,听起来慢,做起来最快。
回归三层:类型、测试、人工走一遍
升级改完之后,验证分三层,缺一层都不能上线。第一层是类型检查:tsc --noEmit 必须全绿。React 19 的类型变化不少:useRef 不再允许不传参数、ref 回调不能再隐式返回清理函数、@types/react 也要同步升到 19。类型检查是成本最低的一层,跑一次几十秒,能拦住一大半问题。第二层是测试套件:单元测试、集成测试全跑一遍,和升级前的基线结果逐项对。新增的红项,一项一项查:是升级改坏的,还是测试本身写死了旧行为?测试里写死旧行为的(比如断言了 ReactDOM.render 还在),按新行为改测试;升级改坏的,修代码。第三层是人工走主流程:下单、查库存、看流水,三条主流程在浏览器里亲手走一遍。自动化测不到的东西——页面闪不闪、按钮点下去有没有反应、弱网下会不会卡住——只有人走一遍才知道。
三层之外,还有一个容易漏的验证:构建产物。升级之后打一次生产构建,看包体积有没有异常变大、看有没有新冒出来的警告。Next.js 16 默认 Turbopack 之后,构建日志里的警告要一条一条过:有的警告是“你的 webpack 配置被忽略了”,有的警告是“某个插件不兼容 Turbopack”。构建警告不是装饰,升级期间的每一条新警告,都值得停下来看一眼。
如果项目有灰度条件,别一次性全量上线。先上一小部分流量,盯半天错误日志,没新增报错再全量。没有灰度条件的小项目,至少做到“可回滚”:上线之前,把旧版本的部署包留好、把回滚命令写好、把数据库有没有不兼容的变更确认好。回滚预案不是“觉得会失败才准备”,而是“不管觉得会不会失败都准备”。升级当天最贵的东西不是修 bug 的时间,而是“发现坏了、却不知道怎么回去”的时间。
升级之后的第一周:盯着三样东西
上线不等于升级结束。很多升级问题不会在上线那一刻冒出来,而是在接下来的一周里慢慢露头:某个不常用的页面第一次被打开、某个定时任务第一次跑、某个用户第一次用了一个冷门功能。升级之后的第一周,盯着三样东西。
第一样是错误日志。把升级前后一周的错误量拿出来比:新增了哪些错误、每种错误每天出现几次。重点看两类:升级清单里提到过的变化引起的错(比如渲染错误上报方式变了之后,日志里是不是多了以前没见过的错误类型),和“静默失效”引起的错(某个功能悄悄不工作了,用户不报错、只是用不了,这种错不会出现在日志里,得靠第二样东西发现)。错误量比升级前高,就先别急着关升级分支,留着它,修起来方便。
第二样是用户反馈。升级之后的第一周,主动问一圈最活跃的用户:有没有哪里用起来不对劲、有没有哪个按钮点了没反应、有没有哪个页面比以前慢。用户反馈是发现“静默失效”的唯一办法:代码不报错、测试全绿,但功能就是不对了,只有用的人知道。收到反馈先别急着修,先确认“这是升级引起的,还是本来就这样”——拿升级前的版本对照一下,对照的方法就是前面说的基线。
第三样是性能指标。首屏时间、包体积、接口耗时,三项和升级前比一比。Next.js 16 默认 Turbopack 之后,构建快了,但运行时的表现要实测才知道;React 19 的新特性用上了,也要确认没有把不该重渲染的东西带进来。性能变差了,先别急着优化,先确认是不是升级带来的:回滚到旧版本测一次,两边数字一对比,原因就清楚了。升级后的一周,是升级的最后一道工序:日志、反馈、性能三样都平稳了,这次升级才算真正做完。
五个反模式
反模式一:跳过大版本升级。React 16 直接升 19、Next.js 13 直接升 16,中间的过渡版和警告期全跳过。官方升级文档的建议是一个大版本一个大版本地升:先升 18、修好、确认能跑,再升 19。跳级省下来的时间,都会在排错的时候加倍还回去。
反模式二:升级分支里顺手加功能。升级分支只干升级,功能分支排队等。两件事混在一个分支里,出了问题分不清是谁的锅,回滚的时候连功能一起滚回去。
反模式三:codemod 跑完不审 diff。codemod 是第一稿,不是最终答案。不审 diff 就提交,等于把机器的改动直接当成自己的改动。审 diff 的时候重点看:改得对不对、改全了没有、有没有清单之外的改动。
反模式四:静默失效当没看见。函数组件的 defaultProps 被静默忽略,不会报错;渲染错误的重复抛出改了,不会报错;这些“不报错的变化”最危险。读清单的时候,把“静默”两个字出现的地方单独标出来,一项一项在代码库里搜、在测试里验。
反模式五:没有基线就升级。测试本来就是红的、类型本来就过不了,升级之后更红了,也分不清是谁的错。先把基线测绿、记下来,再开升级分支。基线是升级期间唯一的参照物。
检查表:上线之前过一遍
动手之前:过渡版升了没有(React 18.3 的警告清干净了吗)?breaking change 清单读完了没有、每一项在代码库里搜过几处?功能开发冻结了吗、升级分支干净吗?基线三样(测试、类型、构建)全绿、结果记下来了吗?部署环境的 Node 版本够吗(Next.js 16 要 20.9 以上)?
动手的时候:工作区干净了再跑 codemod;跑完先审 git diff 再提交;codemod 改不了的(类型、defaultProps、异步请求 API)另外列出来人工改;AI 的改动一批一批来,改一批、跑一遍测试、绿了再改下一批;清单之外的改动一律打回去。
上线之前:类型检查全绿?测试套件全绿、和基线逐项对过?三条主流程人工走过?生产构建打过、警告逐条看过?回滚预案写好了(旧版本部署包、回滚命令、数据库兼容性确认)?灰度条件有的先灰度,没有的至少保证能回滚。六项全过,再点上线。升级这件事,慢就是快:准备充分的一次升级,比返工三次的“快速升级”快得多。
评论 (0)
原始来源
相关文章
Flexbox 一次只排一个方向,排对了,导航栏、卡片墙、购物车行都听话。本文按 MDN 的《Basic concepts of flexbox》《Aligning items in a flex container》《Controlling ratios of flex items along the main axis》三篇官方文档讲清楚:两根轴、容器与项目、方向与换行、剩余空间、flex 三件套、两根轴上的对齐、间距与自动边距。
一张点单就是一个对象:桌号、菜品、总价、付没付钱,全按标签收在一起。本文按 MDN 的《Working with objects》《JSON》《Object》三篇官方文档讲清楚:对象字面量、点号与方括号、增删改查、for...in 配 hasOwn、方法与 this、getter 与 setter、引用与复制、Object.assign 等工具箱、空白原型对象、JSON 的严规矩,以及 stringify 与 parse 和数字精度的坑。
2026 年 11 月 10 日,Amp 推出 Boxes:每月 18 美元起的常开小电脑,专门部署你用智能体造出来的软件。每个 box 自带 runner,智能体能直接在上面改生产数据;同一周 Amp 还上线了 Spaces、告别了 Dial、登陆了 Windows——智能体的工作场,正在从笔记本搬到云端。