4.3 版本升级与迁移

4.3 版本升级与迁移

本节摘要：Next.js 迭代快，升级是常态。本节讲清两条升级路径：小版本升级（codemod 自动迁移）与 Pages Router → App Router 大迁移（架构级），以及升级前的准备、破坏性变更处理与验证流程。

本节目标

阅读完本节，你应当能够：

1. 用官方升级工具（codemod）自动迁移
2. 制定升级前准备清单
3. 理解 Pages Router 与 App Router 的核心差异
4. 完成路由与数据获取的迁移
5. 验证升级后功能正常

问题与直觉：升级为什么"不能直接改版本号"

npm install next@latest 一时爽，跑起来全是坑——Next.js 的大版本升级常带破坏性变更（API 移除、行为变化、配置项改名）。盲目升级轻则警告刷屏，重则页面全挂。升级是工程，需要准备、迁移、验证三步走。

直觉类比：升级框架像"老房翻新"——不能直接换地基（版本号），要先勘察（兼容性检查）、分批改造（codemod/手动迁移）、验收（测试+预览）——稳扎稳打，每步可回退。

💡 关键直觉：官方升级工具（codemod）能自动完成大部分"机械性迁移"——改 API 名、移动文件、更新配置。人力集中在"行为变化"的部分（渲染模型、数据获取语义）。先用工具清掉机械劳动，再人工处理语义变化。

核心原理：小版本升级

2.1 官方升级工具

# 查看升级指南
npx @next/codemod@latest --help

# 自动迁移（示例：Next.js 13 → 14）
npx @next/codemod@latest next-13-to-14 .

# 单文件测试模式（先试跑）
npx @next/codemod@latest next-13-to-14 ./pages/index.tsx
​

codemod 能自动处理：import 路径变更、API 重命名、配置项调整。

2.2 升级准备清单

# 1. 先升级 React（Next.js 依赖 React 版本）
npm install react@latest react-dom@latest

# 2. 升级 Next.js
npm install next@latest

# 3. 跑 codemod 自动迁移
npx @next/codemod@latest <目标版本> .

# 4. 检查破坏性变更
# 阅读官方升级指南（nextjs.org/docs/app/building-your-application/upgrading）
​

2.3 验证流程

npm run lint          # 代码规范
npm run test:unit     # 单元测试
npm run build         # 构建（类型检查 + 编译）
npm run test:e2e      # 端到端
# 手动验证核心流程（登录、CRUD、SEO）
​

验证不通过怎么办：逐个修复；修复不了用 git revert 回退——升级的每一步都可回滚。

工程实践要点：Pages Router → App Router

3.1 核心差异

3.2 迁移步骤

第一步：路由文件迁移

# 页面
pages/about.jsx         →  app/about/page.tsx
pages/posts/[id].jsx    →  app/posts/[id]/page.tsx

# API
pages/api/posts.js      →  app/api/posts/route.ts
​

第二步：数据获取迁移

// 旧：getServerSideProps
export async function getServerSideProps() {
  const data = await fetchData();
  return { props: { data } };
}
export default function Page({ data }) { ... }

// 新：服务器组件直接取数
export default async function Page() {
  const data = await fetchData();
  return <div>{data}</div>;
}
​

第三步：组件迁移

• 默认客户端组件 → 判断是否需要服务器组件；
• 交互组件加 "use client"；
• 布局用 layout.tsx 重构。

第四步：混合共存

// next.config.ts —— 迁移期间两套路由共存
const nextConfig = {
  // App Router 与 Pages Router 可共存，逐个迁移
};
​

3.3 迁移策略：渐进式

渐进式原则：一次迁移一个页面/功能，每个都验证通过再继续——避免"大爆炸式"重构。

常见误区与排查

动手演练：迁移一个页面

// 1. 旧代码 pages/posts/[id].jsx
export async function getServerSideProps({ params }) {
  const res = await fetch(`/api/posts/${params.id}`);
  const post = await res.json();
  return { props: { post } };
}
export default function Post({ post }) {
  return <h1>{post.title}</h1>;
}

// 2. 新代码 app/posts/[id]/page.tsx
export default async function PostPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const post = await fetch(`/api/posts/${id}`).then((r) => r.json());
  return <h1>{post.title}</h1>;
}

// 3. 移动文件
git mv pages/posts/[id].jsx "app/posts/[id]/page.tsx"
​

对比：getServerSideProps + props 传递 → 服务器组件直接取数——代码更少、逻辑更直。迁移一个页面，理解 App Router 的数据流，其余页面照此办理。

本章回顾

• 升级是工程：准备 → 迁移 → 验证，每步可回滚。
• codemod：官方工具自动处理机械性迁移。
• 先升 React：Next.js 依赖 React 版本，顺序不能乱。
• 验证流程：lint + test + build + e2e 全跑。
• 核心差异：路由/布局/数据获取/组件默认值的全面变化。
• 渐进迁移：一次一个页面，验证后再继续，避免大爆炸重构。

深入理解：迁移中的行为差异清单

升级 Next.js 时，除了机械性迁移（codemod 处理），更要留意"行为差异"——这些不会报错，但会让功能悄悄变样。

数据获取的语义变化

组件行为的差异

• 客户端 → 服务器组件默认：原本在浏览器跑的代码（useEffect 初始化、window 访问）迁移后会在服务器跑——报错或行为异常是迁移后的常见问题；
• 事件处理：服务器组件里的事件不生效，需要拆客户端组件；
• 布局：Pages 的 _app/_document 手动管理 → App Router 自动嵌套，注意 CSS 与脚本的挂载方式变化。

迁移验证清单

# 逐页面迁移，每步验证
1. npm run lint          # 规范
2. npm run build         # 类型 + 编译
3. npm run test          # 单元
4. 手动验证页面          # 数据、交互、SEO
5. npx playwright test   # 端到端
​

一句话：升级迁移最危险的不是"报错"而是"不报错但行为变了"——数据获取时机、组件默认值、缓存语义是三大高频差异点，迁移后务必手动验证数据流与交互。

常见问题速答

问：升级后还能继续用 Pages Router 吗？
能。Next.js 支持两套 Router 共存，迁移期间可混合。但新页面建议直接用 App Router，逐步迁移旧页面，最终删除 pages/ 目录。

问：codemod 跑完还需要做什么？
codemod 处理机械性变更（API 名、import 路径）。剩下的"行为差异"（数据获取时机、组件默认值、缓存语义）需要人工审查——跑完 codemod 不代表迁移完成。

问：升级后构建报错怎么办？
逐个修复：先看类型错误（tsc），再看弃用警告（build 输出），最后跑测试。修复不了就 git revert 回退，再分批升级。

问：什么时候该升级？
不是"出新版就升"。评估：新版本是否修复你遇到的问题、是否有你需要的新特性、社区是否已稳定（等几个 patch 版本）。生产项目升级要谨慎，先在预览环境验证。