用途:帮助将 Next.js 项目从 15 升级到 16,覆盖迁移流程、兼容性检查和安全上线。
升级前检查:项目使用 Git 以便回滚、所有改动已提交、测试通过、依赖(除 Next.js)为最新、Node.js 为 18.18.0 或更高、必要时备份生产数据库。完整流程在 references/upgrade-process.md,按需加载。
主要能力与用法:使用 codemod 自动迁移,命令为 npx @next/codemod upgrade,也可执行具体转换,如 npx @next/codemod built-in-next-font .、npx @next/codemod new-link .、npx @next/codemod next-image-to-legacy-image .;可通过 next-devtools-mcp 查询迁移模式、codemod 建议和新特性示例。
Next.js 16 变化:移除 getStaticProps、getServerSideProps、getInitialProps,新应用不再使用 pages/(改用 app/);Server Components 成为默认,fetch() 缓存默认值改变,动态路由需显式 generateStaticParams;Middleware 运行时配置、Image 组件属性、字体优化语法有调整。
常见问题处理:构建错误可清除 .next、删除 node_modules 与 package-lock.json 后重新 npm install 并 npm run build;水合错误需保证一致渲染,客户端时间用 useEffect 并加 suppressHydrationWarning;Server Actions 需在顶部写 'use server' 并返回可序列化数据;缓存不更新可用 revalidatePath 或 revalidateTag。
升级后:启用 Partial Prerendering、增强缓存与新 metadata,重构旧模式,优化包体积、图片与懒加载,检查 Core Web Vitals,并更新文档。
回滚:可用 git reset --hard HEAD~1 或 git checkout <previous-commit-hash>,再重装依赖并运行 npm run dev 验证。
限制:资料未提供对更低版本或其他框架的支持,也未说明收费、价格与平台信息。