Next.js 16.3: AI Improvements

Next.js 16.3：AI 改进 | Next.js

返回博客

2026年6月26日，星期五

Next.js 16.3：AI 改进

发布者

Aurora Scharff

@aurorascharff

Jude Gao

gao_jude

随着 Next.js 16.3 预览版接近稳定发布，我们正在分享一系列关于其内部改进的帖子。第一篇帖子《即时导航》介绍了新的渲染和预取原语。这篇帖子则专注于 AI 改进。

自从 App Router 稳定以来，Next.js 已经取得了很大进展，而越来越多的这些进展是由像 Claude Code、Cursor 和 Codex 这样的代理编写的代码驱动的。

如果 Next.js 主要是为代理驱动的开发而设计，它会是什么样子？我们还没有完全实现这一点，但随着每次发布，我们正逐渐接近。Next.js 16 引入了 DevTools MCP 服务器，而 Next.js 16.2 带来了打包的文档和 next-browser，这是一个实验性的 CLI 工具，允许代理驱动真正的浏览器。

在 Next.js 16.3 中，我们通过以下方式扩展了这些功能：

• 通过 AGENTS.md 打包文档：让代理读取与版本匹配的文档，而不是其训练数据

• 专有技能：帮助代理驱动多步骤工作流程的技能

• 带有 React 检视功能的代理浏览器：从 agent-browser 驱动真正的浏览器并检查 React 状态

• 可操作错误：在覆盖层和终端中带有标记的修复菜单，用于即时洞察，包括“复制为提示”按钮和为代理撰写的每条规则文档

• 更小、更专注的 MCP 服务器：新的构建诊断工具，知识库工具已退役

• Markdown 格式的文档：在任何文档 URL 后添加 .md 以获取纯 Markdown 版本

通过 AGENTS.md 打包文档

在我们之前的 16.2 版本中，我们开始将 Next.js 文档打包到您的项目中，以便代理可以本地阅读。使用 create-next-app 在 16.2 或更高版本创建的项目已经将 AGENTS.md 指向这些文档。

在 16.3 中，next dev 会自动编写和更新该指针，因此在您升级时现有项目可以保持最新。在 16.1 或更早版本中，手动运行 agents-md codemod：

终端

npx
@next/codemod@canary
agents-md

这是 next dev 插入到您的 AGENTS.md 中的内容：

AGENTS.md

<!-- BEGIN:nextjs-agent-rules -->
# 这不是你所熟知的 Next.js
此版本有重大变更 —— API、惯例和文件结构可能都与你的训练数据不同。在编写任何代码之前，请阅读 `node_modules/next/dist/docs/` 中的相关指南。注意弃用通知。
<!-- END:nextjs-agent-rules -->

只有当 next dev 检测到环境中存在 AI 编码代理且标记尚未存在时，才会写入该块。标记外部的任何内容都会被保留，并且您可以通过在 next.config.ts 中设置 agentRules: false 来选择退出。即使它显示为未提交的更改，也请按原样提交该块。

专有技能

技能为代理提供特定于框架的上下文。您可能已经安装了我们早期的技能，这些技能来自 skills.sh，涵盖了 App Router 的惯例和缓存 API。随着打包的文档现在通过管理的 AGENTS.md 块到达代理，我们将退役这些技能。运行 npx skills update 以从已安装的集合中删除它们。

技能对于文档无法端到端驱动的多步骤工作流程仍然有用。Next.js 16.3 为这些情况新增了三个专有技能。

next-dev-loop

next-dev-loop 技能为你的编码代理提供了完整的开发反馈循环访问权限。它可以驱动浏览器、读取控制台、跟踪网络请求，并在迭代过程中检查 React 树。

• /_next/mcp，框架对路由、服务器日志和编译问题的视图。

• agent-browser，浏览器对 DOM、控制台、网络和 React 树的视图。

该技能需要 agent-browser 0.27 或更高版本。

npx
skills
add
vercel/next.js
--skill
next-dev-loop

然后提示你的代理，例如：

每次编辑后，使用 next-dev-loop 技能验证页面在运行时是否仍正常工作。

Claude 正在通过 next-dev-loop 进行编辑、编译、重新加载和检查结果。

next-cache-components-adoption

next-cache-components-adoption 技能会在你的项目中启用缓存组件，并逐个功能地通过应用进行操作，每次在功能边界处与你确认，以确保你对范围保持控制。它有两种工作模式：

• 逐步增量模式。首先提交一个机械的 PR，将所有路由从验证中排除，这样你可以在后续的 PR 中逐步发布功能。

• 直接模式。在一个分支上一次性启用所有路由。

在两种模式中，每个功能的循环是一样的：技能读取可操作的错误，获取该错误链接到的文档页面，将修复应用到路由，然后通过 next-dev-loop 驱动浏览器，确认静态外壳渲染了正确的内容。

npx
skills
add
vercel/next.js
--skill
next-cache-components-adoption

使用 next-cache-components-adoption 技能在该项目中启用缓存组件。

Claude 正在启用缓存组件，并逐个功能地采用路由。

next-cache-components-optimizer

next-cache-components-optimizer 技能通过针对静态外壳运行观察-修复-迭代循环，优化缓存组件路由以实现即时导航。当你希望某个路由感觉更快时，使用它，通过扩展静态外壳，使页面的更多部分在请求时就准备就绪。它有两种工作模式：

• 页面渲染模式。通过将 I/O 推得更深到组件树中或使用 'use cache' 进行缓存，增加单个页面静态渲染的部分。

• 导航模式。确保页面之间的导航是即时的。下一页所需的任何服务器端工作都会流式传输，而不会阻塞导航。

该技能通过 next-dev-loop 在每次更改前后进行截图。如果截图相同，更改将被回滚。

npx
skills
add
vercel/next.js
--skill
next-cache-components-optimizer

使用 next-cache-components-optimizer 技能在 /dashboard 上增加静态外壳。

Claude 正在扩展路由的静态外壳，并使用更改前后的截图来验证更改是否成功。

带有 React 检查的代理浏览器

Next.js 16.2 的实验性 next-browser 已合并到通用的 agent-browser CLI 中。next-browser 的所有功能现在都在 agent-browser 中，并且它不仅适用于 Next.js。

版本 0.27 在现有的 DOM、控制台、网络和 Web Vitals 访问功能基础上，新增了 React DevTools 的内省功能。代理可以使用 react tree 列出组件树，使用 react inspect <fiberId> 检查单个组件，使用 react renders start 和 react renders stop 对重新渲染进行性能分析，并使用 react suspense --only-dynamic --json 查看是什么导致了渲染阻塞。Next-dev-loop 技能在启动时会启用 agent-browser 并激活 React DevTools，因此这些命令在验证过程中可用。

要安装或升级，请运行 npm install -g agent-browser@^0.27。使用 React 命令时，需要在启动时添加 --enable react-devtools 参数。

可操作的错误

启用缓存组件后，服务器端的 await 是一个选择。Instant Insights 将这个选择以一个带有三个具体修复方案的错误形式呈现：

• 在 <Suspense> 边界后流式传输数据

• 使用 use cache 进行缓存

• 使用 export const instant = false 阻止路由

这些是产品决策，各有取舍。选择正确的方案需要上下文，无论你是自己做出选择，还是你的编码代理做出选择。

Instant Insights 修复提示

Instant Insights 会以带有标签修复方案的形式展示错误，并提供一个“复制为提示”的按钮，将所选修复方案打包成一个可粘贴的提示，供你的编码代理使用。该提示会引导代理识别出失败的代码，阅读匹配的错误页面，应用标准模式，并通过 next-dev-loop 技能在运行时验证结果。

例如，假设我们在页面中遇到了一个未缓存的 fetch() 调用。我们选择“流式传输”并点击“复制为提示”，就会得到如下提示：

你的代理可以使用的提示

将 [Stream] "Wrap in or move into Suspense" 修复应用到该项目中 Next.js Insight 提出的问题上。
步骤：
1. 确保在开始之前可以使用浏览器进行调试。在重新加载路由并查看渲染结果之前，修复效果不会被验证。如果你还没有设置浏览器工具，请先安装 next-dev-loop 技能（https://github.com/vercel/next.js/tree/canary/skills/next-dev-loop）。
2. 识别下面错误块中的失败代码。这可能是数据访问调用、钩子调用、元数据或视口导出，或组件。将修复集中在该代码上。如果你认为相关的重构（如兄弟组件、共享布局、包装边界）会使结果明显更好，请命名它并事先与用户确认，不要在没有通知的情况下扩大范围。
3. 阅读规则文档（https://nextjs.org/docs/messages/blocking-prerender-dynamic）以获得完整的 Insight 解释，然后阅读修复部分（https://nextjs.org/docs/messages/blocking-prerender-dynamic#wrap-in-or-move-into-suspense）。选择与失败代码匹配的“### Patterns”下的模式，然后在编辑之前阅读“### Gotchas” —— 它们列出了容易被忽略的约束。使用页面中的规范导入和代码结构，不要随意更改。
4. 将选定的模式应用到步骤 2 中识别的代码上。不要用新注释来叙述更改 —— 代码本身应该能够解释清楚。只有在 *why* 不明确时（例如，有明确原因的 Block）才留下注释。
5. 在运行时验证修复。开发环境中的 Insight 清除确认构建是成功的，但不能确认实际渲染内容。在浏览器中重新加载路由，确认静态外壳仍然先绘制，任何新的 <Suspense> 备用内容会解析为真实内容。
6. 检查外壳是否为空。如果 <Suspense> 边界放置得过高（如整个页面主体周围，或使用 `fallback={null}`），可能会导致构建报告外壳，而外壳本身却没有任何内容，所有内容都流式传输。如果你看到这种情况，请将边界向下移动，更接近实际的动态读取。
7. 如果修复影响了共享代码（如布局、包装器、侧边栏），请重新检查其他路由 —— 外壳级别的更改可以修复一个路由，但可能破坏另一个。受影响路由的前后截图是一个有用的合理性检查：可见的 UI 可能看起来一样（修复通常只是更改外壳中的内容与流式传输内容），但如果任何视觉效果退化，你将看到。
当你向用户回复时，只需用普通文本总结你做了什么更改以及原因。不要将此检查列表作为标题、部分或带有“Verification”或“Scope”标签的项目符号列表返回 —— 这些是你的内部步骤，而不是用户的报告。
## 错误类型
Blocking Route
## 错误信息
路由 "/products/[slug]"：Next.js 在预渲染或导航过程中遇到了未缓存的数据。
`fetch(...)` 或 `connection()` 在 `<Suspense>` 之外被访问，导致路由无法预渲染或导航无法即时进行，从而导致用户体验变慢。
在 ProductPage (app/products/[slug]/page.tsx:52:32)
## 代码片段
50 |   props: PageProps<"/products/[slug]">,
51 | ) {
> 52 |   const featured = await fetch(`/api/products/${slug}`);
|                                ^
53 |
54 |   return (
55 |     <div className="space-y-4">
Next.js 版本：16.3.0 (Turbopack)

结构化的控制台输出

在下一次开发过程中，终端中会显示相同的修复菜单，而在下一次构建过程中，当错误阻止预渲染时，也会显示该菜单。这意味着从 next build、CI 日志或任何没有开发叠加层的终端会话中读取错误的代理，仍然可以获取到相同的带标签的修复建议，并且这些修复建议会链接到错误页面中对应的部分：

错误：Route "/products/[slug]"：Next.js 在预渲染或导航过程中遇到了未缓存的数据。
`fetch(...)` 或 `connection()` 在 `<Suspense>` 之外被访问，这会阻止路由的预渲染或导航的即时性，从而导致用户体验变慢。
修复方法：
- [stream] 使用 `<Suspense fallback={...}>` 包裹数据访问，提供一个占位符
https://nextjs.org/docs/messages/blocking-prerender-dynamic#wrap-in-or-move-into-suspense
- [cache] 使用 `"use cache"` 缓存数据访问（不适用于 `connection()`）
https://nextjs.org/docs/messages/blocking-prerender-dynamic#cache-the-component-or-data
- [block] 设置 `export const instant = false` 以静默此错误并允许阻塞路由
https://nextjs.org/docs/messages/blocking-prerender-dynamic#allow-blocking-route
在 ProductPage (app/products/[slug]/page.tsx:52:32)
50 |   props: PageProps<"/products/[slug]">,
51 | ) {
> 52 |   const featured = await fetch(`/api/products/${slug}`);
|                                ^
53 |
54 |   return (
55 |     <div className="space-y-4">

为代理编写的错误页面

叠加层和控制台会告诉你应该应用哪种修复方法。但每种修复方法都有其模式、限制、边缘情况和权衡，这些内容无法在错误信息中完整体现。因此，每个错误在 nextjs.org/docs/messages 上都有一个专门的页面，专为代理阅读而编写。每个修复部分都遵循相同的结构：经典的模式、与其他修复方法的权衡，以及代理在首次尝试时可能忽略的注意事项。

例如，我们的未缓存 fetch() 调用会导向 blocking-prerender-dynamic 页面，并在 Wrap in or move into Suspense 部分选择 Stream 修复方法。这是最常见的修复方法。在 /docs/messages 下还有 10 多个类似的页面，每个页面都有自己的考虑因素。代理在自行应用修复方法时，可以阅读权衡内容并选择最适合的方案。

结合“复制为提示”按钮、结构化的控制台输出以及每条规则的文档页面，代理可以获得编写高性能、符合习惯的缓存组件代码所需的上下文。

更小、更专注的 MCP 服务器

DevTools MCP 服务器以前包含自己的 Next.js 知识库，以及升级和缓存组件的辅助工具。现在，捆绑的文档已经承担了这些功能，因此我们从 MCP 服务器中移除了这些工具，就像我们之前从知识技能中移除它们一样。

在 16.3 版本中，MCP 服务器新增了两个编译工具：get_compilation_issues 用于整个项目，compile_route 用于单个路由。代理通常会运行 next build 来检查代码是否编译，这在你仍在编辑代码时是过度的。这些工具可以更快地从运行的开发服务器中回答相同的问题。

像 next-dev-loop 这样的技能会直接调用底层的 /_next/mcp 端点，因此它们无需任何额外设置即可工作。要从自己的代理客户端使用这些工具，请将 next-devtools-mcp 添加到你的 .mcp.json 文件中。客户端会自动找到正在运行的 next dev。

将 .md 添加到任何 Next.js 文档 URL 后，即可获取该页面的纯 Markdown 格式内容。这适用于 nextjs.org/docs 上的任何页面，包括每个错误页面。发送 Accept: text/markdown 请求头的客户端也可以获取 Markdown 格式的内容。

完整的目录位于 /docs/llms.txt，而 /docs/llms-full.txt 将所有文档页面合并为一个文件。两者都遵循 llms.txt 的格式约定，因此任何已经能够读取 llms.txt 的代理都可以以相同的方式读取 Next.js 文档。

反馈和社区

分享你的反馈，共同塑造 Next.js 的未来：

• GitHub Discussions

• GitHub Issues

• Discord 社区