Communitygithub.com

Next.js 开发验证循环

验证编辑 Next.js 应用代码后的运行时行为。使用此技能确认更改在运行中的应用程序中实际生效——而不仅仅是编译或类型检查通过。结合 /_next/mcp(Next.js 的视图)和 agent-browser(浏览器的视图)。需要运行中的 `next dev`。

Next.js 开发验证循环 是什么?

该技能专为使用 AI 智能体(如 Claude Code 或 Cursor)的开发者设计,用于在 Next.js 开发中建立可靠的编辑验证循环。它通过两个互补视角验证运行时行为:Next.js 自身的 `/next/mcp` 端点(了解框架特定的路由、RSC、服务器操作和编译问题)和 `agent-browser`(驱动真实 Chrome 浏览器,检查 DOM、控制台、网络和 React 状态)。该技能要求 Next.js 16.3+ 搭配 Turbopack 和 `agent-browser` 0.31.1+,提供严格的预检来确保两个视图均正常工作。预检步骤包括设置持久化浏览器会话以保持登录状态、探测 `/next/mcp` 工具列表、以及确认 Turbopack 可用。核心循环遵循先检查范围(询问运行中的应用以获取相关文件)、然后检查四种故障模式(编译、运行时错误、行为意图和 React 层级行为)的流程。指南还涵盖了常见陷阱,例如会话管理、浏览器状态过期以及 `agent-browser` 与 Next.js 输出之间的差异处理。

兼容平台~Claude Code~Codex CLI~Cursor✓Antigravity
npx skills add https://github.com/0n6k4v-Coder/skills/tree/HEAD/next.js/next-dev-loop

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

next-dev-loop

在 next dev 期间的编辑/验证节奏——做出更改,然后确认它在运行时实际生效,而不仅仅是类型或构建正常。

你可以通过两个视图验证同一个运行中的应用:

  • /_next/mcp —— Next.js 暴露的关于自身的 HTTP 端点。了解框架特定信息:路由、段、RSC、服务器操作、服务器日志以及 Next.js 看到的错误。调用 tools/list 获取当前可用的工具。
  • agent-browser —— 驱动真实 Chrome 的 CLI。了解与框架无关的浏览器相关事项:DOM、控制台、网络、React fiber、核心性能指标。在驱动之前,先运行 agent-browser skills get core 一次以获取与版本匹配的使用指南——不要凭记忆猜测子命令。

两个视图相互交叉验证。

要求

  • Next.js 16.3+ 搭配 Turbopack —— 需要 /_next/mcp 以及通过 get_compilation_issues 进行主动编译检查。
  • agent-browser >= 0.31.1 —— React 内省、工作树范围的 session id、幂等的 --restore 以及启动标志协调。

这些是硬性下限,而非软性偏好。如果缺少任何内容,请告知用户如何升级并停止。不要退回到搜索源代码或使用较弱的探测手段——此技能假定两个视图都处于以上版本条件下正常运行。

预检

每个会话执行一次,确认两个视图均正常运行。

  1. 在目标 URL 打开 agent-browser,并在存在时恢复保存的登录状态。 首先为此代码仓库派生一个稳定的会话 ID,并用于每个 agent-browser 命令:

    SESSION="$(agent-browser session id --scope worktree --prefix next-dev-loop)"
    export AGENT_BROWSER_SESSION="$SESSION"
    export AGENT_BROWSER_RESTORE="$SESSION"
    

    然后打开目标 URL:

    agent-browser --session "$SESSION" --restore --headed --enable react-devtools open <url>
    

    --scope worktree 可防止并行工作树和复制的仓库冲突。裸 --restore 将会话 ID 用作持久化键,在导航前加载保存的 cookie/localStorage(如果存在),并在关闭时自动保存状态。始终在 open 时传递所需的启动标志;agent-browser 会根据需要重用、重新启动或重启其作用域内的后台状态。

    浏览器是用户的。如果状态未恢复(首次运行、会话过期)且页面需要登录,则由用户驱动登录——暂停直到他们确认。登录后,继续使用同一会话和恢复上下文;agent-browser close 保存 cookie 状态,以便下次 open 时恢复。

  2. 探测 /_next/mcp(tools/list)——确认它可达并列出 get_compilation_issues:

    • 不可达 → 要么 next dev 未在运行,要么 Next.js 版本低于 16.3。检查 package.json 以区分,然后拒绝。
    • get_compilation_issues 不在列表中 → Next.js 版本低于 16.3。拒绝并告知用户升级。
  3. get_compilation_issues 同时作为 Turbopack 探测。错误响应 "Turbopack project is not available..." 表示用户正在使用 webpack。拒绝——需要 Turbopack。

  4. get_routes → 获取会话其余部分的路由映射。

循环

编辑前——缩小范围

询问运行中的应用,而非代码库。/_next/mcp 知道哪些文件渲染了当前路由;将它们用作搜索范围。随着代码库的增长,运行时内省保持低成本;而智能体搜索则不然。

编辑后——验证

四种故障模式。分别检查:

  • 编译 —— get_compilation_issues。
  • 运行时无错误 —— /_next/mcp(服务器和冒泡上来的浏览器错误都会在此处呈现)。
  • 行为符合预期 —— agent-browser 驱动页面;断言用户实际看到的内容。
  • React 层级行为 —— 启用 react-devtools 的 agent-browser 暴露组件树、props、state 和渲染计数。在此处进行框架层级的检查(额外渲染、服务器/客户端边界变化、Suspense 回退)——仅靠 DOM 断言会遗漏它们。

从 tools/list 或 agent-browser 手册中选择特定工具,而非凭记忆。

注意事项

  • 每个 agent-browser 命令必须知道你的会话和恢复密钥,否则它可能使用空的默认浏览器或无法保存登录状态。 最简单的方法:在你运行 agent-browser 的每个 shell 顶部同时导出 AGENT_BROWSER_SESSION="$SESSION" 和 AGENT_BROWSER_RESTORE="$SESSION"。如果你没有导出它们,请在每个命令上传递 --session "$SESSION" --restore。
  • 当两个视图不一致时,首先怀疑工具本身。 如果 agent-browser 说某个路由有问题,但 /_next/mcp 和服务器显示它已正常渲染,则更可能的原因是过时或错误的浏览器会话,而非真实 bug——在调试应用程序之前先协调视图。
  • 确认点击或导航:页面会有短暂的加载延迟,因此使用 wait --load networkidle 等待(无需指定路径容易出错),然后截图/读取以确认页面。避免使用 wait --url,除非你传递了链接的确切 href——猜测的或占位符路径不会匹配真实 URL,并在 25 秒后超时。
  • 空白读取、空截图、about:blank 或“无浏览器会话”错误——无论是在 open 之后还是点击之后(即使 open 报告了页面)——都是浏览器丢弃了页面(会话过时),而非路由损坏。使用 --session "$SESSION" --restore 在目标 URL 重新打开你的会话并重新截图;如果仍然是空白,运行 agent-browser --session "$SESSION" --restore close,然后重新打开。不要退回到使用 curl;它会绕过你要测试的浏览器。
  • React 内省输出在导航后会过时。重新运行。
  • /_next/mcp 的回复是 SSE 格式——使用 sed -n 's/^data: //p' 读取 data: 行上的 JSON(简单的 sed 's/^data: //' 会保留 event: 行导致解析失败)。
  • 非 3000 端口的开发服务器:读取 next dev 的横幅;设置 NEXT_MCP_URL=http://localhost:<port>/_next/mcp。
  • get_errors 和 get_page_metadata 需要至少一次导航才能填充数据。

参考

以下所有工具在预检通过后即可使用。如果 tools/list 中缺少其中任何一个,预检应该已经拒绝——请重新检查。

# /_next/mcp                 说明
get_project_metadata          projectPath、devServerUrl、bundler
get_routes                    文件扫描;无需浏览器会话
get_errors                    运行时 + 构建;需要浏览器会话;
                              包括开发服务器捕获的浏览器端错误
get_page_metadata             段 trie + routerType;需要浏览器会话;
                              用作发现哪个文件驱动路由的快捷方式
get_logs                     返回 logFilePath
get_server_action_by_id       哈希 ID → file + functionName
get_compilation_issues        仅 Turbopack;webpack 上报错
                              ("Turbopack project is not available")

清理

使用相同的会话和恢复上下文关闭会话: agent-browser --session "$SESSION" --restore close。close 保存该会话的 cookie 和存储,以便下一个循环的 --restore open 保持用户登录状态。保留 next dev 运行以供下一个循环使用。


next-dev-loop-<主题> 相关的技能(例如 next-dev-loop-rsc、next-dev-loop-debug)假定此预检已完成;它们直接从循环开始执行。

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

0n6k4v-Coder/skills

Translates Figma motion and animations into production-ready application code. Use when implementing animation/motion from a Figma design — user mentions "implement this motion", "add animation from Figma", "animate this component", provides a Figma URL whose node is animated, or when `get_design_context` returns motion data or instructs you to call `get_motion_context`.

0n6k4v-Coder/skills

Motion / animation context for the `use_figma` MCP tool — animating Figma nodes via manual keyframes, animation styles, easing, and timeline duration. Load alongside figma-use whenever a task involves adding, editing, or inspecting animation on a node.

0n6k4v-Coder/skills

Generate motion specification annotations from After Effects timeline data. Use when the user mentions "motion", "motion spec", "animation spec", "timeline", or wants to document a component's animation properties.

0n6k4v-Coder/skills

Turn on Cache Components in a Next.js app and resolve the blocking routes it surfaces. Use when the user wants to enable, adopt, or migrate to Cache Components, flip the `cacheComponents` flag, work through a flood of blocking-prerender / instant validation errors, run the `cache-components-instant-false` codemod, or decide between opting routes out with `export const instant = false` and fixing them in place.

0n6k4v-Coder/skills

Optimize a Next.js app that has `cacheComponents: true` — either the static shell on first paint, or the in-app navigation between routes. Picks the matching diagnostic loop and runs it.

相关技能