next-cache-components-optimizer
两个循环,共享手段和原语,不同的诊断:
- 页面渲染循环 (ppr-loop.md) — 扩增单页面的静态外壳。在仅渲染外壳时,对 Suspense fallback 区域进行排序。
- 导航循环 (instant-nav-loop.md) — 当用户从 A 点击链接到 B 时,立即显示 B 的静态布局(chrome、结构、内容形状的 fallback),而不是保持 A 的 UI 直到 B 的数据解析完成。在
pushstate之后捕获 B 的挂起边界,按suspended_by[].name分类,移除仅适用于 SSR 的客户端 hooks。
选择一个并完整运行。
前提条件
- 本次会话中已启动
next-dev-loop— 它打开有头浏览器,暴露agent-browserCLI,并连接开发 MCP 服务器,该服务器提供mcp get_logs。 - 在
next.config.ts中设置了cacheComponents: true。否则拒绝执行。
预检(共享)
- 确认
cacheComponents: true。 - 用户必须已经位于每个循环所需页面上(通过
next-dev-loop打开的有头浏览器)— 已登录,并设置好任何状态。此技能无法驱动认证、SSO 或 MFA;它将以手动设置作为起点。(每个子循环会说明期望的页面。) - 使用
agent-browser get url锚定当前路由。
每个循环根据需要设置即时 Cookie(见下面的共享 即时 cookie 部分)。
即时 Cookie(共享)
两个循环都使用 next-instant-navigation-testing Cookie 来冻结框架的动态数据写入。设置后,页面上的可见内容就是静态外壳 + Suspense fallback — 我们通过捕获它来评估优化。
使用待定锁元组 [0, "<unique-id>"] 进行设置。id 可以是任意唯一字符串;惯例是使用 p 前缀的随机标记,以便并发作用域不冲突:
agent-browser cookies set next-instant-navigation-testing '[0,"p<random>"]' \
--url <origin>
每个循环的预检指定了在流程中的何时设置它。最后清除它(见下面的 teardown)。
决定使用哪个循环
- 页面渲染 — 当用户抱怨单一路由的初始加载时。阅读 ppr-loop.md。
- 导航 — 当用户抱怨两个路由间的导航时。阅读 instant-nav-loop.md。
不明确时 → 询问。
共享的重构手段
- 下推 — 将 I/O 提取到一个 Suspense 包裹的子组件中,这样父组件保持静态,并且静态的兄弟组件会被提升到外壳中。
- 递归,不要盲目包裹。 如果一个 Suspense 边界已经包裹了一个同时包含静态内容和 I/O 的组件,请阅读内部,将 I/O 相关的 JSX 提取到一个新的叶子组件中,并将静态兄弟组件提升出去。
- 缓存 — 使用
'use cache'+cacheLife(<profile>)。始终询问用户对新鲜度的要求;映射到预设(seconds/minutes/hours/days/weeks/max/default)。
下推和缓存可以组合:下推提升静态结构,缓存消除剩余的数据缺口。
通过 plan 模式提出方案(共享)
每次重构在应用前都要经过 plan 模式。请将此视为一个信号:应用工作是非平凡的智能体工程,而不是模板化的编辑。此技能提供了框架——使用哪种手段,修复哪个候选,期望的可见差异是什么——但实际工作(编辑哪个文件,如何干净地提取 I/O,将新的 Suspense 边界放在哪里,向用户询问哪个 cacheLife 配置文件)是需要你仔细思考的判断。Plan 模式强制在触及代码前提出一个连贯的提案,并让用户有机会对这些决策中的任何一个进行重定向。
无外壳时退出(共享)
这些手段假设存在一个可以扩增或缓存到的外壳。如果路由完全阻塞——mcp get_logs 中出现 HTTP 500 blocking-route 或 NEXT_STATIC_GEN_BAILOUT,或者在一个有可见渲染的页面上有零个 Suspense 边界——就没有外壳。揭示结构阻塞器并停止;用户必须在任一循环提供帮助之前,将导致问题的动态访问包裹在 <Suspense> 中。
验证需要可见差异(共享)
每个循环在应用任何更改之前捕获外壳的基线截图,然后在更改后重新截图。在最终摘要中报告两个路径,以便用户看到变化。两个捕获必须明显不同——fallback 区域缩小,内容提升到静态表面,目标 fallback 消失或变成内容形状。相同的截图意味着重构未生效;撤销。“编译通过”不是标准。
在每次截图前隐藏开发覆盖层。 Next.js 开发覆盖层(文档根部的 <nextjs-portal>)会渲染即时导航指导、构建错误和其他干扰前后对比的开发 chrome。隐藏它、截图、恢复:
agent-browser eval "document.querySelector('nextjs-portal').style.display='none'"
agent-browser screenshot <path>
agent-browser eval "document.querySelector('nextjs-portal').style.display=''"
反模式(共享)
不要用顶层加载骨架替换细粒度的 Suspense 边界。 整个片段的 loading.tsx,或根级别的 <Suspense fallback={<Skeleton />}>(更糟糕的是 fallback={null} 导致 UI 空白),会破坏此技能的优化目标——即在每个细粒度边界上方提取真实的静态 chrome,并为每个区域使用内容形状的 fallback。一个粗粒度的“页面正在加载”占位符完全绕过了这项工作。
陷阱(共享)
- 开发环境不会像生产环境那样预取,并且路由在第一次命中时编译——因此导航或重新加载后,DOM 更新持续的时间明显长于最终的生产体验。在捕获 React 树或截图之前,耐心等待 DOM 稳定——例如,轮询
document.documentElement.innerHTML.length直到两次连续读取未发生变化。固定的短延时可能会导致在渲染过程中采样。 - 不要尝试通过检查开发网络流量来验证导航预取——开发环境根本不触发预取请求,因此网络选项卡、手动
router.prefetch()调用和<Link prefetch={true}>看起来都会出问题,无论你的代码是否正确。instant-nav-loop.md 中verify下的 cookie 锁定 SPA 导航配方已经是这方面的规范方法——它模拟生产环境会预渲染到预取 RSC 中的内容,而无需预取实际触发。使用它;不要发明网络选项卡的替代方案。 - 诊断流水线可能不稳定——DevTools 附件时机、DOM 稳定竞态和开发编译效应都可能导致每次运行产生不一致的捕获。当结果感觉不对劲时(出现了一个你没想到的候选,或者你期望的候选没有出现),重复运行诊断 2-3 次并交叉检查;始终出现的边界是真实的,单次出现的是噪声。
参考(共享原语)
agent-browser react suspense 添加 --only-dynamic 以过滤
--json 服务端真正挂起的
边界。每个条目包含
jsx_source +
suspended_by[],带有原始
阻塞器名称(usePathname,
cookies, fetch, cache, ...);
按名称分类以用于每个循环的规则
POST /__nextjs_original-stack-frames 主体 { frames: StackFrame[],
isServer, isEdgeServer,
isAppDirectory }; 每帧返回一个
结果,包含 file:line:column
mcp get_logs 来自 next-dev-loop 的开发 MCP
工具;显示 blocking-route /
NEXT_STATIC_GEN_BAILOUT 500 错误
cacheLife('<profile>') default | seconds | minutes
| hours | days | weeks | max
每个循环特有的原语在 instant-nav-loop.md 中。
清理(共享)
通过名称删除 Cookie — 用过期标记覆盖:
agent-browser cookies set next-instant-navigation-testing x \
--url <origin> --expires 1
永远不要使用 agent-browser cookies clear(无参数)— 这会清除认证信息。
与 next-dev-loop 配合使用 — 请先启动它。