next-cache-components-adoption
在應用程式上啟用快取元件,並逐步使其能通過構建。此技能會安排工作順序;每個錯誤的修復方法位於開發者重疊層的修正卡和構建的終端機輸出中。遷移至快取元件指南是此技能所應用之概念和每個 API 修復方法的權威參考文件 — 每當技能步驟參考某個模式("use cache"、cacheLife、<Suspense> 放置等)且您想要完整解釋時,請查閱該指南。
需求
-
App Router 專案。 快取元件是 App Router 的功能;
cacheComponents: true對pages/路由無效。如果專案有pages/或src/pages/目錄結構但沒有app/或src/app/目錄結構,請停止並告知使用者 — Pages 到 App 的遷移是另一個獨立的工作,不屬於此技能的範圍。混合型應用程式(同時包含pages/和app/)是可以的:該旗標會影響app/路由;pages/路由不受影響,也不需要排除設定。 -
Next.js 16.3 或更新版本。 此版本包含了此技能所依賴的各項功能:頂層的
cacheComponents、export const instant、開發者重疊層的即時導航驗證警告,以及cache-components-instant-falsecodemod。如果next --version顯示的版本低於 16.3,請先進行升級: -
無不相容的配置鍵值。 任何匯出
dynamic、revalidate或fetchCache的檔案,當設定cacheComponents: true時都會產生錯誤。請進行轉換,不要直接刪除。 每個匯出都編碼了路由需要保持的行為;請透過遷移指南的按鍵值章節將每個匯出遷移為其對應的快取元件等效項。如果某個值尚無法乾淨地轉換,請留下一個// TODO: Cache Components adoption — restore revalidate = 3600的註解,以便在後續循環中處理。cache-components-instant-falsecodemod 不會處理這些。 -
experimental.dynamicIO是致命的錯誤。 它已被重新命名為頂層的cacheComponents,而舊的鍵值現在會在任何構建開始前就中止執行 — 請先將其移除(或替換為cacheComponents: true)。experimental.useCache仍然被接受為已棄用的別名;一旦設定了cacheComponents: true,它就變成多餘的,因此為了清晰起見,也請一併移除。
備註
-
在設定旗標前,不需要一個通過的基準構建。 如果應用程式已經使用了
"use cache",則在設定旗標之前的構建會因please enable the feature flag cacheComponents而失敗。啟用該旗標是您要做的第一件事(在增量式方法中,是在執行 codemod 之前;在直接式方法中,是在開始修復路由之前)— 而不是在取得通過的構建之後才做的事情。請在您的起始摘要中記下這一點,以免讓使用者感覺像是功能倒退。 -
離線文件。 指南連結的離線副本位於
node_modules/next/dist/docs/下,其目錄結構以數字編號排序(例如node_modules/next/dist/docs/01-app/02-guides/migrating-to-cache-components.md)。結尾的檔案名稱與 slug 匹配。如果您無法預測編號前綴,可以使用find node_modules/next/dist/docs -name '<slug>.md'來解析。/docs/messages/*的錯誤頁面不會被打包。如果完全找不到離線文件,請執行npx @next/codemod@latest agents-md以將版本匹配的索引寫入AGENTS.md/CLAUDE.md。
工作型態
這裡只有一個循環:從上到下遍歷路由樹,一次處理一個功能,並針對 next dev 加上瀏覽器來採用每個路由。構建是每個功能的最終檢查點,而不是主要的工作環境。
步驟 1 的選擇是要先讓驗證錯誤安靜下來,還是邊進行邊修復。無論哪種方式,循環都是一樣的:
- 使用無聲預處理步驟(增量式)。 執行 codemod 以將每個頁面和佈局從驗證中排除。一旦您也修復了 codemod 無法處理的部分(同步 I/O 呼叫、遺留的
revalidate/dynamic/fetchCache匯出),構建就會通過;您可以將其作為一個獨立的拉取請求推送,然後開始循環 — 一次移除一個排除設定並採用該路由。這種方式能將工作拆解成小的、易於審查的拉取請求。 - 不使用預處理步驟(直接式)。 啟用
cacheComponents,然後從構建標記出的第一個路由開始循環。循環本身相同,但所有的修復都放在同一個分支上,直到採用完成。
在兩種方式中,每個路由的成功標準是相同的:開發循環沒有任何錯誤報告,且 next build 通過。在每個功能完成後都與使用者確認。預計大部分時間會花在循環中,而非預處理步驟。
背景知識
cacheComponents: true 要求每個路由都必須是可預渲染的。在 <Suspense> 之外讀取請求階段資料的路由會被視為「阻塞」並導致構建失敗。export const instant = false 將一個路由標記為允許阻塞,這在開發和構建階段都會清除其錯誤;在佈局中使用時,它會涵蓋整個子樹。包裹在 "use cache" 函數中的讀取操作被視為快取邊界,而非阻塞讀取。
三類阻塞問題會以以下順序困擾開發者:
- 請求階段的資料讀取(
cookies()、headers()、await params、await searchParams)。當這四個操作在頁面或佈局的頂層被 await 時,都會造成阻塞。params和searchParams常常因為不被視為「請求資料」(像 cookies 和 headers 那樣)而被忽略。解決方法是將讀取操作推入一個被<Suspense>包裹的子元件中 — 對於params/searchParams,則將 promise 轉發到子元件中並在那裡 await;不要在頁面頂層使用await。 - 模組/渲染階段的同步 I/O(
new Date()、Date.now()、Math.random()、crypto.randomUUID())。即使設定了instant = false,這些操作也會導致構建失敗 — 排除設定並不會抑制它們。如果它們位於共享佈局中,則會阻塞其下的每個路由。codemod 無法修復它們;您必須逐一轉換每個呼叫(如果值是穩定的,則使用"use cache"進行快取;如果是每個請求都不同,則將其包裹在await connection()+<Suspense>中),構建才能通過。在執行任何其他操作之前,請先在整個儲存庫中搜尋這些呼叫。 - 讀取請求資料的
"use cache"檔案。 帶有頂層"use cache"指令的檔案無法匯出instant;將兩者結合使用會導致Only async functions are allowed to be exported in a "use cache" file.錯誤,這表示該指令對該路由來說是錯誤的。請在執行 codemod 之前將其移除。
工作環境
尋找阻塞路由
在工作時,優先使用 next dev 而非 next build。
next dev— 主要的工作環境。訪問一個路由;其阻塞錯誤會顯示在開發者重疊層中,並附有完整的堆疊追蹤和連結到每個錯誤文件的修正卡。一次處理一個路由 — 錯誤不會集中在一個地方。該路由本身仍然會回傳 HTTP 200 狀態碼,因此請讀取重疊層(或.next-dev.log),而不是看狀態碼。清除重疊層僅代表路由清潔了一半 — 另一半是瀏覽器驗證(請參閱步驟 2)以及該路由的構建成功。next build— 僅用於檢測。構建是next dev的權威檢查,而非其替代品。將它用作循環中每個功能的最後一道關卡(通過的構建是每個路由成功標準的一部分),並作為整個應用程式的最終驗證。在增量式方法中,構建也用於確認預處理步驟(codemod 已將每個路由排除,且沒有共享佈局仍包含同步 I/O 阻塞器)是否成功,之後才能推送該拉取請求。在處理路由時,不要使用構建來取代開發循環 — 一個乾淨的編譯錯誤並不能告訴您最終哪些內容進入了靜態殼層,哪些內容被串流化了。預設情況下,構建會在第一個阻塞路由處停止,因此它也不利於評估工作量。有兩個旗標在迭代時會很有幫助:--debug-build-paths只構建您指定的路由(相對於專案根目錄的檔案路徑,使用逗號分隔的 glob 模式,例如--debug-build-paths="app/admin/**/page.tsx"— 而非 URL 路徑;--debug-build-paths="app/(marketing)/about/page.tsx"— 而非/about;--debug-build-paths="app/admin"不會匹配任何內容,並會靜默地構建零個路由),而--debug-prerender則會停用提前退出功能,使構建在遇到第一個預渲染失敗後繼續執行,報告所有阻塞路由,並印出更完整的堆疊追蹤,其中標示了原始檔案和行號。
每個阻塞錯誤都有一個對應的文件頁面 — 請打開它。開發者重疊層和構建終端機都會為每個錯誤印出一個 https://nextjs.org/docs/messages/<slug> 連結。該頁面是解決方法的權威說明;內聯訊息僅是摘要。請為您遇到的每個不同錯誤取得該連結,即使您認為自己已經知道模式 — 這些解決方法會隨著時間演進,而且同一類別的錯誤根據路由讀取的資料不同,可能會有不同的正確修復方法。不要僅根據內聯訊息就自行發揮。(/docs/messages/* 頁面不會被打包到離線文件中;如果您沒有網路連線,請退而使用 node_modules/next/dist/docs/ 下的每個 API 指南,並在回報時說明此限制。)
在執行時期驗證每個修復
通過的構建或清除的重疊層並不能證明路由實際行為正常 — 快取元件是一個執行時期相關的功能(一個帶有串流資料的靜態殼層)。請在每次修復後進行驗證,而不是等到最後。
依偏好順序:
-
next-dev-loop— 強烈推薦。 透過agent-browser交叉比對/_next/mcp與實際瀏覽器,並在一次檢查中同時呈現編譯和執行時期問題。其診斷資訊(React 樹、suspend 邊界、主控台 + 網路)比手動檢查next dev更豐富。在開始循環之前安裝它。不要等到您遇到
next dev本身無法解釋的問題時才安裝。請執行:npx skills add https://github.com/vercel/next.js/tree/canary/skills/next-dev-loop此技能需要
agent-browser >= 0.27.0,並且會引導您完成安裝。需要 Turbopack。 如果
package.json中的dev腳本傳遞了--webpack參數,請向使用者提出此問題,並詢問是否有理由繼續使用 webpack。如果沒有,請切換到 Turbopack(Next.js 16.3+ 的預設選項)。如果他們想保留 webpack,請跳過此安裝,改用僅構建循環。您不需要取得安裝
next-dev-loop本身的權限。它是一個工具,就像安裝一個開發依賴項一樣。如果有使用者在線上,請簡單告知您正在安裝它用於驗證。在非互動式執行環境(CI、儀表板、沙盒)中,請在沒有詢問的情況下直接安裝 — 「無法提示使用者」並非跳過的理由。唯一合理的跳過理由是實際的技術障礙:沒有網路、沒有 npm、唯讀檔案系統、明確的禁止新增依賴項政策,或是僅限 webpack 的開發腳本。如果您跳過了,請在最終報告中說明具體的障礙原因。 -
一個您可以自主控制的瀏覽器。 Playwright、直接使用
agent-browser、任何瀏覽器自動化工具。僅在next-dev-loop確實被阻擋時使用。您會錯過框架端的檢查(/_next/mcp),因此僅靠 DOM 斷言無法捕捉所有回歸問題 — 對於您稱為「已驗證」的結果要更加謹慎。 -
僅構建。 如果您完全無法執行開發伺服器,那麼構建是您唯一的訊號。
○ (Static)且沒有<Suspense>的路由可以被構建完全驗證(沒有要測試的串流內容)。◐ (Partial Prerender)路由僅驗證了殼層部分 — 當您回報時請標記它們。 -
完全沒有工具。 請使用者執行開發伺服器(或構建)並報告他們看到的結果,或者提交您已達到的里程碑並交接。
步驟 1:選擇策略
詢問使用者。請將問題表述為關於拉取請求形狀的問題,而不是關於工作量的請求。與使用者溝通時,切勿使用內部標籤(增量式、直接式、里程碑 A)— 那些是您自己的輔助標記。請以拉取請求和功能的方式提問,例如:*"您希望我先打開一個拉取請求來啟用快取元件並將每個路由從驗證中排除,然後在後續的拉取請求中逐個功能地處理實際的路由採用嗎?還是希望所有事情都在同一個分支上完成?"*即使是在一個很小的應用程式上,增量路徑仍然有其價值(可審查的拉取請求大小、可復原、// TODO: Cache Components adoption 標記也可作為您下次處理的工作佇列)。請不要替他們做決定。
如果沒有使用者可以詢問,請預設使用增量式,並記錄此選擇。
- 增量式 — 無聲預處理步驟 + 循環。執行 codemod 以將每個頁面和佈局從驗證中排除,讓構建通過,然後停下來與使用者確認(請參閱預處理步驟結束),接著進入步驟 2 的循環,並將每個功能作為後續的拉取請求推送。
- 直接式 — 跳過預處理步驟。啟用
cacheComponents並直接進入步驟 2 的循環;構建中的阻塞路由就是您的工作佇列。
增量式
在呼叫 codemod 之前,請先修復它無法處理的兩類阻塞問題。
-
模組/渲染階段的同步 I/O。 在整個儲存庫中搜尋
new Date()、Date.now()、Math.random()和crypto.randomUUID()(不僅限於app/**/layout.{js,jsx,ts,tsx}— 該讀取操作可能位於被佈局匯入的任何元件中)。使用其blocking-prerender-*錯誤卡中的修復方法來轉換每個匹配項。 -
不相容的區段配置。 在
app/目錄中搜尋^export const (revalidate|dynamic|fetchCache),並根據上方需求中的備註進行轉換。codemod 不會處理它們;讓它們留在原位會導致在執行 codemod 後構建失敗。
codemod 拒絕在一個骯髒的工作目錄樹上執行。請先提交或暫存不相關的工作,或者傳遞 --force 參數以允許其編輯與您的 WIP 共存。常見的誤判情況:如果您最近升級了 Next.js,package.json 和鎖定檔案可能已經是骯髒的狀態 — 請先提交它們。
使用 @canary 頻道...
[其餘內容因翻譯而被截斷]