前端发布如何做灰度、回滚和版本追踪？
简化版
前端发布要把静态资源版本化、HTML 入口可切换、监控可观测、灰度可控、回滚可快速执行。核心原则是资源不可变、入口可回退、版本可追踪；不能只把 dist 上传 CDN 就算发布完成。
详细版
成熟发布流程包含：
- 构建产物带 hash，静态资源长期缓存。
- HTML 入口短缓存，方便切换版本。
- 发布记录包含 commit、构建号、环境、时间。
- 灰度按用户、地区、比例或业务开关控制。
- 监控错误率、白屏率、接口失败、性能指标。
- 回滚能恢复上一版 HTML 和资源引用。
注意点：
- 旧 HTML 可能引用旧资源，旧资源不能立刻删除。
- 发布后要观察关键指标。
- 回滚不等于数据回滚，接口协议要兼容。
- 灰度规则要稳定，避免用户来回跳版本。
完整版教学
一、前端发布的核心是入口和资源分离
现代前端构建会生成带 hash 的 JS/CSS，例如 app.a1b2.js。这些资源可以长期缓存，因为内容变了文件名也变。HTML 入口负责引用当前版本资源，应该短缓存或可快速刷新。回滚时通常切换 HTML 指向上一版资源。
index.html 短缓存，可切换
├─ app.a1b2.js 不可变长期缓存
└─ style.c3d4.css 不可变长期缓存如果 HTML 和静态资源都强缓存很久，发布后用户可能长时间拿不到新版；如果 hash 资源被覆盖，用户缓存和 CDN 会非常混乱。
二、版本追踪要贯穿构建和运行
每次发布都应该知道对应哪个 git commit、构建号、发布时间、环境和发布人。前端运行时也可以把版本号注入到全局变量或错误上报里。否则线上报错时，你不知道用户到底运行哪一版代码。
数字例子：一天发布 8 次，如果错误日志没有版本字段，只看到 “Cannot read property x”，排查会非常痛苦；有版本字段后，可以立刻定位是第 6 次发布引入的。
window.__APP_VERSION__ = {
commit: 'abc1234',
build: '20260729.8'
}三、灰度发布要有稳定分流
灰度不是随机让用户一会儿进新版本、一会儿进旧版本。应按用户 ID、设备 ID、租户、地区或固定比例做稳定分流。这样同一个用户体验一致，问题也更容易复现。
| 灰度方式 | 适合 | 风险 |
|---|---|---|
| 按比例 | 通用灰度 | 需稳定 hash |
| 按用户 | 内测用户 | 样本有限 |
| 按租户 | B 端客户 | 配置复杂 |
| 按地区 | 地域业务 | 统计偏差 |
灰度期间要观察错误率、白屏率、关键转化和性能指标，而不是只看“页面能打开”。
四、回滚要快，但也要考虑协议兼容
前端回滚通常比后端快：切回上一版 HTML 或路由配置即可。但如果这次发布同时依赖了后端新接口，前端回滚后旧代码是否还能调用后端？如果数据库结构或接口语义已经变了，单纯回滚前端可能没用。
因此前后端协作要遵守兼容发布：后端先兼容新旧字段，前端再发布，确认稳定后再清理旧逻辑。这个顺序能让前端回滚真正可用。
五、旧资源要保留一段时间
用户可能已经拿到旧 HTML，它引用旧 hash 资源。如果发布时把旧资源从 CDN 删除，用户刷新后 HTML 仍指向旧文件，就会 404 白屏。资源清理要有保留窗口，例如保留最近 7 到 30 天版本。
数字例子：如果日活 100000，哪怕只有 0.5% 用户命中旧 HTML，也有 500 人可能受影响。保留旧资源成本通常远低于白屏事故成本。
六、发布后验证要自动化
发布后应自动跑 smoke test：访问首页、登录页、核心路由，检查资源 200、主接口可用、控制台无明显错误。再结合监控看白屏、JS error、接口错误和性能。手动点两下不够稳定。
发布心法：资源不可变，入口可切换，版本可追踪，协议可兼容，回滚才真的有效。
七、常见误区与追问
- 误区：前端发布就是上传 dist。 还要处理缓存、版本、灰度、监控和回滚。
- 误区：回滚只要重新发旧包。 若接口协议不兼容或旧资源被删，回滚可能失败。
- 误区：hash 资源可以覆盖。 hash 文件应不可变，内容变就生成新文件名。
- 追问：HTML 为什么不能长缓存？ HTML 是版本入口，长缓存会让用户长期引用旧资源。
- 追问：灰度如何保证用户稳定？ 用用户 ID 或设备 ID 做 hash 分桶，避免随机抖动。
- 追问：发布后看哪些指标？ JS 错误、白屏率、接口失败、核心转化和性能指标。
八、加强记忆
前端发布用“三可一不可”记：入口可切换，灰度可控制，版本可追踪，静态资源不可变。再加一个关键条件：接口协议向前兼容。做到这些，发布、观察、回滚才是一套闭环，而不是一次上传动作。