使用编码代理进行升级
experimental
使用编码代理升级并验证 Next.js 应用。
使用 next upgrade --agent 让编码代理升级并验证你的应用。该命令会根据配置的策略确定目标版本,准备相关的迁移指南和 Skills,并将任务交给代理。
该命令支持 App Router 和 Pages Router 项目。如果不使用 --agent,next upgrade 将改为运行交互式 codemod 工作流。
开始升级#
在你的应用目录中运行最新的升级 CLI:
npx next@canary upgrade --agent=latest从工作区根目录运行时,传入应用目录:
npx next@canary upgrade apps/web --agent=latest使用 next@canary 会运行最新的升级工具,即使应用使用的是较旧的 Next.js 版本也是如此。CLI 会读取应用中安装的版本,只有当应用已经使用 canary 版本时,才会选择 canary 目标。如果项目的包管理器设置了最短发布时长,CLI 会使用策略允许的最新 canary 版本。
选择策略#
| 策略 | 行为 |
|---|---|
security | 对于受影响的稳定版本,选择最早符合条件的主版本中的最新安全版本。 |
latest | 将稳定版、RC、beta 和 preview 应用升级到 npm 的 latest 稳定版本,或将 canary 应用升级到 canary 版本。 |
experimental-future | 应用 latest 策略,然后采用适用的未来默认值。 |
省略策略时,将使用 experimental.agentUpgrade 中的字符串值。否则,命令将使用 security:
npx next@canary upgrade --agent--agent 不能与 --revision 一起使用。
security 支持稳定版安装。canary 安装可以使用 latest 或 experimental-future。RC、beta 和 preview 安装可以使用 latest 升级到更新的稳定版本。不支持其他预发布渠道。
采用未来默认值#
未来默认值是 Next.js 计划默认启用的功能,例如 Cache Components 和 Partial Prefetching。experimental-future 策略是升级帮助应用采用这些功能的早期版本,即使应用已经使用最新的 Next.js 版本也是如此。这样一来,迁移到新的默认值就成为升级的一部分,而不是单独的迁移。
对于 Next.js 16.3 或更高版本的 App Router 项目,该策略目前会准备 Cache Components 指南和采用 Skill:
npx next@canary upgrade --agent=experimental-futurePages Router 项目可以使用它进行版本升级,但在项目改用 App Router 之前,它不会提供 Cache Components。
要立即采用新功能,请直接使用相应的采用 Skill。请参阅迁移到 Cache Components和采用 Partial Prefetching。
该命令的作用#
在启动代理会话之前,CLI 会检查已安装的版本、发布元数据以及所选策略所需的任何安全数据。当不需要升级或无法确定目标时,它会停止并给出说明。
对于可以执行的升级,CLI 会将相关的迁移指南复制到临时目录,准备适用的 Skills,并为所选目标创建任务。对于主版本升级,任务会包含所跨越的每个主版本的指南。它还会要求代理检查重复工作、在可用时使用单独的 Git worktree、运行相关检查并验证结果。
任务还会要求代理将所选策略保存为 next.config 中的 experimental.agentUpgrade,以便将来进行升级提醒。要禁用提醒,请将该选项设置为 false。
当你在编码代理内部运行该命令时,CLI 会打印任务供当前代理执行。在交互式终端中,它可以启动已安装的 Codex 或 Claude Code 会话,或复制任务供其他代理使用。在非交互式终端中,它会打印任务。
选择运行代理的方式#
当你从交互式终端启动该命令时,它会询问要使用哪个已安装的代理。对于新的代理会话,你还可以选择其模型、推理强度、是否使用自动权限以及是否使用单独的 Git worktree。可用的选项取决于所选代理和 CLI 版本。
终端会显示类似以下的提示:
检测到多个编程智能体。你想使用哪一个?
使用 ↑/↓ 选择,然后按 Enter。
❯ 继续使用 Codex
继续使用 Claude Code
复制提示词给其他编程智能体
取消
应由哪个 Codex 模型执行升级?
❯ Terra
Sol
取消
本次升级应使用多大的推理强度?
低
中
❯ 高
极高
最大
超强
取消
Codex 是否使用自动权限模式?
❯ 是
否,请求批准
取消
是否在单独的 Git worktree 中打开升级?
❯ 是
否当你从现有的编码代理中运行该命令时,它会将准备好的任务提供给该代理。代理会保留其会话中已配置的模型、推理强度和权限。
配置升级提醒#
升级提醒默认随 security 策略启用。设置 experimental.agentUpgrade 可选择其他策略或禁用提醒:
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
experimental: {
agentUpgrade: 'latest',
},
}
export default nextConfig将该选项设置为 false 可禁用提醒。
该选项不会自动升级应用。在交互式终端中,当提醒显示时,next dev 或 next build 会继续运行并缓冲其输出。立即升级会在开始升级前停止该命令。跳过会返回正在运行的命令并重放该输出。跳过直到下一个版本会针对当前安装的版本关闭提醒。详情请参阅提醒行为。
当编码代理遇到提醒时,它会报告可用的升级,并在重试命令后继续执行原任务。
在 next dev 期间,当安装的版本受到已知安全漏洞影响时,Next.js DevTools 还会显示漏洞洞察。该洞察提供一个可复制的提示词,用于通过编码代理启动 security 升级。
CLI 需要访问发布元数据,对于稳定版目标,还需要访问安全公告数据。如果无法确定目标,它会报告原因,而不会启动代理会话。