用途:在 Next.js 应用中打开 Cache Components(cacheComponents: true),并逐条解决它暴露出的阻塞路由,使构建通过。
前提条件:需 App Router 项目;纯 pages/ 项目不适用,混用 pages/ 与 app/ 时该标志只影响 app/ 路由。需能正常启动的应用、Next.js 16.3 或更高版本。experimental.dynamicIO 必须移除(否则构建前即中止);文件中仍导出 dynamic、revalidate、fetchCache 会报错,需先按迁移指南处理。
主要能力与流程:核心是一个循环——自顶向下遍历路由树,逐个功能采用,每个路由对照 next dev 与浏览器验证。分两种策略:增量式先运行 codemod 把所有路由排除出校验、让构建通过,再逐功能跟进;直接式则启用后直接按构建报出的阻塞路由修复。阻塞主要来自三类:在 Suspense 之外读取请求时数据(cookies()、headers()、await params、await searchParams)、模块或渲染时的同步 IO(new Date()、Date.now()、Math.random()、crypto.randomUUID()),以及顶层带 "use cache" 指令的文件读取请求数据。修复通常是把读取下推到 Suspense 包裹的子组件,params/searchParams 需把 promise 传入子组件后再 await。
使用方式:可运行 npx @next/codemod@latest cache-components-instant-false ./app 插入 export const instant = false,并建议安装 next-dev-loop 进行验证:npx skills add https://github.com/vercel/next.js/tree/canary/skills/next-dev-loop。开发时用 next dev 作为工作界面,next build 作为最终检查;可用 --debug-build-paths 只构建指定路由,用 --debug-prerender 让构建不在首个阻塞处提前退出。每个错误都应打开对应的 https://nextjs.org/docs/messages/<slug> 文档页查看规范修法。
限制:失败退出码、路由返回值等需以实际输出为准;离线时无法访问 /docs/messages/* 页面,只能回退到 node_modules/next/dist/docs/ 下的离线副本。资料未提供具体耗时、收费与效果数据。