用途:在 Next.js App Router 应用中开启 Cache Components(cacheComponents: true),并逐条解决它暴露的阻塞路由,直到构建通过。
主要能力:提供一套按路由自上而下推进的工作循环,区分“增量式”(先用 codemod 让所有路由退出校验、构建通过后再逐个移除 opt-out)与“直接式”(开启后直接按构建报错修复)两种策略;覆盖三类阻塞:请求时读取(cookies()、headers()、await params、await searchParams)、模块/渲染期同步 IO(new Date()、Date.now()、Math.random()、crypto.randomUUID())、以及顶层 "use cache" 文件读取请求数据。
使用方式:要求 App Router 项目、Next.js 16.3+,且不存在 dynamic、revalidate、fetchCache 等不兼容导出;experimental.dynamicIO 必须移除。增量路径先运行 npx @next/codemod@canary cache-components-instant-false ./app 插入 export const instant = false,再设置 cacheComponents: true,用 next build 验证后逐个移除 opt-out。验证优先使用 next dev 与 next-dev-loop(npx skills add https://github.com/vercel/next.js/tree/canary/skills/next-dev-loop),需要 Turbopack。
适用场景:从 Pages 迁移完成后的 App Router 项目、希望分 PR 逐步采用 Cache Components 的团队。
限制:不适用于纯 pages/ 项目;同步 IO 无法被 codemod 修复,需手工处理;构建默认在首个阻塞路由停止,可用 --debug-build-paths 与 --debug-prerender 辅助;离线时 /docs/messages/* 不可用。