Next.js 16.3 新特性全解析 AI 驱动开发与 Instant Navigations 实战指南

文章首发于: https://feinterview.poetries.top/blog/nextjs-16-3-ai-improvements-guide

在本篇文章中，我们将从浅入深，和大家一起学习以下知识：

• Next.js 16.3 这个版本到底更新了什么，为什么官方把「给 AI Agent 用」当成一条主线
• Cache Components 与 Instant Navigations 的核心心智模型：一次 await 就是一次「Stream / Cache / Block」三选一
• Partial Prefetching 如何把「每个链接一次预取请求」改成「每个路由一个可复用壳」，以及 Navigation Inspector、instant() 测试助手怎么用
• AGENTS.md 内置文档机制：next dev 如何自动让 Claude Code / Cursor / Codex 读到与项目版本匹配的文档
• 三个官方 Skills（next-dev-loop、next-cache-components-adoption、next-cache-components-optimizer）分别解决什么问题、怎么安装、怎么写提示词
• agent-browser 0.27 新增的 React 内省能力：让 Agent 直接查看组件树、诊断 Suspense 阻塞、分析重渲染
• Actionable Errors 可执行错误体系：报错自带修复菜单、一键复制给 Agent 的 prompt、专为 Agent 编写的错误文档页
• 精简后的 DevTools MCP Server 新增的两个编译诊断工具，以及「任意文档 URL 加 .md 后缀」的 Markdown 文档访问方式

写 Next.js 应用这几年，大家多少都被两件事折磨过：一是 Server Components 时代「点了链接没反应，等服务器回包页面才切换」的导航迟钝感；二是让 AI 编码助手写 Next.js 代码时，它凭训练数据里的旧版本 API 一顿输出，Pages Router 和 App Router 的写法混在一起，改起来比自己写还累。Next.js 16.3（当前处于 Preview，即将稳定）把这两个痛点一起端上了桌：Instant Navigations 让服务端驱动的应用拥有 SPA 级的瞬时导航，而整套 AI Improvements 则让 Agent 读得到版本匹配的文档、跑得动完整的开发反馈闭环、看得懂每一个报错该怎么修。读完这篇你会得到：全部新特性的开启配置、每个功能的可运行示例、官方 Skills 的实际用法，以及在存量项目里渐进落地的路线建议。

一、Next.js 16.3 版本全景

Next.js 16.3 的更新在官方博客里拆成了系列文章发布，两篇主线分别是：

• Instant Navigations （2026 年 6 月 25 日）：全新的渲染与预取原语，让导航像 SPA 一样瞬时
• AI Improvements （2026 年 6 月 26 日）：面向 AI 编码助手的一整套工程设施

除此之外，这个版本还包含基于 Node.js 原生流的渲染改进、更快的本地 dev 启动速度等底层优化。官方在博客里说了一句很有信息量的话：「如果 Next.js 是为 Agent 驱动开发而设计的，它会长什么样？」 ------从 Next.js 16 内置 DevTools MCP Server，到 16.2 的内置文档与实验性 next-browser CLI，再到 16.3 这一整套，官方路线已经非常明确：把「人看的文档 / 人读的报错 / 人操作的浏览器」逐一改造成「Agent 也能消费」的形态。

尝鲜方式很简单，安装 preview 标签即可：

npm install next@preview

注意：16.3 目前是 Preview 版本，存在少量已知问题（比如 Partial Prefetching 开启时在 shell 里访问 params 导致的阻塞不会上报为 Instant Insight、Safari 下 Insights 工具有兼容问题，开发时建议用 Chrome / Firefox）。生产项目建议等稳定版，但特性心智模型现在就可以开始建立。

下面先讲 Instant Navigations，因为 AI 篇的很多能力（可执行错误、Skills）都建立在它引入的概念之上。

二、Instant Navigations 让服务端应用拥有 SPA 手感

2.1 问题：服务端驱动的导航为什么「感觉慢」

在服务端驱动的应用里，一次导航通常要走完整的网络往返：

1. 用户点击链接
2. 什么都没发生（等服务器）
3. 服务器响应，下一页出现

而客户端驱动的 SPA 是这样：

1. 用户点击链接
2. 立刻看到下一页的骨架壳（部分数据还在加载）
3. 服务器响应，页面完整呈现

对报纸、博客这类内容站，前者没什么问题；但对交互密集的应用，后者的「点击立即有反馈」明显体验更好------这也是很多团队宁愿放弃服务端模型也要做 SPA 的核心原因。Next.js 16.3 的答案是：两个都要 。服务端的能力全保留，导航像 SPA 一样瞬时。

2.2 第一步：开启 Cache Components

所有新行为都挂在 cacheComponents 这个开关之下（未来的大版本会变成默认值）：

// next.config.ts
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  cacheComponents: true,
  // ...
};

export default nextConfig;

这个开关背后是 Next.js 过去一年的方向回归：默认动态、没有隐式缓存。所有缓存行为都必须显式声明，不再有「fetch 默认被缓存了但你不知道」的暗坑。

2.3 核心心智模型：Stream、Cache 或 Block 三选一

开启之后，路由里每一次服务端 await 都变成一个需要你做决定的产品选择 。开发环境的 Instant Insights 面板会自动把「拖慢导航的异步操作」以错误形式呈现，并给出三个带标签的修复选项：

选项	做法	用户看到什么	适用场景
Stream	用 <Suspense fallback={...}> 包住数据访问	立刻看到 loading 占位，内容随后流入	数据个性化、实时性强（库存、消息流）
Cache	给组件或数据函数加 'use cache'	立刻看到上次缓存的 UI（跨请求复用）	数据变化慢、可跨用户复用（商品详情、文档）
Block	路由里 export const instant = false	等服务器返回后整页切换	明确不想给用户看骨架壳的页面（如博客正文）

Stream 和 Cache 两条路都能让导航瞬时；Block 是显式声明「这条路由我就要服务端阻塞」，声明之后报错消失。比如一个博客站不想让文章页出现加载壳：

// app/posts/[slug]/page.tsx
export const instant = false;

这套设计最大的价值在于把控制权交还给开发者：想要点击立即响应就 Stream 或 Cache，想要延迟导航就 Block------但你必须「选一个」，而不是无意识地写出慢导航。

2.4 Partial Prefetching 按路由预取可复用的壳

导航要真正瞬时，还得解决「客户端到服务器的网络间隙」。以前 Next.js 的做法是给视口里每一个链接 发一个预取请求------侧边栏挂二十个聊天链接就发二十个请求，Network 面板一滚动就是一屏请求，官方自己都承认「确实很离谱」。

16.3 借鉴了 SPA 按路由做代码分割的思路：不再按链接预取页面，而是按路由预取一个可复用的壳（shell） 。二十个 /chat/[id] 链接现在只触发一次 /chat/[id] 路由壳的预取，壳缓存在客户端整个会话期间复用。开启方式：

// next.config.ts
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  cacheComponents: true,
  partialPrefetching: true,
  // ...
};

export default nextConfig;

如果某些链接想要比壳更丰富的预取内容（比如聊天页头部要「秒出」），可以按链接开启：

<Link href={`/chat/${id}`} prefetch={true}>
  {chat.title}
</Link>

即便如此，Next.js 也不会把整条路由渲染到底，而是只渲染到「同步可用或标了 'use cache'」的深度------预取不再是全有或全无的选择：路由壳是保底，<Link prefetch> + 'use cache' 是按需加码。默认的按链接预取只覆盖构建期已知的内容，如果不在乎额外服务器负载，还可以再进一步：

// 把按链接预取扩展到请求期的缓存内容
export const prefetch = 'allow-runtime';

官方还在 v0.app 上提前吃了自己的狗粮：用 Instant Insights 找出慢导航路由并逐个修复后，从点击到路由切换的耗时曲线大幅下降。想看小而全的开源示例，可以研究官方的音乐播放器 Next Beats（next-beats.dev，源码在 GitHub 的 vercel-labs/next-beats）。

2.5 配套工具：Navigation Inspector 与 instant() 测试助手

Navigation Inspector 是 Next.js DevTools 新增的面板，可以把每次导航「暂停在壳阶段」，直观看到任意路由预取到的壳里有什么、哪些内容要等网络回包，点「Resume」再继续到完整页面。

防回归则交给 @next/playwright 的 instant() 助手------在断言块内，所有可见性断言都必须不等网络就成立：

import { expect, test } from '@playwright/test';
import { instant } from '@next/playwright';

test('product title is available immediately', async ({ page }) => {
  await page.goto('/products/shoes');

  // 断言点击后无需等待网络就应可见的内容
  await instant(page, async () => {
    await page.click('a[href="/products/hats"]');
    await expect(page.locator('h1')).toContainText('Baseball Cap');
    await expect(page.getByText('Checking inventory...')).toBeVisible();
  });

  await expect(page.getByText('12 in stock')).toBeVisible();
});

这样重构之后某条「本应瞬时」的路由退化成阻塞导航，CI 里立刻会红。

三、AGENTS.md 内置文档 让 Agent 读版本匹配的文档而不是训练数据

这是 16.3 AI 篇里最「四两拨千斤」的一个改动。AI 助手写 Next.js 代码最大的坑是训练数据滞后 ：模型记忆里的 API 可能停留在一两个大版本之前。16.2 开始 create-next-app 会把整套文档打包进项目（node_modules/next/dist/docs/），16.3 更进一步：next dev 会自动在项目的 AGENTS.md 里写入并更新一个指针块：

<!-- BEGIN:nextjs-agent-rules -->

# This is NOT the Next.js you know

This version has breaking changes --- APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.

<!-- END:nextjs-agent-rules -->

几个工程细节值得注意：

• 这个块只在 next dev 检测到环境里有 AI 编码助手、且标记不存在时才写入；标记之外的内容原样保留
• 不想要可以在 next.config.ts 里配置 agentRules: false 退出
• 官方建议把这个块原样 commit 进仓库，即使它以未提交变更的形式出现
• 16.1 及更早版本的项目需要手动跑 codemod：

npx @next/codemod@canary agents-md

一句话总结这个机制的价值：它把「Agent 该读哪份文档」从约定 变成了框架自动维护的基础设施 ，升级 Next.js 时文档指针自动跟着走。

四、三个官方 Skills 让 Agent 跑通多步工作流

文档解决「知识」问题，但多步工作流 （改代码 → 编译 → 刷新浏览器 → 看渲染结果 → 迭代）光靠文档驱动不了，这就是 Skills 的定位。此前社区版的 knowledge 类 Skills（App Router 约定、缓存 API 之类）已随内置文档机制退役（npx skills update 可移除），16.3 新增的三个官方 Skills 全部是 workflow 型，放在 vercel/next.js 仓库的 skills/ 目录下。

4.1 next-dev-loop 完整的开发反馈闭环

这个 Skill 让 Agent 同时拿到两个视角：

• /_next/mcp：框架视角------路由表、服务端日志、编译问题
• agent-browser ：浏览器视角------DOM、控制台、网络请求、React 组件树

安装与使用：

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

然后在提示词里要求 Agent 每次改动后自查：

After every edit, verify the page still works at runtime using the next-dev-loop skill.

效果是 Agent 进入「编辑 → 编译 → 重载 → 检查渲染结果」的自动循环，不再是「改完代码就宣布完成」。它是另外两个 Skills 的运行时底座，要求 agent-browser 0.27+。

4.2 next-cache-components-adoption 存量项目开启 Cache Components

给老项目开 cacheComponents 最怕的就是「一开全项目报错」。这个 Skill 把迁移变成按 feature 逐个推进、每个边界处向你确认范围的过程，支持两种模式：

• Incremental 增量模式：先落一个纯机械的 PR，把所有路由 opt-out 校验，之后在后续 PR 里按 feature 逐步收编------期间不阻塞正常需求上线
• Direct 直接模式：在一个分支上就地收编所有路由

两种模式的单个 feature 循环是一样的：读取可执行错误 → 抓取错误链接的专属文档页 → 应用修复 → 通过 next-dev-loop 驱动浏览器确认静态壳渲染正确。

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

Adopt Cache Components in this project using the next-cache-components-adoption skill.

4.3 next-cache-components-optimizer 把静态壳越养越大

收编完成后，这个 Skill 负责优化：对单条路由跑「观察 → 修复 → 迭代」循环，让更多内容进静态壳、请求时刻就绪。两种模式：

• Page-render 模式 ：把 I/O 下推到组件树更深处、或用 'use cache' 缓存，提高单页可静态渲染的比例
• Nav 模式：确保页面间导航瞬时，下一页需要的服务端工作全部流式进入、不阻塞导航

它有个很工程化的细节：每次改动前后都通过 next-dev-loop 截图对比，两张截图一样就自动回滚该改动------防止 Agent 做无效或负优化。

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

Increase the static shell on /dashboard using the next-cache-components-optimizer skill.

五、agent-browser 0.27 带 React 内省的 Agent 浏览器

16.2 的实验性 next-browser 已合并进通用的 agent-browser CLI（不再局限于 Next.js 项目）。0.27 版本在原有 DOM / 控制台 / 网络 / Web Vitals 之上，新增了 React DevTools 级别的内省能力：

命令	作用
react tree	列出整棵组件树
react inspect <fiberId>	检查单个组件的 props / state
react renders start / react renders stop	录制并分析重渲染
react suspense --only-dynamic --json	查看是什么在拖住一次渲染（只看动态部分，输出 JSON）

安装或升级：

npm install -g agent-browser@^0.27

React 系列命令需要启动时带 --enable react-devtools 参数；如果通过 next-dev-loop Skill 启动则自动开启。对 Agent 来说，这相当于把「为什么这块 UI 没出来 / 为什么这里重渲染了 8 次」这类以前只能靠人肉打开 React DevTools 排查的问题，变成了几条可编排的命令。

六、Actionable Errors 每个报错都自带修复方案

这是我认为 16.3 里最能体现「为 Agent 重新设计」的部分。传统报错只说「哪里错了」，16.3 的可执行错误还告诉你（和你的 Agent）「有哪几种修法、各自的取舍、以及去哪读细节」。

6.1 Instant Insights 修复菜单与一键复制 prompt

开发覆盖层里的每条 Instant Insight 都带标签化的修复选项（对应第二节的 Stream / Cache / Block），旁边有一个 Copy prompt 按钮：选中某个修法后点击，会生成一份可直接粘贴给编码 Agent 的完整提示词。这份 prompt 的结构非常讲究，它会引导 Agent：

1. 先确认能驱动浏览器（否则先装 next-dev-loop）
2. 从错误块里精准定位出问题的代码，不擅自扩大改动范围（想做相关重构必须先向用户报备）
3. 阅读该错误的规则文档页与所选修法章节，按 Patterns 里的规范写法改，先读 Gotchas 再动手，不要即兴发挥
4. 应用修复，不写叙事性注释
5. 运行时验证 ：覆盖层里错误消失只代表构建满意，还要在浏览器里重载路由，确认静态壳先绘制、新的 Suspense fallback 能解析为真实内容
6. 检查壳不为空：Suspense 边界包得太高（包住整个页面主体、或 fallback={null}）会出现「构建报告有壳但壳里空空如也」的假象，要把边界下移到真正的动态读取附近
7. 改动如果碰了共享代码（layout、侧栏），要回查兄弟路由有没有被壳级变更破坏

这七步几乎就是一位资深工程师 review 此类修复时的完整检查清单------现在它被打包进了每一次 Copy prompt。

6.2 终端里的结构化输出

同样的修复菜单也会出现在 next dev 的终端输出里，next build 在预渲染被错误中断时也会输出。这意味着从 CI 日志、构建输出这些没有开发覆盖层的地方读错误的 Agent，拿到的信息和覆盖层完全等价：

Error: Route "/products/[slug]": Next.js encountered uncached data during prerendering or a navigation.

`fetch(...)` or `connection()` accessed outside of `<Suspense>` prevents the route from being prerendered or the navigation from being instant, leading to a slower user experience.

Ways to fix this:
  - [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access
    https://nextjs.org/docs/messages/blocking-prerender-dynamic#wrap-in-or-move-into-suspense
  - [cache] Cache the data access with `"use cache"` (does not apply to `connection()`)
    https://nextjs.org/docs/messages/blocking-prerender-dynamic#cache-the-component-or-data
  - [block] Set `export const instant = false` to silence this error and allow a blocking route
    https://nextjs.org/docs/messages/blocking-prerender-dynamic#allow-blocking-route
    at 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">

注意每个修法都直接链接到错误文档页的对应小节，Agent 不需要再全文检索。

6.3 为 Agent 编写的错误文档页

nextjs.org/docs/messages 下的每个错误页现在按统一结构编写，明确面向 Agent 消费：

• Patterns：该修法的规范代码形态（用页面上的标准 import 和代码结构，不要变体）
• Trade-offs：与其它修法相比的取舍
• Gotchas：第一次尝试最容易踩的约束

以最常见的 blocking-prerender-dynamic（未缓存的 fetch() 阻塞预渲染）为例，选择 Stream 就落在「Wrap in or move into Suspense」小节。类似的错误页有 10+ 个，各有自己的考量。覆盖层的修复菜单 + 终端结构化输出 + 按规则拆分的文档页 ，三件套凑齐后，Agent 写出的 Cache Components 代码才可能既高性能又符合惯例。

七、更小更专注的 MCP Server 与 Markdown 文档

7.1 MCP Server 的减法与加法

DevTools MCP Server 这次做了一轮「减法」：自带的 Next.js 知识库、升级助手、Cache Components 助手工具全部移除------这些职责已由内置文档接管（和 knowledge Skills 的退役是同一个逻辑）。同时做了两处「加法」，新增编译诊断工具：

工具	作用
get_compilation_issues	拿整个项目的编译问题
compile_route	编译单条路由

背后的观察很实在：Agent 经常为了确认「代码能不能编译」就跑一次完整的 next build，编辑迭代阶段这是杀鸡用牛刀。这两个工具直接从运行中的 dev server 拿答案，快得多。next-dev-loop 这类 Skills 直接调用底层 /_next/mcp 端点、零配置可用；自己的 Agent 客户端要用的话，把 next-devtools-mcp 加进 .mcp.json 即可，客户端会自动发现正在运行的 next dev。

7.2 任意文档 URL 加 .md 后缀

给任何 nextjs.org/docs 页面的 URL 追加 .md ，就能拿到纯 Markdown 版本（包括上面说的每个错误页）；请求头带 Accept: text/markdown 同样生效。索引遵循 llms.txt 约定：

• nextjs.org/docs/llms.txt：全部文档的索引
• nextjs.org/docs/llms-full.txt：所有文档打包成的单一文件

任何已经支持读取 llms.txt 的 Agent 都能用同样的方式消费 Next.js 文档，不再需要爬 HTML 再转格式。

八、落地建议 从升级到渐进收编

结合两篇官方博客和这套特性的依赖关系，给一条可操作的落地路径：

1. 先装 preview 体验 ：npm install next@preview，只开 cacheComponents: true，在开发环境观察 Instant Insights 报出来的慢导航路由------这一步不改任何业务代码，纯「体检」
2. 让 Agent 接管机械劳动 ：装 next-cache-components-adoption Skill，选 Incremental 模式先落 opt-out PR，再按 feature 逐个收编；每个错误用 Copy prompt 喂给 Agent，人只在 feature 边界做 review
3. 收编完成后开 partialPrefetching: true ：用 Navigation Inspector 检查各路由的壳内容是否符合预期，重交互路由用 next-cache-components-optimizer 把壳养大
4. 补上防回归 ：核心导航路径写 instant() 断言进 CI
5. 团队的 Agent 基建同步升级 ：确认 AGENTS.md 的管理块已提交、agent-browser 升到 0.27+、.mcp.json 加上 next-devtools-mcp

需要提醒的边界条件：这一切都是 opt-in 的，不开 cacheComponents 则行为与 16.2 一致；Preview 阶段不建议直接上生产；Safari 下的 Insights 工具目前有已知问题，开发调试用 Chrome / Firefox。

总结

Next.js 16.3 表面上是两组特性，底层其实是同一个判断：未来相当比例的 Next.js 代码将由 Agent 编写，框架必须为此重新设计自己的「接口」 ------这里的接口不只是 API，还包括文档（AGENTS.md 指针 + .md 后缀 + llms.txt）、报错（带修复菜单和文档链接的可执行错误）、工作流（三个官方 workflow Skills）和运行时观测（agent-browser 的 React 内省、MCP 的编译诊断）。而 Instant Navigations 则补上了 Server Components 时代最大的体验短板：通过 Stream / Cache / Block 三选一的显式决策 + 按路由预取可复用壳，让服务端驱动的应用第一次在「点击手感」上追平 SPA。如果你的项目还在 16.x 早期版本，至少先把 agents-md codemod 跑上------让你的 AI 助手读对文档，是所有收益里成本最低的一项。

参考

• Next.js 16.3: AI Improvements（官方博客）
• Next.js 16.3: Instant Navigations（官方博客）
• 官方 Skills 目录（vercel/next.js/skills）
• agent-browser（npm）
• Instant Navigation 指南（Preview 文档）
• blocking-prerender-dynamic 错误页
• Next.js MCP 指南
• llms.txt 约定> 文章首发于: https://feinterview.poetries.top/blog/nextjs-16-3-ai-improvements-guide

在本篇文章中，我们将从浅入深，和大家一起学习以下知识：

• Next.js 16.3 这个版本到底更新了什么，为什么官方把「给 AI Agent 用」当成一条主线
• Cache Components 与 Instant Navigations 的核心心智模型：一次 await 就是一次「Stream / Cache / Block」三选一
• Partial Prefetching 如何把「每个链接一次预取请求」改成「每个路由一个可复用壳」，以及 Navigation Inspector、instant() 测试助手怎么用
• AGENTS.md 内置文档机制：next dev 如何自动让 Claude Code / Cursor / Codex 读到与项目版本匹配的文档
• 三个官方 Skills（next-dev-loop、next-cache-components-adoption、next-cache-components-optimizer）分别解决什么问题、怎么安装、怎么写提示词
• agent-browser 0.27 新增的 React 内省能力：让 Agent 直接查看组件树、诊断 Suspense 阻塞、分析重渲染
• Actionable Errors 可执行错误体系：报错自带修复菜单、一键复制给 Agent 的 prompt、专为 Agent 编写的错误文档页
• 精简后的 DevTools MCP Server 新增的两个编译诊断工具，以及「任意文档 URL 加 .md 后缀」的 Markdown 文档访问方式

写 Next.js 应用这几年，大家多少都被两件事折磨过：一是 Server Components 时代「点了链接没反应，等服务器回包页面才切换」的导航迟钝感；二是让 AI 编码助手写 Next.js 代码时，它凭训练数据里的旧版本 API 一顿输出，Pages Router 和 App Router 的写法混在一起，改起来比自己写还累。Next.js 16.3（当前处于 Preview，即将稳定）把这两个痛点一起端上了桌：Instant Navigations 让服务端驱动的应用拥有 SPA 级的瞬时导航，而整套 AI Improvements 则让 Agent 读得到版本匹配的文档、跑得动完整的开发反馈闭环、看得懂每一个报错该怎么修。读完这篇你会得到：全部新特性的开启配置、每个功能的可运行示例、官方 Skills 的实际用法，以及在存量项目里渐进落地的路线建议。

一、Next.js 16.3 版本全景

Next.js 16.3 的更新在官方博客里拆成了系列文章发布，两篇主线分别是：

• Instant Navigations （2026 年 6 月 25 日）：全新的渲染与预取原语，让导航像 SPA 一样瞬时
• AI Improvements （2026 年 6 月 26 日）：面向 AI 编码助手的一整套工程设施

除此之外，这个版本还包含基于 Node.js 原生流的渲染改进、更快的本地 dev 启动速度等底层优化。官方在博客里说了一句很有信息量的话：「如果 Next.js 是为 Agent 驱动开发而设计的，它会长什么样？」 ------从 Next.js 16 内置 DevTools MCP Server，到 16.2 的内置文档与实验性 next-browser CLI，再到 16.3 这一整套，官方路线已经非常明确：把「人看的文档 / 人读的报错 / 人操作的浏览器」逐一改造成「Agent 也能消费」的形态。

尝鲜方式很简单，安装 preview 标签即可：

npm install next@preview

注意：16.3 目前是 Preview 版本，存在少量已知问题（比如 Partial Prefetching 开启时在 shell 里访问 params 导致的阻塞不会上报为 Instant Insight、Safari 下 Insights 工具有兼容问题，开发时建议用 Chrome / Firefox）。生产项目建议等稳定版，但特性心智模型现在就可以开始建立。

下面先讲 Instant Navigations，因为 AI 篇的很多能力（可执行错误、Skills）都建立在它引入的概念之上。

二、Instant Navigations 让服务端应用拥有 SPA 手感

2.1 问题：服务端驱动的导航为什么「感觉慢」

在服务端驱动的应用里，一次导航通常要走完整的网络往返：

1. 用户点击链接
2. 什么都没发生（等服务器）
3. 服务器响应，下一页出现

而客户端驱动的 SPA 是这样：

1. 用户点击链接
2. 立刻看到下一页的骨架壳（部分数据还在加载）
3. 服务器响应，页面完整呈现

对报纸、博客这类内容站，前者没什么问题；但对交互密集的应用，后者的「点击立即有反馈」明显体验更好------这也是很多团队宁愿放弃服务端模型也要做 SPA 的核心原因。Next.js 16.3 的答案是：两个都要 。服务端的能力全保留，导航像 SPA 一样瞬时。

2.2 第一步：开启 Cache Components

所有新行为都挂在 cacheComponents 这个开关之下（未来的大版本会变成默认值）：

// next.config.ts
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  cacheComponents: true,
  // ...
};

export default nextConfig;

这个开关背后是 Next.js 过去一年的方向回归：默认动态、没有隐式缓存。所有缓存行为都必须显式声明，不再有「fetch 默认被缓存了但你不知道」的暗坑。

2.3 核心心智模型：Stream、Cache 或 Block 三选一

开启之后，路由里每一次服务端 await 都变成一个需要你做决定的产品选择 。开发环境的 Instant Insights 面板会自动把「拖慢导航的异步操作」以错误形式呈现，并给出三个带标签的修复选项：

选项	做法	用户看到什么	适用场景
Stream	用 <Suspense fallback={...}> 包住数据访问	立刻看到 loading 占位，内容随后流入	数据个性化、实时性强（库存、消息流）
Cache	给组件或数据函数加 'use cache'	立刻看到上次缓存的 UI（跨请求复用）	数据变化慢、可跨用户复用（商品详情、文档）
Block	路由里 export const instant = false	等服务器返回后整页切换	明确不想给用户看骨架壳的页面（如博客正文）

Stream 和 Cache 两条路都能让导航瞬时；Block 是显式声明「这条路由我就要服务端阻塞」，声明之后报错消失。比如一个博客站不想让文章页出现加载壳：

// app/posts/[slug]/page.tsx
export const instant = false;

这套设计最大的价值在于把控制权交还给开发者：想要点击立即响应就 Stream 或 Cache，想要延迟导航就 Block------但你必须「选一个」，而不是无意识地写出慢导航。

2.4 Partial Prefetching 按路由预取可复用的壳

导航要真正瞬时，还得解决「客户端到服务器的网络间隙」。以前 Next.js 的做法是给视口里每一个链接 发一个预取请求------侧边栏挂二十个聊天链接就发二十个请求，Network 面板一滚动就是一屏请求，官方自己都承认「确实很离谱」。

16.3 借鉴了 SPA 按路由做代码分割的思路：不再按链接预取页面，而是按路由预取一个可复用的壳（shell） 。二十个 /chat/[id] 链接现在只触发一次 /chat/[id] 路由壳的预取，壳缓存在客户端整个会话期间复用。开启方式：

// next.config.ts
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  cacheComponents: true,
  partialPrefetching: true,
  // ...
};

export default nextConfig;

如果某些链接想要比壳更丰富的预取内容（比如聊天页头部要「秒出」），可以按链接开启：

<Link href={`/chat/${id}`} prefetch={true}>
  {chat.title}
</Link>

即便如此，Next.js 也不会把整条路由渲染到底，而是只渲染到「同步可用或标了 'use cache'」的深度------预取不再是全有或全无的选择：路由壳是保底，<Link prefetch> + 'use cache' 是按需加码。默认的按链接预取只覆盖构建期已知的内容，如果不在乎额外服务器负载，还可以再进一步：

// 把按链接预取扩展到请求期的缓存内容
export const prefetch = 'allow-runtime';

官方还在 v0.app 上提前吃了自己的狗粮：用 Instant Insights 找出慢导航路由并逐个修复后，从点击到路由切换的耗时曲线大幅下降。想看小而全的开源示例，可以研究官方的音乐播放器 Next Beats（next-beats.dev，源码在 GitHub 的 vercel-labs/next-beats）。

2.5 配套工具：Navigation Inspector 与 instant() 测试助手

Navigation Inspector 是 Next.js DevTools 新增的面板，可以把每次导航「暂停在壳阶段」，直观看到任意路由预取到的壳里有什么、哪些内容要等网络回包，点「Resume」再继续到完整页面。

防回归则交给 @next/playwright 的 instant() 助手------在断言块内，所有可见性断言都必须不等网络就成立：

import { expect, test } from '@playwright/test';
import { instant } from '@next/playwright';

test('product title is available immediately', async ({ page }) => {
  await page.goto('/products/shoes');

  // 断言点击后无需等待网络就应可见的内容
  await instant(page, async () => {
    await page.click('a[href="/products/hats"]');
    await expect(page.locator('h1')).toContainText('Baseball Cap');
    await expect(page.getByText('Checking inventory...')).toBeVisible();
  });

  await expect(page.getByText('12 in stock')).toBeVisible();
});

这样重构之后某条「本应瞬时」的路由退化成阻塞导航，CI 里立刻会红。

三、AGENTS.md 内置文档 让 Agent 读版本匹配的文档而不是训练数据

这是 16.3 AI 篇里最「四两拨千斤」的一个改动。AI 助手写 Next.js 代码最大的坑是训练数据滞后 ：模型记忆里的 API 可能停留在一两个大版本之前。16.2 开始 create-next-app 会把整套文档打包进项目（node_modules/next/dist/docs/），16.3 更进一步：next dev 会自动在项目的 AGENTS.md 里写入并更新一个指针块：

<!-- BEGIN:nextjs-agent-rules -->

# This is NOT the Next.js you know

This version has breaking changes --- APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.

<!-- END:nextjs-agent-rules -->

几个工程细节值得注意：

• 这个块只在 next dev 检测到环境里有 AI 编码助手、且标记不存在时才写入；标记之外的内容原样保留
• 不想要可以在 next.config.ts 里配置 agentRules: false 退出
• 官方建议把这个块原样 commit 进仓库，即使它以未提交变更的形式出现
• 16.1 及更早版本的项目需要手动跑 codemod：

npx @next/codemod@canary agents-md

一句话总结这个机制的价值：它把「Agent 该读哪份文档」从约定 变成了框架自动维护的基础设施 ，升级 Next.js 时文档指针自动跟着走。

四、三个官方 Skills 让 Agent 跑通多步工作流

文档解决「知识」问题，但多步工作流 （改代码 → 编译 → 刷新浏览器 → 看渲染结果 → 迭代）光靠文档驱动不了，这就是 Skills 的定位。此前社区版的 knowledge 类 Skills（App Router 约定、缓存 API 之类）已随内置文档机制退役（npx skills update 可移除），16.3 新增的三个官方 Skills 全部是 workflow 型，放在 vercel/next.js 仓库的 skills/ 目录下。

4.1 next-dev-loop 完整的开发反馈闭环

这个 Skill 让 Agent 同时拿到两个视角：

• /_next/mcp：框架视角------路由表、服务端日志、编译问题
• agent-browser ：浏览器视角------DOM、控制台、网络请求、React 组件树

安装与使用：

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

然后在提示词里要求 Agent 每次改动后自查：

After every edit, verify the page still works at runtime using the next-dev-loop skill.

效果是 Agent 进入「编辑 → 编译 → 重载 → 检查渲染结果」的自动循环，不再是「改完代码就宣布完成」。它是另外两个 Skills 的运行时底座，要求 agent-browser 0.27+。

4.2 next-cache-components-adoption 存量项目开启 Cache Components

给老项目开 cacheComponents 最怕的就是「一开全项目报错」。这个 Skill 把迁移变成按 feature 逐个推进、每个边界处向你确认范围的过程，支持两种模式：

• Incremental 增量模式：先落一个纯机械的 PR，把所有路由 opt-out 校验，之后在后续 PR 里按 feature 逐步收编------期间不阻塞正常需求上线
• Direct 直接模式：在一个分支上就地收编所有路由

两种模式的单个 feature 循环是一样的：读取可执行错误 → 抓取错误链接的专属文档页 → 应用修复 → 通过 next-dev-loop 驱动浏览器确认静态壳渲染正确。

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

Adopt Cache Components in this project using the next-cache-components-adoption skill.

4.3 next-cache-components-optimizer 把静态壳越养越大

收编完成后，这个 Skill 负责优化：对单条路由跑「观察 → 修复 → 迭代」循环，让更多内容进静态壳、请求时刻就绪。两种模式：

• Page-render 模式 ：把 I/O 下推到组件树更深处、或用 'use cache' 缓存，提高单页可静态渲染的比例
• Nav 模式：确保页面间导航瞬时，下一页需要的服务端工作全部流式进入、不阻塞导航

它有个很工程化的细节：每次改动前后都通过 next-dev-loop 截图对比，两张截图一样就自动回滚该改动------防止 Agent 做无效或负优化。

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

Increase the static shell on /dashboard using the next-cache-components-optimizer skill.

五、agent-browser 0.27 带 React 内省的 Agent 浏览器

16.2 的实验性 next-browser 已合并进通用的 agent-browser CLI（不再局限于 Next.js 项目）。0.27 版本在原有 DOM / 控制台 / 网络 / Web Vitals 之上，新增了 React DevTools 级别的内省能力：

命令	作用
react tree	列出整棵组件树
react inspect <fiberId>	检查单个组件的 props / state
react renders start / react renders stop	录制并分析重渲染
react suspense --only-dynamic --json	查看是什么在拖住一次渲染（只看动态部分，输出 JSON）

安装或升级：

npm install -g agent-browser@^0.27

React 系列命令需要启动时带 --enable react-devtools 参数；如果通过 next-dev-loop Skill 启动则自动开启。对 Agent 来说，这相当于把「为什么这块 UI 没出来 / 为什么这里重渲染了 8 次」这类以前只能靠人肉打开 React DevTools 排查的问题，变成了几条可编排的命令。

六、Actionable Errors 每个报错都自带修复方案

这是我认为 16.3 里最能体现「为 Agent 重新设计」的部分。传统报错只说「哪里错了」，16.3 的可执行错误还告诉你（和你的 Agent）「有哪几种修法、各自的取舍、以及去哪读细节」。

6.1 Instant Insights 修复菜单与一键复制 prompt

开发覆盖层里的每条 Instant Insight 都带标签化的修复选项（对应第二节的 Stream / Cache / Block），旁边有一个 Copy prompt 按钮：选中某个修法后点击，会生成一份可直接粘贴给编码 Agent 的完整提示词。这份 prompt 的结构非常讲究，它会引导 Agent：

1. 先确认能驱动浏览器（否则先装 next-dev-loop）
2. 从错误块里精准定位出问题的代码，不擅自扩大改动范围（想做相关重构必须先向用户报备）
3. 阅读该错误的规则文档页与所选修法章节，按 Patterns 里的规范写法改，先读 Gotchas 再动手，不要即兴发挥
4. 应用修复，不写叙事性注释
5. 运行时验证 ：覆盖层里错误消失只代表构建满意，还要在浏览器里重载路由，确认静态壳先绘制、新的 Suspense fallback 能解析为真实内容
6. 检查壳不为空：Suspense 边界包得太高（包住整个页面主体、或 fallback={null}）会出现「构建报告有壳但壳里空空如也」的假象，要把边界下移到真正的动态读取附近
7. 改动如果碰了共享代码（layout、侧栏），要回查兄弟路由有没有被壳级变更破坏

这七步几乎就是一位资深工程师 review 此类修复时的完整检查清单------现在它被打包进了每一次 Copy prompt。

6.2 终端里的结构化输出

同样的修复菜单也会出现在 next dev 的终端输出里，next build 在预渲染被错误中断时也会输出。这意味着从 CI 日志、构建输出这些没有开发覆盖层的地方读错误的 Agent，拿到的信息和覆盖层完全等价：

Error: Route "/products/[slug]": Next.js encountered uncached data during prerendering or a navigation.

`fetch(...)` or `connection()` accessed outside of `<Suspense>` prevents the route from being prerendered or the navigation from being instant, leading to a slower user experience.

Ways to fix this:
  - [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access
    https://nextjs.org/docs/messages/blocking-prerender-dynamic#wrap-in-or-move-into-suspense
  - [cache] Cache the data access with `"use cache"` (does not apply to `connection()`)
    https://nextjs.org/docs/messages/blocking-prerender-dynamic#cache-the-component-or-data
  - [block] Set `export const instant = false` to silence this error and allow a blocking route
    https://nextjs.org/docs/messages/blocking-prerender-dynamic#allow-blocking-route
    at 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">

注意每个修法都直接链接到错误文档页的对应小节，Agent 不需要再全文检索。

6.3 为 Agent 编写的错误文档页

nextjs.org/docs/messages 下的每个错误页现在按统一结构编写，明确面向 Agent 消费：

• Patterns：该修法的规范代码形态（用页面上的标准 import 和代码结构，不要变体）
• Trade-offs：与其它修法相比的取舍
• Gotchas：第一次尝试最容易踩的约束

以最常见的 blocking-prerender-dynamic（未缓存的 fetch() 阻塞预渲染）为例，选择 Stream 就落在「Wrap in or move into Suspense」小节。类似的错误页有 10+ 个，各有自己的考量。覆盖层的修复菜单 + 终端结构化输出 + 按规则拆分的文档页 ，三件套凑齐后，Agent 写出的 Cache Components 代码才可能既高性能又符合惯例。

七、更小更专注的 MCP Server 与 Markdown 文档

7.1 MCP Server 的减法与加法

DevTools MCP Server 这次做了一轮「减法」：自带的 Next.js 知识库、升级助手、Cache Components 助手工具全部移除------这些职责已由内置文档接管（和 knowledge Skills 的退役是同一个逻辑）。同时做了两处「加法」，新增编译诊断工具：

工具	作用
get_compilation_issues	拿整个项目的编译问题
compile_route	编译单条路由

背后的观察很实在：Agent 经常为了确认「代码能不能编译」就跑一次完整的 next build，编辑迭代阶段这是杀鸡用牛刀。这两个工具直接从运行中的 dev server 拿答案，快得多。next-dev-loop 这类 Skills 直接调用底层 /_next/mcp 端点、零配置可用；自己的 Agent 客户端要用的话，把 next-devtools-mcp 加进 .mcp.json 即可，客户端会自动发现正在运行的 next dev。

7.2 任意文档 URL 加 .md 后缀

给任何 nextjs.org/docs 页面的 URL 追加 .md ，就能拿到纯 Markdown 版本（包括上面说的每个错误页）；请求头带 Accept: text/markdown 同样生效。索引遵循 llms.txt 约定：

• nextjs.org/docs/llms.txt：全部文档的索引
• nextjs.org/docs/llms-full.txt：所有文档打包成的单一文件

任何已经支持读取 llms.txt 的 Agent 都能用同样的方式消费 Next.js 文档，不再需要爬 HTML 再转格式。

八、落地建议 从升级到渐进收编

结合两篇官方博客和这套特性的依赖关系，给一条可操作的落地路径：

1. 先装 preview 体验 ：npm install next@preview，只开 cacheComponents: true，在开发环境观察 Instant Insights 报出来的慢导航路由------这一步不改任何业务代码，纯「体检」
2. 让 Agent 接管机械劳动 ：装 next-cache-components-adoption Skill，选 Incremental 模式先落 opt-out PR，再按 feature 逐个收编；每个错误用 Copy prompt 喂给 Agent，人只在 feature 边界做 review
3. 收编完成后开 partialPrefetching: true ：用 Navigation Inspector 检查各路由的壳内容是否符合预期，重交互路由用 next-cache-components-optimizer 把壳养大
4. 补上防回归 ：核心导航路径写 instant() 断言进 CI
5. 团队的 Agent 基建同步升级 ：确认 AGENTS.md 的管理块已提交、agent-browser 升到 0.27+、.mcp.json 加上 next-devtools-mcp

需要提醒的边界条件：这一切都是 opt-in 的，不开 cacheComponents 则行为与 16.2 一致；Preview 阶段不建议直接上生产；Safari 下的 Insights 工具目前有已知问题，开发调试用 Chrome / Firefox。

总结

Next.js 16.3 表面上是两组特性，底层其实是同一个判断：未来相当比例的 Next.js 代码将由 Agent 编写，框架必须为此重新设计自己的「接口」 ------这里的接口不只是 API，还包括文档（AGENTS.md 指针 + .md 后缀 + llms.txt）、报错（带修复菜单和文档链接的可执行错误）、工作流（三个官方 workflow Skills）和运行时观测（agent-browser 的 React 内省、MCP 的编译诊断）。而 Instant Navigations 则补上了 Server Components 时代最大的体验短板：通过 Stream / Cache / Block 三选一的显式决策 + 按路由预取可复用壳，让服务端驱动的应用第一次在「点击手感」上追平 SPA。如果你的项目还在 16.x 早期版本，至少先把 agents-md codemod 跑上------让你的 AI 助手读对文档，是所有收益里成本最低的一项。

参考

• Next.js 16.3: AI Improvements（官方博客）
• Next.js 16.3: Instant Navigations（官方博客）
• 官方 Skills 目录（vercel/next.js/skills）
• agent-browser（npm）
• Instant Navigation 指南（Preview 文档）
• blocking-prerender-dynamic 错误页
• Next.js MCP 指南
• llms.txt 约定