如何驯服Next.js构建缓存一张地图加三套清理方案告别本地正常线上崩【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js早上改完最后一行样式本地跑next dev一切完美push、构建、上线半小时后用户截图过来页面还是旧样式数据也是昨天的。别急着怀疑代码——作为React框架的Next.js它那套构建缓存体系才是大多数这类事故的源头。读完这篇文章你会拿到一张缓存机制地图、三个真实翻车现场、三套从浅到深的清理方案以及一张上线前的自查清单之后绝大多数缓存不一致问题都能自己定位、自己修复。把缓存想象成三道收费站结论先行Next.js 的缓存不是一个东西而是一条流水线上的三道关卡。搞懂这张图之后排查就变成了一个判断题到底哪道关卡放行了旧数据源码 / 配置变更 │ ▼ 关卡一文件系统缓存.next/cache │ 判断有没有必要重新编译哈希没变 → 直接复用中间产物 ▼ 关卡二数据缓存fetch / use cache │ 判断要不要重新请求force-cache 直接吐缓存 ▼ 关卡三全路由缓存 客户端路由缓存 │ 判断返回哪一份 HTML静态路由默认永久缓存 ▼ 用户浏览器文件系统缓存囤在.next/cache里的编译结果和中间产物作用是能复用就别重算它决定了构建快不快。数据缓存fetch在生产构建默认force-cache同一个 URL 直接命中缓存它决定了数据新不新。全路由缓存与客户端路由缓存一个管服务端返回哪份 HTML一个管浏览器端跳转时是否吞掉预取的旧内容它决定了用户最终看到什么。这套机制的完整官方描述在 docs/01-app/02-guides/caching.mdx建议收藏当字典用。三个真实的翻车现场复盘先给结论下面三个坑几乎覆盖了日常 80% 的缓存事故而且每一个都能在十分钟内定位。现场一改了文件CDN 还在发旧版本发生你只调整了 CSS 里的注释和空白重新构建部署部分用户依旧看到旧样式。 原因构建产物文件名里的哈希由内容生成纯注释改动没有改变有效内容哈希原样保留CDN 认为资源没变直接命中旧缓存。 定位构建前后各导出一次.next/build-manifest.json做 diff看到哈希一模一样就实锤了。 修复让资源真正变——改动有效内容或升级版本号比如修改资源前缀配置。现场二revalidatePath 调了ISR 页面纹丝不动发生你在更新文章后执行revalidatePath(/blog/[slug])页面还是旧内容。 原因这个 API 只对静态渲染的路由生效且动态段要用参数化写法如果页面本身是动态渲染或路径写成了/blog/post-1这种具体值调用会被静默忽略。 定位确认页面没有写dynamic force-dynamic并检查revalidatePath的参数形式。 修复改用标签体系revalidateTag(posts)配合fetch(url, { next: { tags: [posts] } })匹配更省心。现场三开发环境数据实时变生产环境永远旧数据发生同一个接口本地每次刷新都有新数据线上却像焊死了一样。 原因fetch在开发模式下默认no-store在生产构建里默认force-cache你被两套默认值骗了。 定位全局搜一遍fetch(看哪些请求没写显式缓存策略。 修复全部显式声明见下一节的示例代码。分台阶的清理与预防方案新手先做第一条命令进阶靠代码声明工程化交给流水线。按团队水位选台阶不必全上。台阶一一条命令重建构建产物新手必会适用开发环境被脏缓存卡住、CI 构建出诡异产物。这一条命令能解决 90% 的本地正常线上崩# 只清中间产物缓存保留 .next 其余内容然后重建 rm -rf .next/cache npx next build # 产物整体错乱时直接把 .next 全删重来最彻底 rm -rf .next npx next build顺手写进 package.json随时用干净模式起服务{ scripts: { dev:fresh: rm -rf .next/cache next dev, build:fresh: rm -rf .next/cache next build } }成本约等于一次全量重编译的时间收益是确定性。台阶二在代码里显式声明缓存意图进阶推荐适用数据获取行为飘忽不定、想精确控制 ISR 刷新。原则只有一句别依赖默认值。// 实时数据始终请求最新 const res await fetch(/api/data, { cache: no-store }) // 可接受延迟每 60 秒重新验证一次 const res2 await fetch(/api/data, { next: { revalidate: 60 } }) // 事件驱动刷新打标签写操作后再失效 const res3 await fetch(/api/data, { next: { tags: [products] } }) // 在更新商品数据的接口里调用 revalidateTag(products)台阶三把缓存管理写进 CI/CD工程化适用多人协作、高频发版、有预发与生产多套环境。核心是给缓存配一把钥匙避免跨代码版本复用脏缓存# .github/workflows/build.yml片段 steps: - uses: actions/cachev3 with: path: .next/cache key: ${{ runner.os }}-nextjs-${{ hashFiles(**/pnpm-lock.yaml) }} - run: pnpm install - run: pnpm buildkey 里带lock 文件哈希依赖没变才复用缓存依赖一变缓存自动作废 ✅生产与预发用不同 key 前缀实现缓存隔离加一个postbuild钩子du -sh .next/cache缓存异常膨胀时能及时发现完整配置参考 docs/01-app/02-guides/ci-build-caching.mdx。三套方案怎么选一张表看懂方案适用场景成本收益手动清理偶发脏缓存、排障一次全量重建耗时立刻恢复正常代码显式声明数据行为漂移、ISR 失效逐个改 fetch 调用点各环境行为一致CI 缓存管理团队高频发版一次 workflow 改造长期省时、少出故障收尾自查三分钟检查你的项目把自己当缓存质检员过一遍每项都能回答是再上线☐ 所有fetch都显式写了cache或revalidate没有裸奔请求☐revalidatePath只用在了静态路由上动态段用了参数化写法☐ 构建后.next/build-manifest.json里的哈希随有效内容变化☐ CI 的缓存 key 绑定了 lock 文件各环境缓存相互隔离☐ 每次发版后跑一遍冒烟测试确认关键页面拿到的是新产物再进一步把数据获取升级为ISR 按需重新验证的组合甚至用next build前后产物做自动化回归。部署检查清单在 docs/01-app/02-guides/production-checklist.mdx想深挖缓存实现可以直接读 packages/next/ 下与next/cache相关的源码。缓存不是敌人而是一笔用旧换快的生意。理解它、给它划清边界你既能拿到性能也不再被本地正常线上崩偷袭。如果你也踩过更刁钻的缓存坑欢迎把故事讲出来——下一个翻车的人也许就靠你的复盘少加一小时班。【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 如何驯服Next.js构建缓存？一张地图加三套清理方案，告别本地正常线上崩
如何驯服Next.js构建缓存一张地图加三套清理方案告别本地正常线上崩【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js早上改完最后一行样式本地跑next dev一切完美push、构建、上线半小时后用户截图过来页面还是旧样式数据也是昨天的。别急着怀疑代码——作为React框架的Next.js它那套构建缓存体系才是大多数这类事故的源头。读完这篇文章你会拿到一张缓存机制地图、三个真实翻车现场、三套从浅到深的清理方案以及一张上线前的自查清单之后绝大多数缓存不一致问题都能自己定位、自己修复。把缓存想象成三道收费站结论先行Next.js 的缓存不是一个东西而是一条流水线上的三道关卡。搞懂这张图之后排查就变成了一个判断题到底哪道关卡放行了旧数据源码 / 配置变更 │ ▼ 关卡一文件系统缓存.next/cache │ 判断有没有必要重新编译哈希没变 → 直接复用中间产物 ▼ 关卡二数据缓存fetch / use cache │ 判断要不要重新请求force-cache 直接吐缓存 ▼ 关卡三全路由缓存 客户端路由缓存 │ 判断返回哪一份 HTML静态路由默认永久缓存 ▼ 用户浏览器文件系统缓存囤在.next/cache里的编译结果和中间产物作用是能复用就别重算它决定了构建快不快。数据缓存fetch在生产构建默认force-cache同一个 URL 直接命中缓存它决定了数据新不新。全路由缓存与客户端路由缓存一个管服务端返回哪份 HTML一个管浏览器端跳转时是否吞掉预取的旧内容它决定了用户最终看到什么。这套机制的完整官方描述在 docs/01-app/02-guides/caching.mdx建议收藏当字典用。三个真实的翻车现场复盘先给结论下面三个坑几乎覆盖了日常 80% 的缓存事故而且每一个都能在十分钟内定位。现场一改了文件CDN 还在发旧版本发生你只调整了 CSS 里的注释和空白重新构建部署部分用户依旧看到旧样式。 原因构建产物文件名里的哈希由内容生成纯注释改动没有改变有效内容哈希原样保留CDN 认为资源没变直接命中旧缓存。 定位构建前后各导出一次.next/build-manifest.json做 diff看到哈希一模一样就实锤了。 修复让资源真正变——改动有效内容或升级版本号比如修改资源前缀配置。现场二revalidatePath 调了ISR 页面纹丝不动发生你在更新文章后执行revalidatePath(/blog/[slug])页面还是旧内容。 原因这个 API 只对静态渲染的路由生效且动态段要用参数化写法如果页面本身是动态渲染或路径写成了/blog/post-1这种具体值调用会被静默忽略。 定位确认页面没有写dynamic force-dynamic并检查revalidatePath的参数形式。 修复改用标签体系revalidateTag(posts)配合fetch(url, { next: { tags: [posts] } })匹配更省心。现场三开发环境数据实时变生产环境永远旧数据发生同一个接口本地每次刷新都有新数据线上却像焊死了一样。 原因fetch在开发模式下默认no-store在生产构建里默认force-cache你被两套默认值骗了。 定位全局搜一遍fetch(看哪些请求没写显式缓存策略。 修复全部显式声明见下一节的示例代码。分台阶的清理与预防方案新手先做第一条命令进阶靠代码声明工程化交给流水线。按团队水位选台阶不必全上。台阶一一条命令重建构建产物新手必会适用开发环境被脏缓存卡住、CI 构建出诡异产物。这一条命令能解决 90% 的本地正常线上崩# 只清中间产物缓存保留 .next 其余内容然后重建 rm -rf .next/cache npx next build # 产物整体错乱时直接把 .next 全删重来最彻底 rm -rf .next npx next build顺手写进 package.json随时用干净模式起服务{ scripts: { dev:fresh: rm -rf .next/cache next dev, build:fresh: rm -rf .next/cache next build } }成本约等于一次全量重编译的时间收益是确定性。台阶二在代码里显式声明缓存意图进阶推荐适用数据获取行为飘忽不定、想精确控制 ISR 刷新。原则只有一句别依赖默认值。// 实时数据始终请求最新 const res await fetch(/api/data, { cache: no-store }) // 可接受延迟每 60 秒重新验证一次 const res2 await fetch(/api/data, { next: { revalidate: 60 } }) // 事件驱动刷新打标签写操作后再失效 const res3 await fetch(/api/data, { next: { tags: [products] } }) // 在更新商品数据的接口里调用 revalidateTag(products)台阶三把缓存管理写进 CI/CD工程化适用多人协作、高频发版、有预发与生产多套环境。核心是给缓存配一把钥匙避免跨代码版本复用脏缓存# .github/workflows/build.yml片段 steps: - uses: actions/cachev3 with: path: .next/cache key: ${{ runner.os }}-nextjs-${{ hashFiles(**/pnpm-lock.yaml) }} - run: pnpm install - run: pnpm buildkey 里带lock 文件哈希依赖没变才复用缓存依赖一变缓存自动作废 ✅生产与预发用不同 key 前缀实现缓存隔离加一个postbuild钩子du -sh .next/cache缓存异常膨胀时能及时发现完整配置参考 docs/01-app/02-guides/ci-build-caching.mdx。三套方案怎么选一张表看懂方案适用场景成本收益手动清理偶发脏缓存、排障一次全量重建耗时立刻恢复正常代码显式声明数据行为漂移、ISR 失效逐个改 fetch 调用点各环境行为一致CI 缓存管理团队高频发版一次 workflow 改造长期省时、少出故障收尾自查三分钟检查你的项目把自己当缓存质检员过一遍每项都能回答是再上线☐ 所有fetch都显式写了cache或revalidate没有裸奔请求☐revalidatePath只用在了静态路由上动态段用了参数化写法☐ 构建后.next/build-manifest.json里的哈希随有效内容变化☐ CI 的缓存 key 绑定了 lock 文件各环境缓存相互隔离☐ 每次发版后跑一遍冒烟测试确认关键页面拿到的是新产物再进一步把数据获取升级为ISR 按需重新验证的组合甚至用next build前后产物做自动化回归。部署检查清单在 docs/01-app/02-guides/production-checklist.mdx想深挖缓存实现可以直接读 packages/next/ 下与next/cache相关的源码。缓存不是敌人而是一笔用旧换快的生意。理解它、给它划清边界你既能拿到性能也不再被本地正常线上崩偷袭。如果你也踩过更刁钻的缓存坑欢迎把故事讲出来——下一个翻车的人也许就靠你的复盘少加一小时班。【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考