Communitygithub.com

next-cache-components-optimizer(Next.js 快取組件優化器)

針對啟用 `cacheComponents: true` 的 Next.js 應用程式進行最佳化,涵蓋首屏靜態外殼或路由間導航,並自動選擇對應的診斷迴圈執行。

next-cache-components-optimizer(Next.js 快取組件優化器) 是什麼?

此技能提供兩個診斷迴圈(頁面渲染迴圈與導航迴圈),用於最佳化啟用 `cacheComponents: true` 的 Next.js 應用程式。它會根據使用者反映的問題類型(單一路由的初始載入問題,或路由間導航問題)自動選擇合適的迴圈並從頭到尾執行。技能共用多種重構手段,包括「下推」(將 I/O 提取到 Suspense 子元件中)與「快取」(使用 `'use cache'` + `cacheLife(<profile>)`),並且要求每次重構前先透過計劃模式提交提案。此外,它會自動捕捉基準螢幕截圖與變更後螢幕截圖以驗證可見的差異。支援的平台包括 Claude Code、Cursor、Codex 等 AI 編碼代理,依賴於 `next-dev-loop` 提供的開發環境。

相容平台~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),而不是在 B 的資料解析前保持 A 的 UI。在 pushstate 之後捕捉 B 的 suspended 邊界,按 suspended_by[].name 分類,移除僅 SSR 的用戶端掛鉤。

選擇一個並從頭到尾執行。

需求

  • 本次會話已啟動 next-dev-loop — 它會開啟有頭瀏覽器、暴露 agent-browser CLI,並連接提供 mcp get_logs 的開發 MCP 伺服器。
  • 在 next.config.ts 中設定 cacheComponents: true。否則拒絕執行。

預檢(共用)

  1. 確認 cacheComponents: true。
  2. 使用者必須已經在 headed 瀏覽器中(來自 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>

每個迴圈的預檢會指定在流程中的何時設定它。最後清除它(請參閱下方的「清理」)。

決定使用哪個迴圈

  • 頁面渲染:當問題是關於單一路由的初始載入時。請參閱 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)。

下推與快取可以組合使用:下推提升靜態結構,快取消除剩餘的資料差距。

透過計劃模式提出提案(共用)

每次重構在應用前都必須經過計劃模式。將此視為一個訊號:應用工作是非平凡的代理工程,而不是模板化編輯。此技能提供了框架 — 該使用哪個槓桿、該修復哪個候選項目、預期的可見差異是什麼 — 但實際工作(要編輯哪個檔案、如何乾淨地提取 I/O、將新的 Suspense 邊界放在哪裡、該詢問使用者哪個 cacheLife 設定檔)是您需要深思熟慮的判斷。計劃模式強制在接觸程式碼之前提出連貫的提案,並讓使用者有機會就任何這些決策進行重新導向。

無外殼時退出(共用)

這些槓桿假設存在一個可供擴增或快取的外殼。如果路由完全阻塞 — 在 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 會持續更新更長時間,比最終的生產體驗明顯更久。耐心等待 DOM 穩定後再捕捉 React 樹或截圖 — 例如,輪詢 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          add --only-dynamic to filter
--json                                server-side to actually-
                                      suspended boundaries. Each
                                      entry has jsx_source +
                                      suspended_by[] with raw blocker
                                      names (usePathname, cookies,
                                      fetch, cache, ...); classify by
                                      name for per-loop rules

POST /__nextjs_original-stack-frames  body { frames: StackFrame[],
                                      isServer, isEdgeServer,
                                      isAppDirectory }; returns one
                                      result per frame with
                                      file:line:column

mcp get_logs                          dev MCP tool from
                                      next-dev-loop; surfaces
                                      blocking-route /
                                      NEXT_STATIC_GEN_BAILOUT 500s

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`.

相關技能