Next.js Cache Components 逐页决策指南：判断哪些路由该保留 `instant = false`，以及如何安全处置阻塞读取

本篇指南聚焦 Next.js 16.3+ 引入 Cache Components（cacheComponents: true）后的核心采纳难题：在将应用逐条路由迁移到"即时导航（instant navigation）"时，如何判断某条路由究竟应当被修复（缓存、加 <Suspense>）、延迟处理还是永久保留为"允许阻塞"（Block）。文中内容以仓库内技能文档 per-page-decisions.md 为主体骨架，结合其配套工作流 SKILL.md、instant 路由段配置参考、blocking-route 错误页 以及认证、数据访问层文档展开。读完你将掌握一套可复用的"机器不该独自判断"的决策框架：何时向用户提问、如何处理安全门禁、何时应让路由体面地保留阻塞。

背景：为什么会有"逐页决策"这件事

Cache Components 开启后，Next.js 要求每条 app/ 路由都可预渲染（prerenderable）。一条在 <Suspense> 之外读取请求期数据（request-time data）的路由会被判定为"阻塞（blocking）"并导致构建失败——对应错误即 blocking-route（"Uncached data was accessed outside of <Suspense>"），该类错误的常见触发点是：在 Page 或 Layout 顶层 await params/searchParams、调用 cookies()/headers()/connection()、或读取未被 "use cache" 缓存的数据。

而 export const instant = false 正是标记"该段允许阻塞"的开关：它同时清除 dev 与构建阶段的校验；放在 layout 上则在构建期覆盖整个子树（客户端导航仍会逐个校验后代 segment）。在采纳流程中，cache-components-instant-false codemod 会给每个 {page,layout,default} 文件插入 export const instant = false 与 // TODO: Cache Components adoption 注释，然后逐条移除 opt-out、逐特性修复（详见 SKILL.md）。

问题在于：并非每个阻塞读取都该被"修掉"。当你移除某条路由的 instant = false 后，dev overlay 的修复卡片（fix card）通常会给出解决方向，但总有一些场景是修复卡片无法替你决定的——例如这个读取该缓存还是该流式？它是不是安全门禁？这条路由是不是本来就该阻塞？这些判断正是 per-page-decisions.md 要解决的"机器（Agent）不应单独拍板"的灰色地带。按 instant API 参考 所述，instant = false 的本意是告诉 Next.js"导航进本段时允许阻塞"，而错误页与修复方案（加缓存、包 <Suspense>、或保持请求期读取）之间的取舍，往往取决于这段内容在产品上"是干什么用的"——代码本身不会记录这一点。

遇到阻塞读取时：先读全文，再决定是"缓存、包 Suspense 还是保持请求期"

per-page-decisions.md 给出的第一条纪律是：不要只看 fix card 的内联片段就动手。修复卡片虽然能解除构建阻塞，但真正决定"这条路由的导航为什么能变 instant"的细节（例如 <Suspense> 边界究竟该放在哪里）都在修复卡片链接的完整文档页里。对应的错误页面（如 blocking-route）会对数据访问、Headers、Params/SearchParams、短生命周期缓存分别给出"Before / After"代码，哪种修复适用取决于你读取的是什么数据、希望页面如何表现。不要即兴发挥。

如果拿不准该套用哪种修复，正确做法通常是向用户提出产品 / UX 层面的问题，而不是从 API 层面猜：

• 这段内容应当加载时就立即出现，还是允许稍后流式（stream）进来？ 回答是"立即出现"→ 用 "use cache" 缓存（同时按 caching 指南 的思路选择 data-level 或 UI-level 边界并设置生命周期）；回答是"可以稍后"→ 用 <Suspense> 包住，提供 fallback。
• 所有人看到的内容是否一致（可缓存），还是按用户 / 按请求不同？ 人人一致 → 缓存；每用户 / 每请求不同 → 本质上属于请求期数据，不能盲目缓存。

把技术修复（缓存它、包进 <Suspense>、或保持请求期读取）绑定到这个产品答案上，让用户决策的是体验，而不是 API。这正是 blocking-route 错误页 划分的两条主线：能被 "use cache" 覆盖的数据走缓存；必须每次请求访问的数据则必须有一个父级 <Suspense> 边界来提供 fallback UI——边界放多高，由你想渲染的 fallback 形态决定。

安全门禁与其他"你无法从代码推断"的守卫：停下来问，不要静默重构

这是整个逐页决策中最重要的一条铁律：如果阻塞代码看上去是因为某个"你无法推断的原因"而存在的——页面顶部的 await verifyAccess()、一个认证重定向、一个 feature-flag 检查——把它挪进 <Suspense> 会改变这段代码原本保证的语义，先停下来问用户再重构。构建错误想要的是 <Suspense>，但把一个安全门禁包进 <Suspense> 会让门禁形同虚设：fallback 先渲染、门禁后执行，等于把受保护内容暴露在了 fallback 阶段。只有写出这段代码的人才知道门禁的正确结局。

针对"页面顶部有一个安全守卫"的合法出路，关联文档给出了四条候选，需与用户逐条对齐：

1. 保持路由阻塞：保留 instant = false 作为一条有文档说明的 Block（见下文"何时保留 Block"）；
2. 重构页面，让门禁以不同的方式运行（例如把校验下推到真正访问数据的叶子组件或 Data Access Layer）；
3. 把检查移到 Proxy。按仓库内 authentication.mdx 的定位，Proxy 适合做路由层的乐观检查（optimistic checks），但不该是唯一防线；数据侧的主体校验应在靠近数据源的 Data Access Layer 完成。把门禁迁到 Proxy 属于架构修复，不是 Cache Components 修复，应作为迁移完成后的后续事项，而不是卡住整个迁移的阻塞项；
4. 删除门禁——仅当它只是重复了应用其他地方已经依赖的保护（如平台级部署保护、Proxy 检查、已有 Data Access Layer 的鉴权）。

"重定位"不等于"该不该运行"：Gate 冗余时要说出来

一个容易迷惑 Agent 的陷阱是：重定位一个读取（await connection()、Proxy）只改变它"在哪里运行"，从不改变它"是否应当运行"。因此，从 fix card 的视角看，一个冗余或已损坏的门禁和一个放置正确的门禁长得一模一样——它们都不会触发构建报错，也都"需要被挪进 Suspense"。所以当门禁看起来奇怪、冗余或不合时宜时，Agent 的职责是直白地表达疑问（例如："这处检查在这里可能是不必要的——你确定它该属于这里吗？"），而不是安静地把这个读取搬到别处。提出问题（surfacing the doubt）是 Agent 的工作；拍板（deciding）是用户的权力。如果你不知道如何在不改变代码行为的前提下把某段代码改造成 Cache Components 兼容，直接提问，不要硬改。

布局（Layout）层被整体门禁的特殊情形

如果 layout 下的每条路由都是这样被门禁的，那么在该 layout 上留一个有文档说明的 Block 就是正确的终态（而不是在每条页面上各自处理）。这与 instant API 参考 中"最高的 instant 配置覆盖整棵子树"的解析规则一致：layout 上 instant = false 在构建期覆盖全部后代 segment。把门禁整体迁往 Proxy 属于另一项架构改造，不应让 Cache Components 迁移为此停摆。

想要掌握认证与数据校验的全局图景，可继续阅读仓库内的两份权威文档：authentication.mdx（认证检查归属：路由层进 Proxy、数据层进 Data Access Layer）与 data-security.mdx 的 Data Access Layer 章节（集中式鉴权检查，可与 "use cache" 组合使用：由专门的数据访问层控制数据如何被读取、什么进入渲染上下文）。

何时保留 Block 是合法结局：文档化的取舍，而非未文档化的遗留

并不是每条阻塞路由都必须"修到不阻塞"。以下两种情形下，保留 instant = false 是完全正当的采纳结果：

• 路由本质上就该按请求阻塞——它天然是 per-request 的、没有可用的静态壳（static shell），硬凑静态壳只会让首屏体验更糟；
• 重构规模过大，而用户现阶段不想接手。

但前提有两个：第一，先与用户确认；第二，把 codemod 留下的机械性 // TODO: Cache Components adoption 注释改写为带原因的说明，例如：

// instant = false: kept on purpose — fully request-time dashboard
export const instant = false

// instant = false: deferred, refactor too large for now
export const instant = false

SKILL.md 在特性验收清单中明确把"留下 Block"与"留下脏注释"区分对待：任何遗留的 instant = false 都必须已改写为原因注释；grep -rn "TODO: Cache Components adoption" 应只在注释仍表示"待办工作"的地方命中。换句话说，一条文档化、深思熟虑的 Block 在迁移完成后可以名正言顺地留下；一条未文档化的遗留 opt-out 则不可以。这与 skill 的注释纪律（除 TODO 与用户已有注释外不添加冗余注释、只在代码里看不出"为什么"时才补注释）互为表里——Block 的原因注释正是"代码看不出为什么"的例外场景。

保留 Block 的适用范围边界

注意"保留 Block"只适用于请求期读取这一阻塞类别。若阻塞源是模块 / 渲染期的同步 IO（new Date()、Date.now()、Math.random()、crypto.randomUUID()），即使设置 instant = false 也无法豁免——该类错误在 build 中依旧失败（opt-out 不会压制它们）。所以"文档化 Block"策略不能用来掩盖同步 IO 问题，它只适用于那些"允许在导航时等待请求数据"的读取。另外，instant 导出不能出现在 Client Component 中（会抛错），布局中若有客户端导航组件调用 usePathname()/useSearchParams()，应走对应错误页（如 blocking-prerender-client-hook）的 <Suspense> 配方，而不是 Block 方案。

决策前自查清单

结合 per-page-decisions.md 全文与配套技能，在移除某条路由的 instant = false 之前，按顺序完成以下自查：

1. 是否已读完 fix card 链接的完整文档页，而非只看内联摘要？
2. 这段内容的产品定位是什么——加载即呈现还是可流式？人人一致（可缓存）还是按用户 / 请求变化？答案决定修复方向是 "use cache"、<Suspense> 还是保持请求期读取；
3. 代码是否在守卫某个我无法推断的语义（安全门禁、auth redirect、feature flag）？若是，先询问，绝不把门禁包进 <Suspense> 使其失效；
4. 门禁是否冗余（重复了平台部署保护、Proxy 检查或 Data Access Layer 的鉴权）？若是，直白说出疑问并交由用户决定删除或保留；
5. 该路由是否本质上就该阻塞，或重构成本过大用户暂不接受？若是，与用户确认后把 TODO 注释改写为原因注释，保留一个文档化 Block；
6. layout 层是否每条路由都被门禁？若是，在 layout 上保留文档化 Block 为正确终态，Proxy 迁移作为后续架构工作。

这套清单的核心精神始终如一：代码告诉你"它阻塞了"，但只有用户能告诉你"它该不该阻塞"。让技术修复服从产品意图，让安全守卫留在原位，让深思熟虑的 Block 体面地文档化——这就是 Cache Components 逐页采纳的正确节奏。