Next.js 开启 cacheComponents 后,根布局乱用 cookies 会整页掉进动态渲染。

开启 cacheComponents 后,很多「以前能用」的写法会直接炸。这篇把三个最常见、也最难从报错里看出原因的白屏坑按「现象—原因—改法」写清楚,方便你在升级时逐条对照。
别在根布局乱用动态 API
cookies / headers 会把整棵树拉进动态渲染边界。根布局一旦读 cookie,就等于宣布整站无法预渲染,构建时不再生成静态 HTML,首屏只能等运行时。
典型现象:本地开发看不出问题,上线后首屏白屏时间变长,或者在 RSC 里报「无法在静态上下文中使用动态 API」。
怎么做:把读 cookie / headers 的动作下沉到真正需要它的叶子组件,并在那一层用 Suspense 包起来,让上层保持可预渲染。登录态这类全局信息,用一个小的客户端组件去取,不要写在 layout.tsx 里。
怎么确认改对了:构建输出里该页面应显示为静态或部分预渲染,而不是全部 dynamic。若整站都被标成 dynamic,多半还是根布局上有动态 API。
别在可预渲染组件里 new Date()
页脚年份这类用常量或构建期注入。在服务端组件里直接 new Date() 写年份、时间戳或「几小时前」,构建时间与服务端渲染时间会不一致,客户端 hydrate 时对不上,React 会丢掉这棵子树并重渲染,表现出来就是局部闪烁或整块内容消失。
典型现象:控制台提示 hydration mismatch;页面上某个时间文案在加载后突然变了;偶发、难复现。
怎么做:固定文案(版权年份)写成常量或在构建期注入;确实要显示「当前时间」的,放到客户端组件里用 useEffect 赋值,首屏先渲染占位;相对时间(几天前)改成服务端算好后传下来的绝对时间字符串。
怎么确认改对了:同一页面连续刷新,服务端 HTML 与客户端渲染的文案应完全一致;控制台不再出现 hydration 警告。
别再 export const dynamic
用 connection() + Suspense,或把读库放进 async 子树。新版约定里,页面级 export const dynamic = "force-dynamic" 这类旧开关已不再是推荐做法,混用容易得到「已声明动态但实际被缓存」的矛盾结果。
典型现象:页面数据不更新,或者反过来每次请求都重新渲染、缓存完全失效,两种极端都可能出现。
怎么做:需要每次请求都取最新数据的部分,用 connection() 明确标注,并把这段逻辑放进被 Suspense 包裹的 async 子树;不需要实时的部分保持可缓存,让静态外壳先出来。
怎么确认改对了:观察构建产物里各段的标记;请求两次看数据是否按预期刷新;确认没有旧开关残留与新缓存机制打架。
我的判断:这类白屏坑的共同点是「本地看不出来、上线才炸」。升级前先把根布局的动态 API 清一遍,比事后逐个页面排查省力得多。
延伸阅读
- 办公 Agent 想落地,先啃会议和流程两座山
- 办公助手不只是聊天,它真能替你跑活
- 办公助手能自动化的场景,别再当翻译机
- 宝贝该复查了,宠物店怎么提醒不烦人
- 本地生活门店的 Agent 团队,一次真实复盘
- 本地生活上 Agent,最先补的三个场景不是客服
- 本地生活智能体团队,4 个行业实战案例
- 本体论:让 AI 理解业务而不是背答案
- 本体论加工作流,让 Agent 真懂业务
- 别急着做 AI 早报,先核对落地三环
相关阅读
标签
双号关注
扫码关注「广说新零售」公众号 + 视频号
本地生活 AI 落地、Agent 实操、真实门店怎么跑起来。扫码关注公众号与视频号「广说新零售」,持续看可收藏的做法;有场景也可私信聊合作。

公众号

视频号
继续读
同栏目相关文章,方便对照着看。
Prisma 迁移上线前这 5 项必须过
Prisma 迁移前五项必检:migrate、deploy、回滚、生成 client、冒烟,少一项都能挂站。
别急着做 AI 早报,先核对落地三环
AI 早报自动生成最容易做成概念稿。真正要核对的是谁在做、做错当天能不能看见、边界在哪。
AI 上线头一周,先盯紧这四件要事别放
AI 落地项目上线第一周别只看 demo。盯四件事:在不在跑、对不对、人的反应、出错怎么兜。
客户说 AI 不懂我,八成是这三种原因
AI 客服不懂客户,多半不是模型问题:不知道你是谁、没接准意图、不记得你们发生过什么。
AI 项目为什么大多死在第二个月就停
AI 落地项目第一个月有掌声,第二个月只剩没人愿意干的脏活:维护、接真业务、说服使用的人。
