Communitygithub.com

Next.js 缓存组件优化器

优化启用了 `cacheComponents: true` 的 Next.js 应用——无论是首屏的静态外壳,还是路由间的页面内导航。自动选择匹配的诊断循环并运行。

Next.js 缓存组件优化器 是什么?

该技能(Skill)用于优化 Next.js 应用中 `cacheComponents: true` 配置下的性能,专注于提升首屏加载(静态外壳)和客户端导航体验。它提供两个诊断循环:页面渲染循环(`ppr-loop.md`)针对单页面初始加载,通过分析 Suspense fallback 区域来扩大静态外壳;导航循环(`instant-nav-loop.md`)则针对 A 到 B 的页面导航,在 B 的数据加载完成前立即显示 B 的静态布局(chrome、结构、内容形状的 fallback),从而消除用户等待时的空白状态。技能共享一套前置检查、即时导航 Cookie 机制、重构手段(如“下推”I/O 到 Suspense 子组件和缓存策略)以及回滚准则。它在 `next-dev-loop` 基础上工作,要求用户已手动登录,并强制通过 plan mode 进行重构,确保每个修改都有清晰的提案和可见的视觉差异。适用于 Cursor、Claude Code、Codex 等支持 SKILL.md 的 AI 编码代理。

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

在你喜欢的 AI 中提问

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

文档

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-browser CLI,并连接开发 MCP 服务器,该服务器提供 mcp get_logs。
  • 在 next.config.ts 中设置了 cacheComponents: true。否则拒绝执行。

预检(共享)

  1. 确认 cacheComponents: true。
  2. 用户必须已经位于每个循环所需页面上(通过 next-dev-loop 打开的有头浏览器)— 已登录,并设置好任何状态。此技能无法驱动认证、SSO 或 MFA;它将以手动设置作为起点。(每个子循环会说明期望的页面。)
  3. 使用 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 配合使用 — 请先启动它。

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

Verify Next.js runtime behavior after editing app code. Use this skill to confirm a change actually works in a running app — not just that it compiles or type-checks. Combines /_next/mcp (Next.js's view) with agent-browser (the browser's view). Requires a running `next dev`.

相关技能