S14-A01 · 前端部署与缓存策略

适用读者：发布后"用户看到旧页面"或"缓存永远不清"的人。
前置：S14-J03。
覆盖旧文：—（E 驱动；旧文未覆盖部署策略）
覆盖扩展：E-S14-005（hash 文件名与长缓存）。
上一篇：S14-J04 · SPA 首屏为什么慢：三阶段拆解
下一篇：S14-A02 · 可视化与内容渲染。

1. 一句话结论

index.html 必须"不缓存或短缓存"，带 hash 的静态资源必须"长缓存且 immutable"。搞反任何一个，都会出现"发版不生效"或"每次访问都重新下载"。

文件	hash	缓存策略	原因
`index.html`	无	`no-cache`（每次都校验）	它引用带 hash 的资源
`assets/*.js/css`	有	`max-age=31536000, immutable`	内容变则名变
图片/字体	有（或内容指纹）	长缓存	同上

实测依据（J02）：构建产物就是 index-HVKwxhDy.js ——hash 随内容变化，这是"长缓存"成立的前提。

2. 为什么 `index.html` 不能长缓存（E-S14-005）

用户请求 / → 命中缓存（30 天）→ 页面引用 old-hash.js → 用户看到旧版本
                              ↓ 即使服务端已发布新版本

策略	结果
`index.html` 长缓存	发版不生效（最经典的坑）
`index.html: no-cache`	每次校验（304 很便宜），能拿到新引用
assets 长缓存	内容变 → 文件名变 → 自动失效

判据："这个文件的名字会随内容变吗？" 会 → 长缓存；不会 → 短缓存/协商缓存。

3. nginx 的标准配置

# 入口：协商缓存
location = /index.html {
    add_header Cache-Control "no-cache, must-revalidate";
}
# 静态资源：长缓存
location /assets/ {
    add_header Cache-Control "public, max-age=31536000, immutable";
}

immutable 的作用：告诉浏览器"不用再发校验请求"（省一个 RTT）。

4. 发布与回滚

步骤	要点
构建	产物带 hash（J02）
上传	先传 assets，最后替换 index.html（避免引用到未上传的文件）
回滚	保留上一版 `index.html` + assets（hash 不同不冲突）
验证	打开无痕窗口看是否是新版本

"为什么最后替换 index.html"：它是"指针"——先换指针会指向不存在的资源 → 白屏。

5. 五个误区

误区	真相
"全部长缓存最省事"	`index.html` 会锁死版本
"全部不缓存最安全"	每次重新下载，性能极差
"回滚只需还原 index"	旧 assets 也被覆盖了就完了
"CDN 会自动处理缓存"	需要配回源与刷新策略
"hash 文件名只是好看"	是长缓存的前提

6. 自检（架构师版）

index.html 与 assets 的缓存策略为什么不同？
发版"不生效"的根因？
immutable 的作用？
发布顺序为什么是"先 assets 后 index"？
回滚要注意什么？

7. 下一篇

S14-A02 · 可视化与内容渲染

部署讲完，最后一篇：动画、代码高亮、Markdown/HTML 渲染的技术选型。

本篇属于系列《S14 · 前端与可视化》。扩展点 E-S14-005。hash 文件名依据 J02 实测产物。