前端交付:版本、缓存、错误定位与回滚
用户上午打开商品页,下午发布新版本,旧页面首次点击报表时才加载旧 chunk。如果部署立即删除旧文件,上午那份页面就会在下午报404。上传新 HTML 成功,只覆盖了发布链路的一部分。
一次构建形成一份可追踪产物
将提交号、构建编号、依赖锁定结果和文件清单关联到同一个 release;构建产物经过验证后再分发,不在不同服务器上各自重新构建出不同内容。
内容 hash 标识构建输出的内容变化,不是业务版本号。同一源码在不同构建条件下也可能得到不同文件名;资源依赖、工具版本和配置都会影响输出。根目录 public 资源通常按原名复制,需要另外安排版本或缓存策略。
回滚要依赖完整旧产物,不只是旧源码。否则临时重新安装和构建可能选择不同依赖,且恢复时间难以控制。
HTML与资源承担不同缓存职责
以下为公开静态站点的策略示意,必须由真实响应头验证,不能只看本地配置文件。
http
# 内容指纹资源,例如 /assets/app.a1b2.js
Cache-Control: public, max-age=31536000, immutable
# 文档入口
Cache-Control: no-cacheno-cache 允许保存但要求复用前重新验证,不等于完全不存储;no-store 才要求不保存。带用户身份的响应还需 private/no-store 等适当策略和缓存键设计,不能照搬公共资源规则。
CDN、浏览器 HTTP 缓存和 Service Worker 缓存是不同层。清理 CDN 不会自动删除浏览器或 Service Worker 中的旧结果;排查必须确认命中的层和当前资源版本。public 中同名更新的图标也不能依赖旧文件名实现自动失效。
发布顺序要保护仍打开的页面
先上传新版本完整资源并验证,再切换文档或入口;旧资源保留足够的兼容窗口。具体期限根据最长页面存活、缓存策略和发布频率确定,不能只保证刷新后的新用户正常。
按版本目录或原子切换可以减少发布中的半套资源,但如果旧 URL 指向共享 assets,仍需保留它们。部署使用删除同步时,先比较文件集并解释线上独有项,避免误删尚未入库但线上已引用的文件。
灰度要让同一次会话拿到相互兼容的文档与资源,并关联 release 监控。多版本接口或数据库变化还需要向后兼容,前端回滚无法自动撤销服务端数据迁移。
Source Map必须匹配同一份文件
压缩栈的行列需要对应构建生成的 map,工具链多次转换也需要正确衔接映射。错误 release 的 map 会给出误导位置,上传成功不等于匹配正确。
map 可以受控上传到监控平台,公开与否按源码暴露风险决定。所谓 hidden sourcemap 通常只是不在产物中写发现注释;若文件仍放在公开目录,知道 URL 的人仍可能访问。敏感源码和密钥不能依赖“没人知道路径”保护。
监控帮助定位,也要控制数据
记录 release、路由模板、错误种类、资源地址类别和必要环境;对错误聚合、采样和过滤,关联接口请求ID时避免携带个人数据。完整 URL、请求正文和用户输入不宜默认采集。
资源404、运行时异常、接口错误和性能回退需要分别统计。接口500不一定抛出 JavaScript 异常,正常运行不代表没有失败;监控SDK加载失败时还要有其他可观察入口。
验收发布与回滚两条路径
用发布前已打开的页面和发布后新页面各跑一遍动态导入;刷新深链接,检查 base、缓存头及资源版本;触发受控错误,确认能关联正确 release 与源码位置。最后切回旧产物,验证入口和资源共同恢复,而不是只看上传命令退出码。
如果新页面正常、旧页面报错,优先查旧 chunk 保留;如果不同地区得到不同版本,查 CDN 与文档缓存;如果栈位置离谱,查 release-map 匹配。站点发布方式见 前端部署,性能验收见 性能工程。
