页面已经捕获数据读取异常，并返回了降级内容，为什么构建仍然失败？在带缓存和预渲染的框架里，异常可能经过不止一层处理：应用完成了降级，框架内部的错误记录却还在影响最终判断。
Next.js 于 UTC 2026 年 10 月 31 日 08:01 发布 16.5.0-canary.35，其中收录了修复 #100956，处理已被页面捕获的 'use cache' 异常仍导致预渲染失败的问题。北京时间为当天 16:01，位于本次写作的过去 48 小时内。
这项变化仍属于 canary 预发布。本文依据上游说明、代码和回归测试分析，不宣称所有稳定版本已经修复，也没有在本博客项目中升级或实测 Next.js。
背景：页面能降级，框架也要正确识别结果
'use cache' 可以用于函数、组件等范围，声明其输出参与 Next.js 的缓存处理。配合 Cache Components，部分输出会在预渲染阶段生成，而不是每次收到请求才重新计算。
设想一个页面读取可缓存的商品推荐数据。读取失败时，页面捕获异常，返回“推荐暂不可用”，其余内容仍可展示。从应用逻辑看，这次渲染已经产生了一个有意设计的结果。
问题在于，缓存函数抛出的异常也会被框架记录。修复说明指出，这些异常写入了工作上下文里的错误摘要索引，方便后续找到原始错误并输出日志；预渲染流程又使用同一个索引判断渲染是否失败。于是，“发生过一个异常”被当成了“页面最终渲染失败”。
受这个问题影响，页面即使完成捕获，构建期预渲染或按需生成仍可能失败。这里讨论的是这个特定路径，不是说所有缓存错误、所有路由或所有构建失败都有相同原因。
核心改动：保留诊断信息，单独收集渲染错误
修复没有简单清空错误记录，也没有让预渲染忽略所有异常。它把两种用途拆开了：
| 记录 | 用途 | 应如何理解 |
|---|---|---|
| 共享的原始错误摘要索引 | 查找原始错误，支持日志处理 | 记录出现过的异常，不直接证明页面失败 |
| 当前渲染的错误集合 | 向预渲染流程报告渲染错误 | 为这次渲染的失败判定提供依据 |
代码中，新建的 renderErrorsByDigest 接收页面 RSC 渲染器报告的错误；返回给预渲染流程的 digestErrorsMap 改用这个集合。原有 reactServerErrorsByDigest 继续保留，用于原始错误查找和日志处理。
关键不是变量名，而是分类时机。缓存函数内部出现异常，并不必然意味着异常最终穿透页面。页面捕获它并返回降级内容后，不应仅因为诊断索引里还有记录，就把整个预渲染结果判为失败。
这也不是“日志不再重要”。缓存数据读取失败仍值得观测，只是诊断记录与生成结果不能共用一个粗略的“是否非空”条件。
回归测试验证了什么
合并修复附带的用例启用了 cacheComponents，让缓存函数主动抛出异常，再由页面捕获并输出降级文本。
测试分别访问两类参数：通过 generateStaticParams() 提供的 static，以及没有提前列出的 runtime。两者都检查响应状态为 200，并包含预期降级内容；在 next start 对应测试模式下，再发一次请求，检查 x-nextjs-cache 为 HIT。
这些断言把问题拆得很清楚：既要确认应用设计的降级内容确实返回，也要确认它没有因为内部错误分类而失去缓存资格。
不过，测试通过不能扩大成几个别的结论：
- 它不是所有宿主平台、所有自定义缓存处理器的兼容报告。
- 它没有承诺业务失败后都应该返回 200。
- 它没有证明上游数据恢复后，降级页面一定会立刻刷新。
- 测试中的缓存命中不等于无限期缓存异常对象，也不代表所有降级结果都会自动按同一方式缓存。
上游测试是本次分析的证据；本文没有运行这些测试，也没有做性能或线上可用性测量。
对业务的影响：修复误判后，还要处理降级内容的寿命
对依赖 Cache Components 的应用，这项修复让页面的异常处理更接近开发者写出的语义：允许降级的错误由页面消化，诊断记录仍然保留。
但“降级页面可以正常生成并缓存”也带来一个必须由业务决定的问题：数据源恢复以后，用户何时能看到正常内容？
如果推荐模块的占位内容可以缓存一段时间，短暂复用可能是可接受的；如果是库存、权限或结算信息，返回一个看起来正常的页面可能掩盖真实故障。状态码、降级文案、缓存时间和刷新方式，都应由具体业务定义，不能把框架测试里的 200 原样当成产品规范。
以下是本文基于该机制提出的工程建议，而非本次修复自动提供的功能：
首先，区分预期的数据不可用与程序错误。不要为了让构建通过，把所有异常都吞掉。必要时按错误类型决定降级、继续抛出或返回明确的失败结果。
其次，为降级结果设计恢复路径。检查实际使用的缓存生命周期、重新验证和标签失效机制，验证上游恢复后页面是否真的更新。只有首次降级成功，没有恢复测试，仍可能留下持续展示旧内容的问题。
最后，区分观测指标。可以分别统计数据读取异常、页面降级和最终请求失败。仅统计 HTTP 500，会漏掉大量返回 200 的降级；只统计日志中的异常数，又可能误以为所有请求都不可用。
实践启示：别只在开发模式里试一次
对怀疑遇到该问题的团队，更有价值的做法是先构造最小复现，再决定是否评估预发布版本。
建议保留两个对照页面：一个捕获缓存异常并降级，另一个让异常继续传播。分别测试构建期生成的参数，以及首次请求时才生成的参数，确认降级与未捕获异常仍能被区分。
随后在生产构建和启动模式下检查首次响应、重复请求与缓存行为，再加入“数据源恢复”的用例。开发模式下能显示占位文本，不足以证明构建、按需生成和后续缓存都正常。
本次能明确核实的是：16.5.0-canary.35 的发布说明列出了该修复，合并改动包含对应的代码与测试。是否已有适合自己项目的稳定发布、托管平台是否采用同样的缓存路径，需要部署前另行确认。不要为了规避一个待核实的问题，直接把生产依赖改成浮动的 canary。
结语
这次修复值得关注的地方，是框架终于把“为排查问题记录过异常”与“页面渲染失败”分开判断。应用已经做出的降级，不该被另一层诊断记录无条件推翻。
对开发者而言，验收也应覆盖完整过程：异常出现、页面降级、结果复用，以及上游恢复后的重新生成。缓存系统把一次渲染延伸到了后续请求，错误处理的测试范围也应随之延伸。
参考来源
- Next.js 16.5.0-canary.35 发布说明——2026 年 10 月 31 日发布，本次近期主题来源；明确为预发布版本。
- Next.js 修复 #100956：Fix prerendering of caught ‘use cache’ errors——错误索引用途、渲染错误收集及构建期/按需预渲染回归用例。
- Next.js 官方文档：use cache——缓存输出、Cache Components、缓存生命周期与部署环境背景；不是本次修复的发布日期依据。