一次因浏览器缓存导致的生产环境事故：前端线上 bug 复盘

一次因浏览器缓存导致的生产环境事故：前端线上 bug 复盘

文章概览

• 一次因浏览器与 CDN 缓存策略不当引发的前端生产事故
• 从现象、排查、根因到应急与长期治理的完整复盘
• 给出可直接落地的缓存配置与发布流程改进建议

事故背景

• 单页应用，静态资源经构建后带 contenthash，通过 CDN 分发
• 网关使用 Nginx，index.html 与静态资源均设置了缓存，但未做差异化
• 发布采用覆盖式上传与 CDN 局部刷新，未验证边缘节点与浏览器层面的缓存一致性

事故现象

• 部分用户访问空白页或页面样式错乱
• 控制台报错资源 404 或运行时异常，如 Uncaught SyntaxError、某个 chunk 未定义
• 复现具有地域性：同一时间不同地区表现不同，且隐身模式明显好转
• 切换网络或强制刷新后恢复，暗示缓存相关问题

排查过程

• 使用开发者工具 Network 观察 index.html 与脚本的 Cache-Control、ETag、Last-Modified
• 对比隐身模式、禁用缓存、正常模式三种行为，确认缓存参与
• 检查 Service Worker 是否接管并返回旧版本 index.html
• 在不同网络与地区抓取响应头，确认 CDN 边缘节点是否仍在回源旧内容
• 对比构建产物清单，发现新老版本资源命名不一致且旧版本已删除

根因分析

• index.html 被设置了较长 TTL（例如 Cache-Control: public, max-age=600），导致页面入口在浏览器与 CDN 均被缓存
• 发布后 index.html 引用新的带指纹的静态资源，而部分用户仍持有旧 index.html，请求旧的 chunk 路径出现 404
• CDN 层刷新不彻底或有延迟，边缘节点与源站内容不一致，扩大了影响范围
• 开启 gzip 后 ETag 与 If-None-Match 不匹配，弱校验未生效
• 叠加 Service Worker 未及时激活新版本，个别用户被旧 SW 继续劫持

影响范围

• 受影响用户集中在缓存未过期且未强刷的群体
• 地域性差异来自于不同 CDN 边缘节点的刷新进度与路由
• 影响周期覆盖发布后若干分钟到数小时（取决于 TTL 与刷新速度）

应急处理

• 全量 Purge index.html 与关键入口路径，并对旧版本引用的资源做临时回滚或补齐
• 提供临时兼容资源别名，避免 404（仅限紧急兜底）
• 指导用户强制刷新或关闭 Service Worker（在支持的场景下）
• 开启监控：资源 404 比例、白屏率、JS 错误率实时告警

验证方法

• 使用隐身模式与禁用缓存分别访问，确认是否消除问题
• 对比 curl -I 返回头部，验证是否已改为不缓存入口和长期缓存静态
• 检查 Service Worker 更新与激活状态，确保不再劫持旧 index.html

配置示例

Nginx 对入口文档不缓存，确保每次导航拿到最新的引用

location = /index.html {
  add_header Cache-Control "no-cache, no-store, must-revalidate";
  add_header Pragma "no-cache";
  add_header Expires "0";
}

Nginx 对指纹静态资源长期缓存且不可变

location /static/ {
  expires 1y;
  add_header Cache-Control "public, max-age=31536000, immutable";
}

Webpack 构建开启内容指纹

output.filename = "js/[name].[contenthash:8].js"
output.chunkFilename = "js/[name].[contenthash:8].chunk.js"

CDN 刷新策略

• 按路径与前缀精确刷新，避免仅刷目录导致入口未更新
• 在发布管道中加入自动刷新与校验步骤

发布流程优化

• 入口与静态资源分级缓存：index.html 不缓存或极短 TTL；静态资源长期缓存加 immutable
• 原子发布：先上传静态资源，后发布入口，避免入口引用不可用资源
• CDN 全链路校验：在多个边缘节点做灰度拉取，确认响应头与内容一致
• 自动化刷新与校验：发布管道内置 CDN Purge 与 curl -I 验证步骤
• 监控与回滚：以资源 404 比例、白屏率、JS 错误率设定阈值与自动回滚开关
• Service Worker 更新策略：版本提示与点击激活，避免静默长期旧版本

自测清单

• 打开正常模式、隐身模式、禁用缓存模式分别访问主页
• 观察 index.html 是否返回 no-cache, no-store, must-revalidate
• 观察静态资源是否返回 public, max-age=31536000, immutable
• 切换网络与地区节点抽样验证 CDN 一致性
• 模拟旧版本 index.html 引用路径，确认不会出现 404 或版本错配
• 检查 Service Worker 是否拿到新 index.html 并正确激活

教训总结

• 入口文档与静态资源必须采用差异化缓存策略
• 指纹与长期缓存是前提，入口不缓存是关键
• CDN 刷新与验证需要成为发布必经步骤
• Service Worker 的版本管理必须可控且可感知
• 建立前端侧可观测性指标，尽早发现资源错配与白屏

结语

• 浏览器与 CDN 缓存是性能优化的利器，也是事故的高发点
• 遵循“入口不缓存、资源长期缓存”的原则，并配套原子发布与监控，能显著降低版本错配风险
• 将本次复盘中的配置与流程纳入团队基线，减少类似事故再次发生