next-upgrade

next-upgrade skill 概览

next-upgrade 是做什么的

next-upgrade skill 用来帮助代理基于官方迁移指南和 codemod，把一个真实的 Next.js 项目升级到更高的主版本，而不是凭记忆猜改法。它的职责很务实：先识别你应用里当前的 next 版本，规划风险更低的升级路径，优先应用合适的 codemod，再更新依赖，并检查仍需手动处理的 breaking changes。

什么人适合使用 next-upgrade skill

这个 next-upgrade skill 最适合正在维护现有 Next.js 代码库、希望让 AI 助手按官方指导来规划或执行升级的开发者。尤其适用于以下场景：

• 你的项目已经落后一个以上主版本
• 你需要基于仓库实际情况的升级方案，而不是泛泛的清单
• 你希望准确识别特定版本对应的 codemod 和依赖对齐关系
• 你想在 Code Editing 工作流里直接完成升级，而不只是看浏览器里的总结

它真正解决的工作问题

大多数用户并不只是想了解“Next.js 升级信息”。他们真正要解决的是：把一个当前还能正常运行的应用，升级到更新的 Next.js 版本，同时尽量不破坏路由、React 兼容性、构建产物或运行时 API。next-upgrade skill 正是围绕这个决策与执行路径设计的。

next-upgrade 和普通提示词有什么区别

普通 prompt 也许会给出宽泛的升级建议。next-upgrade 更聚焦，也更实用，因为它围绕以下流程组织：

• 先读取你的 package.json
• 查阅目标版本对应的官方 Next.js 升级指南
• 以增量方式处理主版本跳跃
• 优先运行官方 codemod，再考虑手动修改
• 正确配套升级 next、react 和 react-dom

它不会替你完成什么

这个 skill 并不能替代验证环节。它可以指导代码修改和依赖更新，但你仍然需要自己运行应用、测试、lint 和 build 检查。对于高度定制的环境，它也不能替代框架层面的专项经验，比如 monorepo、特殊 bundler 集成，或深度改造过的 server/runtime 行为。

如何使用 next-upgrade skill

安装 next-upgrade skill 的前提环境

先把这个 skill 安装到你的 AI 编码环境中，这样它才能在你要升级的仓库里被调用。常见安装方式如下：

npx skills add https://github.com/vercel-labs/next-skills --skill next-upgrade

如果你的环境已经直接暴露了来自 vercel-labs/next-skills 的 GitHub skills，那你可能只需要直接调用 next-upgrade。

实际调用 next-upgrade 的方式

仓库里给出的参数提示是 [target-version]，所以最清晰的用法是显式传入目标版本，例如：

• Use next-upgrade for Next.js 16
• Run next-upgrade targeting v15
• Apply the next-upgrade skill to move this app from 13 to 15 incrementally

如果你还没确定目标版本，可以先让它做规划：

• Use next-upgrade to inspect this repo and recommend the safest target version

next-upgrade 需要哪些输入

当代理能够检查以下内容时，next-upgrade 的效果最好：

• package.json
• lockfile，例如 package-lock.json、pnpm-lock.yaml 或 yarn.lock
• 如果应用在 monorepo 中，还要看 workspace 配置
• 应用目录结构，尤其要确认你使用的是 app/ 还是 pages/
• 用于验证升级结果的 CI 或 build 命令

最少也建议提供这些关键信息：

• 当前 Next.js 版本
• 包管理器
• 目标版本
• 你要的是仅做规划，还是直接修改代码

把模糊需求改写成高质量的 next-upgrade prompt

弱 prompt：

• Upgrade my app

更好的 prompt：

• Use next-upgrade to inspect package.json, determine the current Next.js version, upgrade this project to Next.js 15 using official migration guides, run the relevant @next/codemod transforms first, then update next/react/react-dom together and summarize any manual follow-up changes.

如果仓库更复杂，推荐这样写：

• Use next-upgrade for Code Editing on this monorepo app in apps/web. Read apps/web/package.json, identify the current next/react versions, plan the required incremental major upgrades to reach Next.js 16, apply official codemods where relevant, update dependencies with pnpm-compatible commands, and leave a checklist of manual verification steps for build, routing, and runtime APIs.

之所以这类 prompt 更有效，是因为 skill 本身很简洁；仓库边界、包管理器和执行范围，需要靠你的提示补全。

动手修改前，推荐的 next-upgrade 工作流

一套可靠的 next-upgrade usage 流程通常是：

1. 检查 package.json 和当前依赖版本
2. 确定目标版本
3. 针对涉及到的每一个主版本步骤，获取官方 Next.js 升级指南
4. 先跑 codemod，再做手动清理
5. 更新 next、react 和 react-dom
6. 运行 lint、typecheck、tests 和 production build
7. 修复升级指南或运行时报错暴露出的剩余 breaking changes

如果你落后了多个版本，不要盲跳。应当明确要求代理把 13 -> 14 -> 15 -> 16 当作独立升级步骤来处理。

先读哪个仓库文件

优先从上游仓库中的 skills/next-upgrade/SKILL.md 开始：

• https://github.com/vercel-labs/next-skills/tree/main/skills/next-upgrade

这个 skill 本身很短，可供检查的辅助文件并不多。它的核心价值主要体现在 SKILL.md 编码的流程里：识别版本、拉取官方文档、分步升级、先跑 codemod、再更新依赖。

next-upgrade 依赖的官方文档

这个 skill 明确指向官方 Next.js 升级资源，包括：

• codemod：https://nextjs.org/docs/app/guides/upgrading/codemods
• 各版本升级指南，例如：
  • https://nextjs.org/docs/app/guides/upgrading/version-16
  • https://nextjs.org/docs/app/guides/upgrading/version-15
  • https://nextjs.org/docs/app/guides/upgrading/version-14

这对是否采用 next-upgrade 很关键：它的效果取决于代理是否真的去拉取并遵循这些指南，而不是依赖过时的框架知识。

next-upgrade 的关键原则：codemod 要先跑，不是最后补

next-upgrade guide 最有价值的一点之一就是执行顺序。它会要求代理尽早运行官方 codemod：
npx @next/codemod@latest <transform> <path>

skill 中提到的示例包括：

• next-async-request-api
• next-request-geo-ip
• next-dynamic-access-named-export

这个顺序很重要，因为 codemod 往往比在依赖升级后再手工改代码，更快、更稳地处理重复性的 breaking changes。

依赖更新时，要明确要求一起升级哪些包

使用 next-upgrade 时，建议你明确要求代理把 peer 依赖一起升级。这个 skill 特别强调的模式是：
npm install next@latest react@latest react-dom@latest

即使你用的是 pnpm 或 yarn，原则也一样：除非官方指南另有说明，否则应把 next、react 和 react-dom 视为一个需要协调升级的组合。

next-upgrade 在 Code Editing 场景下怎么用更合适

在 Code Editing 场景中，如果你允许代理既检查文件又直接修改文件，next-upgrade 的价值会更大，而不只是让它输出一个计划。适合交给它的任务包括：

• 更新 package.json 里的依赖版本范围
• 执行 codemod 命令
• 修改受 breaking changes 影响的 API
• 留下便于人工复核的行内注释或迁移总结

如果你的环境无法访问仓库文件或外部文档，它的帮助会明显下降，因为这个 skill 的优势正来自“仓库检查 + 官方指南获取”的组合。

使用 next-upgrade 时的实际限制与权衡

如果你想要一条更有纪律性的升级路径，next-upgrade 很适合；但也要知道它的边界：

• 它不会把每个版本细节都内置在本地，而是依赖实时查询升级指南
• 它最适合标准的 Next.js 应用，不太适合高度定制的基础设施
• 它不自带项目专属的测试自动化
• 对 monorepo、子应用或非根目录包文件，往往需要你额外把范围说明清楚

简而言之，它能减少拍脑袋升级，但你的 prompt 仍然要把范围定义清楚。

next-upgrade skill 常见问题

next-upgrade 比泛用升级 prompt 更好吗？

通常是的，尤其当你想要一个可重复执行的升级流程时。泛用 prompt 可能给出看似合理、但已经过时的建议。next-upgrade 则锚定在官方迁移指南、codemod，以及从项目文件中识别实际版本这几件事上。

next-upgrade skill 对新手友好吗？

友好，但有一个前提：新手最好先用规划模式。可以先让它给出：

• 当前版本识别结果
• 目标版本建议
• 需要运行的 codemod
• 可能需要手动处理的改动
• 验证清单

这样在真正放开修改之前，输出会更容易审阅。

我必须先知道目标版本吗？

不需要。你可以让 next-upgrade 先检查仓库，再推荐风险更低的目标版本。但如果你已经因为平台或依赖要求，明确知道必须升级到某个版本，那么一开始就给出目标版本，通常能得到更干净的执行方案。

什么情况下不该用 next-upgrade？

以下情况可以跳过 next-upgrade：

• 你是在新建应用，而不是升级现有应用
• 你的问题和版本迁移无关
• 你的技术栈依赖官方文档没有覆盖的自定义内部实现
• 你只需要一条命令，而且已经清楚完整的版本升级路径

next-upgrade 能处理跨多个版本的大升级吗？

可以，但应该分步处理。这个 skill 明确倾向于按主版本逐步升级，而不是一次性盲跳。如果你的应用版本很旧，建议要求它给出分阶段方案，并在每个主版本后设置检查点。

它只适用于 app router 项目吗？

不是，但它拉取的官方指南可能会更强调较新的 Next.js 模式。如果你的代码库仍然大量使用旧约定，最好在修改之前先要求代理判断：哪些指南内容适用于你的仓库，哪些不适用。

如何改进 next-upgrade skill 的使用效果

给 next-upgrade 更清晰的仓库边界

想更快得到靠谱结果，最有效的方法就是明确告诉代理：Next.js 应用具体在哪个路径里。对于 monorepo，建议直接说明：

• 应用路径，例如 apps/web
• 包管理器
• workspace 工具
• 修改是否应严格限制在该应用内部

否则，这个 skill 可能会读错 package.json，或者在错误的层级上生成命令。

让 next-upgrade 分两阶段输出

一个很稳妥的模式是：

1. 只出规划
2. 再执行修改

例如：

• Use next-upgrade to first produce an upgrade plan with required codemods and risks. After I approve it, apply the changes.

这样可以减少误触发的大范围修改，也能让这个 skill 在生产代码库里更值得信任。

提供更明确的验证标准

不要只说“成功升级”。更好的做法是要求代理用具体命令来验证，例如：

• install
• lint
• typecheck
• unit tests
• production build

这样能提升 next-upgrade usage 的实际效果，因为代理优化的目标会变成“仓库通过验证”，而不只是“依赖版本号更新了”。

直接说明你最在意的失败模式

如果你最担心某类回归问题，就要明确写出来。例如：

• Prioritize route behavior and middleware compatibility
• Watch for request API changes introduced in newer Next.js versions
• Do not migrate unrelated code while applying next-upgrade

这类约束，比一句宽泛的“让它能跑起来”更能引导出高质量修改。

让它解释 codemod 的选择依据

一个很实用的改进型 prompt 是：

• List which @next/codemod transforms apply to this repo and why before running them

这样你就能先审查代理是否真的根据代码模式匹配 codemod，而不是不加区分地全部跑一遍。

next-upgrade 常见失误模式

典型的低质量结果通常表现为：

• 没先检查当前版本就直接升级依赖
• 跳过中间主版本
• 没看 codemod 就先手动改代码
• 忽略 react 和 react-dom 的版本对齐
• 在 monorepo 中想当然地把根目录 package.json 当成应用包

如果你看到这些迹象，应当停下来，要求它按版本逐步给出升级方案。

第一次输出之后，怎么继续迭代

完成第一轮后，不要从头来过，而是针对失败点要求一次更聚焦的第二轮，例如：

• Re-run next-upgrade analysis based on these build errors
• Compare the remaining errors against the official v15 guide
• Propose the smallest manual edits still needed after codemods

这比直接重开一轮更有效，因为这个 skill 本来就是围绕迁移步骤设计的，而不是追求一次输出就绝对完美。

想要更高质量 next-upgrade 结果，最佳 prompt 模板

一个紧凑但高信号的模板如下：

Use next-upgrade on <path>. Detect the current Next.js version from package.json, determine the correct incremental upgrade path to <target-version>, fetch the official migration guides for each step, identify and run the applicable @next/codemod transforms first, then update next/react/react-dom together. After edits, summarize breaking changes addressed, remaining manual follow-ups, and the exact verification commands I should run.

这个 prompt 给 next-upgrade skill 提供了足够明确的结构，产出通常会明显优于泛泛的 Code Editing 请求。