NNext.js 中文网 GitHub

使用编码代理进行升级

experimental

使用编码代理升级并验证 Next.js 应用。

使用 next upgrade --agent 让编码代理升级并验证你的应用。该命令会根据配置的策略确定目标版本,准备相关的迁移指南和 Skills,并将任务交给代理。

该命令支持 App Router 和 Pages Router 项目。如果不使用 --agent,next upgrade 将改为运行交互式 codemod 工作流。

开始升级#

在你的应用目录中运行最新的升级 CLI:

Terminal
npx next@canary upgrade --agent=latest

从工作区根目录运行时,传入应用目录:

Terminal
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:

Terminal
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:

Terminal
npx next@canary upgrade --agent=experimental-future

Pages 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 版本。

终端会显示类似以下的提示:

Terminal
检测到多个编程智能体。你想使用哪一个?
使用 ↑/↓ 选择,然后按 Enter。

❯ 继续使用 Codex
  继续使用 Claude Code
  复制提示词给其他编程智能体
  取消

应由哪个 Codex 模型执行升级?
❯ Terra
  Sol
  取消

本次升级应使用多大的推理强度?
  低
  中
❯ 高
  极高
  最大
  超强
  取消

Codex 是否使用自动权限模式?
❯ 是
  否,请求批准
  取消

是否在单独的 Git worktree 中打开升级?
❯ 是
  否

当你从现有的编码代理中运行该命令时,它会将准备好的任务提供给该代理。代理会保留其会话中已配置的模型、推理强度和权限。

配置升级提醒#

升级提醒默认随 security 策略启用。设置 experimental.agentUpgrade 可选择其他策略或禁用提醒:

next.config.ts
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 需要访问发布元数据,对于稳定版目标,还需要访问安全公告数据。如果无法确定目标,它会报告原因,而不会启动代理会话。

Next.js 中文网