Next.js 升级协议
Next.js 版本升级(例如 v14 → v15)的自动和手动迁移步骤。
优先级:P1(操作)
实施指南
- 升级检测:始终检查
package.json中next、react和react-dom的版本。 - 规划:对于主版本跳跃(例如 v13 到 v15),执行增量升级(v13 -> v14,然后 v14 -> v15)。请遵循官方 Next.js 迁移指南。
- 自动化 Codemods:使用
npx @next/codemod@latest <transform> <path>来自动化语法迁移。 - 突破性变更(v15):响应
next-async-request-api转换,确保params、searchParams、cookies()和headers()被 await。 - React 版本同步:升级
react和react-dom以匹配 Next.js 的对等依赖(例如,Next.js 15 对应 React 19)。 - 验证:在每个增量步骤之后运行
next dev和next build。检查控制台错误中的水合警告。 - 报告:将所有 codemod 失败或需要手动修复的情况报告给团队。
3. 依赖更新
同步升级 Next.js 和对等依赖:
# 使用 npm
npm install next@latest react@latest react-dom@latest
# 更新类型
npm install --save-dev @types/react@latest @types/react-dom@latest
4. 手动验证规则
- 异步上下文:验证所有对
cookies()、headers()和路由params的使用现在都已 await。 - 元数据:确保
generateMetadata的类型与新的异步params签名匹配。 - 缓存:在 v15+ 中,
fetch默认使用{ cache: 'no-store' }。如果需要旧行为,请显式设置{ cache: 'force-cache' }。
5. 测试构建
- 在 codemods 和包更新后立即运行
npm run build。 - 如果使用
--turbo,请检查“Hydration failed”或“Turbopack”兼容性错误。
反模式
- 不要跳跃主版本:一次只升级一个主版本(13→14,然后 14→15)。
- 不要手动修复突破性变更:始终首先运行
npx @next/codemod@latest转换。 - 升级后不要假设缓存行为:v15 默认使用
no-store;审计所有fetch调用。 - 不要在 Pages Router 中使用异步页面函数:
export default async function Page()会导致错误。