当前位置：首页 > news >正文

Next.js 不写给人类了？新版本的四个改动，全是给 AI Agent 准备的

news 2026/8/17 7:50:19

Next.js 发布了 16.2，没有大的 Breaking Change，也没有新的渲染模式，这次更新的重心只有一个：让 AI Agent用起来更顺手。

说白了，这是一次专门为 AI Agent量身打造的版本。

四项改动，每一项都在解决同一类问题：AI Agent在操作 Next.js 项目时，经常像个蒙眼摸象的人，它能写代码，但"看不见"运行时的状态，不知道浏览器报了什么错，不清楚页面渲染的真实情况，也搞不清楚开发服务器有没有在跑。

这次更新，Vercel 开始系统性地给Agent"补眼睛"。

AGENTS.md 进了脚手架，Agent从第一行代码开始就有文档可读

这是改动里信息量最大的一条。

create-next-app现在会默认生成一个AGENTS.md文件。这个文件的内容不复杂，就一条指令：在写任何 Next.js 相关代码之前，先去node_modules/next/dist/docs/读对应的文档。

# Next.js: ALWAYS read docs before coding Before any Next.js work, find and read the relevant doc in `node_modules/next/dist/docs/`. Your training data is outdated — the docs are the source of truth.

这背后有个很实在的判断：AI Agent的训练数据是有截止日期的，它对 Next.js 的"记忆"可能停在半年甚至一年前。App Router 的某个 API 已经改了，Agent却还在用旧写法，这类问题一直是用 AI 写 Next.js 时的隐患。

把文档直接打包进 npm 包，放在本地，再通过AGENTS.md告诉Agent"你要先读这里"，相当于给Agent配了一本随时翻阅的官方手册。

Vercel 内部做过评测：给Agent提供捆绑文档，Next.js 相关任务的通过率达到 100%；而依赖技能检索（让Agent自己去搜文档）的方式，最高只能到 79%。差距不是一点点。

原因其实不难理解。让Agent"在需要时主动去查"，听起来合理，但Agent往往不知道自己什么时候"需要"。文档触手可及，Agent总是能读到；文档需要主动检索，Agent可能直接跳过了这一步。

对于已有项目，升级到 16.2 后node_modules/next/dist/docs/里就有内容了，只需要手动在项目根目录加两个文件：

AGENTS.md，放上那段"先读文档"的指令
CLAUDE.md（如果用 Claude Code），里面写@AGENTS.md，让 Claude 把它纳入上下文

更早版本的项目可以用官方提供的 codemod 自动生成：

npx @next/codemod@latest agents-md

浏览器报错，现在会直接转发到终端

这个改动不起眼，但对使用 AI Agent开发的人来说很实用。

以前，客户端报错只出现在浏览器控制台。对人类开发者来说，切一下 tab 就能看到，习惯了。但 AI Agent基本只盯着终端，浏览器控制台对它来说是不存在的。所以Agent经常能把服务端跑通，但前端一渲染就出错，它却无从知晓。

16.2 开始，Next.js 默认把浏览器错误转发到开发服务器的终端。Agent不用开浏览器，直接在终端就能看到客户端报什么。

转发级别可以自定义，在next.config.ts里加一行就行：

const nextConfig = { logging: { browserToTerminal: true, // 'error' — 只转发错误（默认值） // 'warn' — 转发警告和错误 // true — 转发所有 console 输出 // false — 关闭转发 }, }; export default nextConfig;

对人类来说，这个功能也有价值，毕竟不用反复在终端和浏览器之间切换了。但最大的受益者还是Agent。

开发服务器有锁文件了，重复启动不再出现诡异问题

AI Agent有个很常见的毛病：不确定开发服务器有没有在跑，于是直接再来一次next dev。两个进程同时跑同一个项目，端口冲突，状态混乱，Agent开始原地打转。

16.2 引入了锁文件机制，运行next dev时会在.next/dev/lock里写入当前进程的 PID、端口号和访问地址。如果有第二个next dev试图启动，它会读到这个文件，然后给出明确的报错信息：

Error: Another next dev server is already running. - Local: http://localhost:3000 - PID: 12345 - Dir: /path/to/project - Log: .next/dev/logs/next-development.log Run kill 12345 to stop it.

PID、地址、日志路径，全给出来了。Agent看到这条错误，要么直接 kill 掉旧进程，要么连接到已有服务器，不再傻乎乎地继续重试。

同样的逻辑也适用于next build，防止两个构建进程同时运行，避免产物被污染。

这个改动思路很简单，但它解决的问题真实存在，而且在 AI 辅助开发的工作流里频繁出现。

实验性功能：给Agent一个终端版 DevTools

前三条改动是在现有 Next.js 框架内调整，最后这条的思路更激进一些：专门出了一个工具，让Agent通过终端命令查看浏览器里发生的事情。

这个工具叫@vercel/next-browser，目前还是实验性的。核心能力是把 React DevTools 和 Next.js 的调试信息，用纯文本形式暴露给Agent。

Agent可以通过命令行获取这些信息：

React 组件树，包括 props、hooks、state 和对应的源码位置
PPR（Partial Prerendering）分析，哪些区域是静态壳，哪些是动态内容，什么东西阻塞了静态渲染
浏览器网络请求，包括 Server Actions
控制台日志和错误
页面截图和加载过程的帧序列

举个具体例子。有个博客页面，Agent想搞清楚为什么整个页面都是动态渲染，没有静态壳。它可以这么操作：

next-browser ppr lock # 锁定 PPR 模式，只渲染静态壳 next-browser goto /blog/hello # 导航到目标页面

如果页面只剩一个加载骨架，说明静态内容一个字都没进壳里。然后：

next-browser ppr unlock

输出会告诉Agent哪个函数是罪魁祸首，在第几行，下一步该怎么改：

# PPR Shell Analysis # 1 dynamic hole, 1 static blocked by: - getVisitorCount (server-fetch) owner: BlogPost at app/blog/[slug]/page.tsx:5 next step: Push the fetch into a smaller Suspense leaf

Agent拿到这份报告，知道要做什么了：把getVisitorCount挪到单独的Suspense边界里，主体内容就能进静态壳，用户访问时秒出标题和正文，访问量计数器再单独流式加载。

用skills安装就能用：