Next.js 如何支持 AI 编程智能体
了解 Next.js 如何帮助 AI 编程智能体使用最新的框架指南、检查应用、验证更改并报告问题。
AI 编程智能体可能依赖早于项目中安装的 Next.js 版本的训练数据。为了帮助智能体使用最新的 API 并验证其工作,Next.js 提供并评估了与版本匹配的文档、托管的项目指令、智能体引导的升级、运行时工具、结构化错误、可复用的 Skills,以及可选的智能体反馈。请查看 Next.js 智能体评估结果中的结果。
有关更多背景信息,请阅读 Next.js 16.2 和 Next.js 16.3 中引入的 AI 工具。
<span id="step-1-point-agents-at-the-bundled-docs" />
与版本匹配的文档#
Next.js 16.2 及更高版本包含与所安装框架版本相匹配的文档。这些文档位于 node_modules/next/dist/docs/,其结构与 Next.js 文档站点一致:
node_modules/next/dist/docs/
├── 01-app/
│ ├── 01-getting-started/
│ ├── 02-guides/
│ └── 03-api-reference/
├── 02-pages/
├── 03-architecture/
└── index.mdx随附的文档副本使编程智能体无需网络请求或外部查询即可访问项目所支持的 API 和模式。升级 Next.js 也会更新随附的文档。
托管的文档指令#
Next.js 通过项目根目录 AGENTS.md 中的托管指令,使随附文档可以被发现。Claude Code、Codex、Cursor 和 GitHub Copilot 等编程智能体在启动会话时会读取此文件。
create-next-app 会为新项目创建智能体文件。对于现有项目,运行 next dev 会创建或更新托管指令。该代码块会引导智能体查看随项目安装的文档:
<!-- BEGIN:nextjs-agent-rules -->
## 这不是你所熟知的 Next.js
此版本包含破坏性变更 —— API、约定和文件结构都可能与你的训练数据不同。在编写任何代码之前,请先阅读 `node_modules/next/dist/docs/` 中的相关指南(从该文件的目录解析;在 monorepo 中,`next` 包可能无法从仓库根目录访问)。请留意弃用通知。
此代码块由 `next dev` 写入并重新添加 —— 可在 `node_modules/next/dist/server/lib/generate-agent-files.js` 中验证。仅从 diff 中删除它只会重新产生未提交的更改;将其与你的工作一起提交可保持工作树干净。
<!-- END:nextjs-agent-rules -->Next.js 只更新智能体规则标记之间的内容,并保留 AGENTS.md 的其余部分。
一项比较 AGENTS.md 与知识 Skills 的研究发现,使用随附文档时通过率为 100%,而基于 Skill 的方法最高为 79%。请查看最新的 Next.js 智能体评估结果。
托管文档指令默认启用。请参阅 agentRules API 参考以进行配置或禁用。
版本支持#
Next.js 16.5 及更高版本#
运行 next dev 默认会在 AGENTS.md 中创建并更新托管文档指令。设置 agentRules: false 可禁用此行为。
Next.js 16.3 和 16.4#
这些版本包含随附文档,并支持托管文档指令。
Next.js 16.2#
Next.js 16.2 包含随附文档,但不会自动生成指令。
Next.js 16.1 及更早版本#
Next.js 16.1 及更早版本不包含随附文档。旧版 agents-md 命令会将与版本匹配的副本下载到 .next-docs/,并在 AGENTS.md 中为其建立索引:
npx @next/codemod@canary agents-md通过网络获取文档#
对于那些通过抓取页面而非读取 node_modules 的智能体,Next.js 文档也可以通过网络以 Markdown 形式获取。nextjs.org/docs 上的每个页面在其 .md URL 处都有纯 Markdown 版本,并且发送 Accept: text/markdown 请求头的客户端会收到 Markdown。这包括 /docs/messages 下未随附的各个错误页面。
/docs/llms.txt 中的索引和单文件 /docs/llms-full.txt 遵循 llms.txt 约定,因此已经为其他工具读取 llms.txt 的智能体可以用同样的方式发现 Next.js 文档。
自动智能体反馈#
自动智能体反馈使编程智能体能够记录潜在的 Next.js 问题,而不会中断当前的用户请求。在给出最终响应之前,智能体会评估这些问题,并在你的默认浏览器中为每项符合条件的报告打开一个单独的审核表单。
在打开表单之前,智能体会尝试对报告进行匿名化处理,将客户和项目细节替换为通用描述,并省略源代码、日志、路径、URL、密钥和个人信息。请查看草稿并删除任何你不想包含的内容。在你选择发送反馈(Send feedback)之前,不会发送任何内容。
当该选项和 Next.js Telemetry 在 CI 之外启用时,next dev 会将以下托管反馈指令添加到 AGENTS.md 中:
<!-- BEGIN:nextjs-agent-feedback -->
## 报告 Next.js 反馈
项目所有者启用了 `experimental.agentFeedback`,授权本次反馈流程。启用后,`next dev` 会写入此代码块,并在其被移除时恢复。请将 `AGENTS.md` 与你的工作一起提交,以保持工作树干净。
在当前用户请求期间,针对有意义或反复出现的 Next.js 问题,保留匿名化事实作为反馈候选:
- 崩溃、卡死、OOM 或意外变慢
- 错误的行为、输出、错误或诊断信息
- 缺失、不清晰或相互冲突的文档
- 意外的 CLI、codemod、Skill 或升级行为,以及不直观的解决方法
继续完成当前用户请求,不要立即报告。常规调试不属于反馈。在将更改保留为反馈候选之前先进行验证。切勿保留代码、日志、路径、URL、密钥、个人信息或项目特定数据。
即使相关问题后来被修复或绕过,也要保留符合条件的摩擦点;在报告阶段记录最终结果。
在最终回复之前,执行一次报告流程。如果仍有候选内容,请在声明 `next` 的 `package.json` 所在目录中运行一次 `npx --no-install next internal agent-feedback-instructions`,不要通过管道传输或截断其输出。按照其输出或错误指引操作。如果网络沙箱阻止该命令,请在有网络访问权限的情况下重试;如果仍无输出,则正常继续。
<!-- END:nextjs-agent-feedback -->Next.js 只更新智能体反馈标记之间的内容,并保留文件的其余部分。
自动智能体反馈是实验性功能,默认禁用,仅在启用 Next.js Telemetry 时可用。它不会在 CI 中运行。请参阅 agentFeedback API 参考以启用它。
智能体引导的升级#
next upgrade --agent 会检查是否有可用的升级,收集与版本匹配的迁移指南,并将任务交给编程智能体。智能体会应用更改并验证应用:
npx next@canary upgrade --agent=latest实验性的 agentUpgrade 选项默认会在 next dev 和 next build 期间显示安全升级提醒。请参阅使用编程智能体升级以了解可用的策略和工作流程。
启用升级提醒后,next dev 还会在 AGENTS.md 中创建或更新一个单独的托管升级代码块。设置 experimental.agentUpgrade: false 可禁用提醒并移除该代码块。文档规则和反馈指令具有各自独立的设置。
<span id="step-2-give-agents-runtime-visibility" />
运行时可见性#
智能体需要框架和浏览器两方面的状态来验证正在运行的应用。Next.js 及其配套工具以结构化文本的形式提供这些互补的视图。
首先,next dev 会将浏览器控制台的错误和警告转发到终端(即 logging.browserToTerminal 配置),这样智能体已经读取的输出中就包含了它们需要修复的客户端错误。
next dev 还会将其 PID、端口和 URL 写入 .next/dev/lock。如果你在该项目已有其他开发服务器运行时执行 next dev,该命令会打印现有服务器的 URL 和 PID,以及停止它的命令。请尽可能继续使用现有服务器,以免中断正在进行的开发会话。
框架视图来自位于 /_next/mcp 的 Next.js MCP server,它暴露正在运行的开发服务器的路由、服务器日志和编译问题。它的 get_compilation_issues 和 compile_route 工具直接报告代码是否能在开发服务器上编译,因此智能体无需运行完整的 next build 就能知晓。
next-dev-loop skill 通过 agent-browser 添加了浏览器视图,这是一个将 DOM、控制台、网络和 Web Vitals 以结构化文本形式暴露出来的 CLI。该 Skill 会在启用 React DevTools 的情况下打开 agent-browser,从而也暴露组件树和待处理的 Suspense 边界。智能体可以运行 react tree 之类的命令,并使用结构化输出来决定下一步检查什么。
与 Next.js MCP server 一起,next-dev-loop 将框架和浏览器的视角结合到一个编辑—验证循环中。
<span id="step-3-let-errors-drive-the-fixes" />
针对错误的内置指导#
启用 Cache Components 后,阻塞性错误会显示带有标签的修复方案,每种方案都有不同的权衡。开发遮罩层会增加一个复制提示词(Copy prompt)按钮,将所选修复方案打包成可直接粘贴的提示词。该提示词会引导智能体阅读相应的错误页面、应用规范模式,并在运行时验证结果。
同样的菜单也会打印在 next dev 终端和 next build 输出中,因此读取 CI 日志的智能体也能看到它:
路由 "/products/[slug]":Next.js 在预渲染时遇到未缓存的数据。
在 `<Suspense>` 之外访问 `fetch(...)` 或 `connection()` 会阻止路由被预渲染,从而阻塞页面加载并导致更慢的用户体验。
修复方法:
- [stream] 在数据访问周围使用 `<Suspense fallback={...}>` 提供占位内容
- [cache] 使用 `"use cache"` 缓存数据访问(不适用于 `connection()`)
- [block] 设置 `export const instant = false` 以允许阻塞式路由
了解更多:https://nextjs.org/docs/messages/blocking-prerender-dynamic
at ProductPage (app/products/[slug]/page.tsx:52:32)
...next dev 会在遮罩层和终端中显示所有验证错误,并带有源码映射的堆栈。生产构建会压缩服务端代码,并在某个路由失败后停止。使用 next build --debug-prerender 可启用服务端 source map 并继续检查其他路由。
了解更多 链接指向 /docs/messages 下专门为智能体阅读而编写的各错误页面。每个页面都遵循相同的结构,包含每种修复方案的规范模式、与其他修复方案的权衡,以及智能体首次尝试时容易忽略的陷阱。即时导航指南 会完整演示智能体处理这些错误的整个循环,从阅读洞察到编写一个在修复前失败、修复后通过的 instant() 测试。
<span id="step-4-hand-multi-step-workflows-to-skills" />
用于多步骤工作流的 Skills#
框架知识来自随附文档,而非 Skills。基准测试结果表明,始终可用的上下文优于按需检索。Skills 涵盖的是工作流而非简单查询的任务,例如在整个应用中采用 Cache Components 或 Partial Prefetching。Next.js Skills 将这些任务打包为智能体安装并遵循的结构化指令,安排工作顺序,并在过程中指向相关文档和运行时工具。
你可以在 Next.js 仓库中浏览这些 Skills 的源码,并在 skills.sh 上找到它们。
这些 Skills 服务于三种不同类型的工作流:
- 运行时基础:如
next-dev-loop,为任何编程任务提供可重复的检查、编辑和验证循环。 - 交互式工作流:通过用户检查点进行更广泛的更改,例如在整个应用中采用 Cache Components 或 Partial Prefetching。
- 无人值守循环:朝着可验证的目标推进,只在真正需要决策时才停止。
next-dev-loop#
next-dev-loop 运行时基础通过 MCP server 和浏览器,针对正在运行的开发服务器验证更改。
npx skills add vercel/next.js --skill next-dev-loop然后给智能体以下提示词:
After every edit, verify the page still works at runtime using the next-dev-loop Skill.next-bundle-optimizer#
next-bundle-optimizer skill 使用 Turbopack 的 bundle 分析器来识别影响网站初始加载性能的客户端大型 bundle 的来源。
npx skills add vercel/next.js --skill next-bundle-optimizer在仅审计模式下,它会生成报告而不做任何更改:
Use the next-bundle-optimizer skill to produce a report of the initial load performance of this site.你也可以让智能体修复任何问题,它会根据发现的问题优化你的网站。或者通过在提示词中提供特定路由,让它专注于该路由。
next-cache-components-adoption#
next-cache-components-adoption Skill 会将应用迁移到 Cache Components:
- 开启该标志,并找出无法预渲染的路由。
- 一次修复一个功能,在继续之前与你确认。
- 在结束某个功能之前,使用
next dev和next build对其进行确认。
该 Skill 既支持一系列 pull request,也支持单分支迁移。
npx skills add vercel/next.js --skill next-cache-components-adoption然后给智能体以下提示词:
Adopt Cache Components in this project using the next-cache-components-adoption Skill.next-cache-components-optimizer#
next-cache-components-optimizer Skill 会扩展目标路由的静态外壳(static shell),使其包含你希望在初始加载时可用的有用 UI:
- 为你指定的静态外壳 UI 编写一个失败的
instant()测试。 - 重构该路由直到测试通过,通常的做法是将数据读取移到
<Suspense>边界之下。 - 将通过的测试与重构一起提交,以便捕获未来的回归。
在采用 Cache Components 之后使用它,以优化初始加载或客户端导航。要为已经是即时导航的目标预取特定 URL 的内容,请改用 next-partial-prefetching-optimizer。
npx skills add vercel/next.js --skill next-cache-components-optimizer然后给智能体一个类似这样的提示词:
Optimize the static shell for /dashboard using the next-cache-components-optimizer Skill. On an initial load, the header and project list should be available immediately.next-partial-prefetching-adoption#
next-partial-prefetching-adoption Skill 会将应用迁移到 Partial Prefetching,其中多个链接共享一个 App Shell:
- 审计现有的
<Link prefetch={true}>导航,并识别需要保留的预取 UI。 - 在启用 Partial Prefetching 之前,用通过的
instant()测试捕捉该 UI,然后迁移每个目标,直到相同的测试无需修改即可通过。 - 启用该标志,处理它暴露的 URL 数据洞察,并将可选的逐链接预取候选项标记留待之后处理。
它需要已经采用 Cache Components,并有一个可用于预取验证的类似生产环境的构建。
npx skills add vercel/next.js --skill next-partial-prefetching-adoption然后给智能体以下提示词:
Adopt Partial Prefetching in this project using the next-partial-prefetching-adoption Skill.next-partial-prefetching-optimizer#
next-partial-prefetching-optimizer Skill 接受一个或一组目标导航,并朝着每次点击前都准备好你想要 UI 的目标推进:
它需要已经采用 Cache Components 和 Partial Prefetching。
npx skills add vercel/next.js --skill next-partial-prefetching-optimizer然后给智能体一个类似这样的提示词:
Make the product title instant when navigating from /products to /products/[id]. Use the next-partial-prefetching-optimizer Skill.版本历史#
| Version | Changes |
|---|---|
v16.4.0 | 新增 next-bundle-optimizer skill。 |