Communitygithub.com

next-cache-components-adoption

在 Next.js 应用中启用缓存组件并解决其暴露的阻塞路由。当用户想要启用、采用或迁移到缓存组件、翻转 cacheComponents 标志、处理大量阻塞预渲染/即时验证错误、运行 cache-components-instant-false 代码模组,或在通过 export const instant = false 选择退出路由与原地修复之间做出决定时使用。

next-cache-components-adoption 是什么?

该技能旨在帮助开发者将一个 Next.js 应用完全迁移到缓存组件(Cache Components)体系。它提供一个结构化的、逐步的迁移流程,包括首先选择增量式(先静默所有错误再逐个修复)或直接式(直接启用并修复)策略。随后,技能会引导代理使用 next dev 和 next build 工具,循环遍历路由树,通过移除 `instant = false` 标记或修复底层代码(如请求时读取、同步 I/O 调用)来逐个采用功能。重要提示:它需要 App Router 和 Next.js 16.3 或更高版本。该技能还整合了 next-dev-loop 等外部工具进行运行时验证,并优先修复“阻塞预渲染”和“即时验证”错误。最终目的是实现一个通过编译且行为正常的应用,其中所有路由均被正确优化,而非仅仅是绕过验证。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/0n6k4v-Coder/skills/tree/HEAD/next.js/next-cache-components-adoption

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

next-cache-components-adoption 是做什么的?

在应用中启用缓存组件(Cache Components)并使其顺利通过构建。此技能编排整个工作流程;每个错误的具体修复方案位于开发者覆盖层(dev overlay)的修复卡片和构建的终端输出中。迁移到缓存组件指南是本技能所应用概念和每个 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-false 代码模组。如果 next --version 报告低于 16.3,请先升级:

    • 运行 npx @next/codemod@latest upgrade latest 来应用版本间的代码模组。
    • 阅读相关的版本升级指南(例如 Version 16)以了解代码模组未覆盖的内容。
  • 没有不兼容的配置键。 cacheComponents: true 会在任何仍导出 dynamic、revalidate 或 fetchCache 的文件上报错。请进行转换,而非删除。 每个导出都编码了路由需要保持的行为;通过迁移指南中每个键的相关章节将其迁移到对应的缓存组件等效功能。如果某个值暂时无法干净地转换,请留下 // TODO: Cache Components adoption — restore revalidate = 3600 这样的注释,以便下次循环能够处理。cache-components-instant-false 代码模组不会触及这些导出。

  • experimental.dynamicIO 是致命错误。 它已被重命名为顶层 cacheComponents,旧键现在会在任何构建运行前中止——请先移除它(或替换为 cacheComponents: true)。experimental.useCache 仍可作为弃用别名被接受;一旦设置了 cacheComponents: true 它就多余了,因此也请移除它以保持清晰。

注意事项

  • 在启用标志之前无需通过基线构建。 如果应用已经使用了 "use cache",启用标志前的构建会报错 please enable the feature flag cacheComponents。启用标志是你要做的第一件事(在增量策略中,在代码模组之前;在直接策略中,在修复路由之前)——而不是在获得一个通过的构建之后才做的事情。请在你的开始总结中注明这一点,以免被视为回归。

  • 离线文档。 指南链接的离线副本位于 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 加浏览器逐个采用每个路由。构建是每个功能的最终检查,而非工作界面。

第一步的选择是:是先静默所有验证错误,还是边走边修复。无论哪种方式,循环都是一样的:

  • 带有静默预处理步骤(增量策略)。 运行代码模组,使每个页面和布局退出验证。在修复完代码模组无法处理的问题(同步 I/O 调用、剩余的 revalidate/dynamic/fetchCache 导出)后,构建通过;你将其作为独立的 PR 提交,然后开始循环——一次移除一个退出标记并采用该路由。这可以将工作分解为小的、易于审查的 PR。
  • 无预处理步骤(直接策略)。 启用 cacheComponents 并开始循环处理构建首先标记的任何问题。相同的循环,但所有修复都位于同一分支上,直到采用完成。

在两种策略中,每个路由的成功标准是一样的:开发循环无任何错误,且 next build 通过。每完成一个功能后与用户核对。预计大部分时间会花在循环中,而不是预处理步骤。

背景

cacheComponents: true 要求每个路由都必须是可预渲染的。在 <Suspense> 之外读取请求时数据(request-time data)的路由是“阻塞的”,会导致构建失败。export const instant = false 将路由标记为允许阻塞,从而在开发环境和构建中清除该错误;在布局上使用会覆盖其下的整个子树。包裹在 "use cache" 函数中的读取被视为缓存边界,而非阻塞读取。

三类阻塞者会按此顺序影响代理:

  1. 请求时读取(cookies()、headers()、await params、await searchParams)。当在页面或布局的顶层 await 这四个函数时,它们都会被阻塞。params 和 searchParams 经常被忽略,因为它们不像 cookies 和 headers 那样被视作“请求数据”。修复方法是将读取推入一个被 <Suspense> 包裹的子组件中——对于 params/searchParams,将 promise 转发到子组件并在那里 await 它;不要在页面顶层 await。
  2. 模块/渲染时的同步 I/O(new Date()、Date.now()、Math.random()、crypto.randomUUID())。即使有 instant = false,这些也会导致构建失败——退出标记无法抑制它们。如果它们位于共享布局中,则会阻塞其下的每个路由。代码模组无法修复它们;你必须在构建通过之前转换每一个(如果稳定,用 "use cache" 缓存;如果每次请求都不同,则包裹在 await connection() + <Suspense> 中)。在运行任何其他操作之前,请在整个仓库中 grep 这些调用。
  3. 读取请求数据的 "use cache" 文件。 带有顶层 "use cache" 指令的文件不能导出 instant;两者结合会报错 Only async functions are allowed to be exported in a "use cache" file.,这意味着该指令对该路由来说是错误的。在运行代码模组之前将其移除。

工作界面

查找阻塞路由

在工作时优先使用 next dev 而非 next build。

  • next dev——工作界面。访问一个路由;其阻塞错误会出现在开发者覆盖层中,带有完整的堆栈跟踪和指向每个错误文档的修复卡片。一次只处理一个路由——错误不会集中在一处。该路由本身仍然返回 HTTP 200,所以请读取覆盖层(或 .next-dev.log),而非状态码。清除覆盖层只完成了路由清理的一半——另一半是浏览器验证(参见步骤 2)以及该路由的构建通过。
  • next build——仅用于检测。构建是 next dev 的权威检查,而非替代品。将其用作循环中每个功能的最终闸门(通过的构建是每个路由成功标准的一部分),并作为整个应用的最终验证。在增量策略中,构建还确认了预处理步骤(代码模组使每个路由都退出了,没有共享布局仍然包含同步 I/O 阻塞者),然后你才能提交该 PR。在处理路由时不要用构建代替开发循环——一个干净的编译错误不会告诉你最终在静态 shell 中包含了什么,又有什么被流式传输。默认情况下,构建在第一个阻塞路由处停止,因此也不适合评估工作量。有两个标志在迭代时很有帮助:--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 指南,并在报告时说明这一限制。)

在运行时验证每次修复

通过构建或清除覆盖层并不能证明路由实际行为正确——缓存组件是一个运行时关注点(带有流式数据的静态 shell)。请在每次修复后验证,而不仅仅在最后。

按偏好顺序:

  1. next-dev-loop——强烈推荐。 通过 agent-browser 交叉检查 /_next/mcp 和实时浏览器,一次通行即可发现编译和运行时问题。其诊断信息(React 树、Suspense 边界、控制台 + 网络)比手动操作 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 的开发脚本。如果你跳过,请在你的最终报告中说明具体的障碍。

  2. 你可以自行驱动的浏览器。 Playwright、直接的 agent-browser、任何浏览器自动化工具。仅当 next-dev-loop 确实被阻塞时才使用。你会错过框架侧的检查(/_next/mcp),因此单独的 DOM 断言无法捕获所有回归——对于你称之为“已验证”的内容要更加谨慎。

  3. 仅构建。 如果你完全无法运行开发服务器,则构建是你唯一的信号。没有 <Suspense> 的 ○ (Static) 路由可通过构建完全验证(没有需要测试的流式内容)。◐ (Partial Prerender) 路由仅经过了 shell 验证——报告时请注明这一点。

  4. 没有任何工具。 请用户运行开发服务器(或构建)并报告他们看到的内容,或者提交你已经达到的里程碑并交接。

第一步:选择策略

询问用户。将其表达为关于 PR 形式的问题,而不是关于工作量大小的问题。永远不要在与用户交流时使用内部标签(增量、直接、里程碑 A)——那些是你自己的脚手架。以 PR 和功能为单位提问,例如:“您希望我先打开一个 PR,启用缓存组件并使每个路由退出验证,然后在后续 PR 中逐个功能地处理实际的路由采用工作吗?还是把所有内容放在一个分支上?” 即使在一个很小的应用上,增量路径也仍然有价值(可审查的 PR 大小、可还原、// TODO: Cache Components adoption 标记可以兼作下次会话的工作队列)。不要替他们做选择。

如果没有用户可问,默认选择增量策略并记录此决定。

  • 增量——静默预处理步骤 + 循环。运行代码模组使每个页面和布局退出验证,让构建通过,停下来与用户核对(见预处理步骤结束),然后进入步骤 2 的循环,并将每个功能作为后续 PR 提交。
  • 直接——跳过预处理步骤。启用 cacheComponents 并直接进入步骤 2 的循环;构建的阻塞路由就是工作队列。

增量策略

在调用代码模组之前,修复它无法处理的两类阻塞者。

  1. 模块/渲染时的同步 I/O。 在整个仓库中 grep new Date()、Date.now()、Math.random() 和 crypto.randomUUID()(不仅仅是 app/**/layout.{js,jsx,ts,tsx}——读取可能位于布局导入的任何组件中)。使用其 blocking-prerender-* 错误卡片中的修复方案转换每个匹配项。

  2. 不兼容的段配置。 在 app/ 下 grep ^export const (revalidate|dynamic|fetchCache),并根据上面的“必要条件”注释进行转换。代码模组不会触及它们;保留它们会导致代码模组运行后构建失败。

代码模组拒绝在有未提交更改的工作树中运行。请先提交或暂存不相关的工作,或者传递 --force 让它的编辑与你的工作并存。常见的误报:如果你最近升级了 Next.js,package.json 和锁文件可能已经是脏的——请先提交它们。

使用 @canary 频道

…

[为了翻译而截断]

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

相关技能