用途:在 Next.js App Router 项目中启用 cacheComponents: true,并按路由逐项修复因此暴露的阻塞错误(blocking routes),最终让每个功能通过 next dev 与 next build 验证。它按顺序编排工作,具体报错修复配方来自开发覆盖层与构建终端输出。
前置条件:项目需为 App Router(纯 pages/ 项目不适用,混合项目仅影响 app/ 路由);需定位 next.config 所在根目录并解析 app/ 或 src/app/;应用须可运行;需 Next.js 16.3 或更高版本,低于则先升级,可用 npx @next/codemod@latest upgrade latest;不能保留 dynamic、revalidate、fetchCache 等配置(需翻译而非删除),experimental.dynamicIO 必须移除。
主要能力:区分两类策略——增量(先用 codemod 将全部路由 opt-out,构建通过后逐个移除 opt-out 并采用该路由)与直接(启用标志后直接按构建报出的阻塞路由逐项修复)。阻塞分三类:请求时读取(cookies、headers、await params、await searchParams)、模块/渲染期同步 IO(new Date、Date.now、Math.random、crypto.randomUUID)、顶层 "use cache" 文件读取请求数据。
使用方式:优先用 next dev 作为工作界面,逐路由查看开发覆盖层报错;next build 用于检测与最终验证,可配合 --debug-build-paths 与 --debug-prerender。每个阻塞错误都有对应文档页,应打开查看权威配方。推荐安装 next-dev-loop 做运行时验证:npx skills add https://github.com/vercel/next.js/tree/canary/skills/next-dev-loop,其需要 Turbopack。
限制:需要可运行的开发环境与浏览器验证;同步 IO 问题 codemod 无法修复,须手工处理;不能凭空验证未运行的应用;缓存组件是运行时关注点,仅构建通过不足以证明行为正确。