前端构建缓存为什么总命中旧文件：哈希命名、HTML入口与发布顺序

前端发布后最容易让人误判的一幕是：构建命令明明生成了新文件，打开页面却还是旧按钮、旧接口地址，强制刷新后才恢复。先别急着把锅全甩给浏览器，真正要核对的是三件事：入口 HTML 当前引用了哪个文件、文件名是否随内容变化、发布时新旧文件的切换顺序是否安全。

先判断：旧的是入口 HTML，还是它指向的资源

打开开发者工具的 Network 面板，勾选 Disable cache 后重新加载一次，再点开文档请求。记录 HTML 中的 和 ，例如入口仍然写着 app.41c8.js，而构建目录已经出现 app.7b21.js，问题在入口或入口的缓存；如果入口已经引用新文件，却返回了旧内容，才继续检查资源响应和中间层。

最小配方：让资源名随内容变化

构建产物不要固定叫 app.js、vendor.js。使用内容哈希后，代码变化会产生新 URL，旧 URL 仍可服务正在打开旧页面的用户。以常见构建清单为例：

{
  "app.js": "assets/app.7b21.js",
  "app.css": "assets/app.2fa0.css"
}

这里的关键不是哈希位数，而是同一份构建结果中的 HTML、清单和资源必须来自同一个目录。发布脚本若重新计算了一次文件名，却拿另一轮构建生成的 HTML，就会出现“文件都在，页面却加载错版本”的假成功。

流水线顺序：资源先到，HTML 最后切换

一个可回滚的静态发布至少分成四步：上传新 JS/CSS 和字体；直接请求新资源确认状态码与内容类型；上传新的 HTML 到临时路径并检查引用；最后再替换线上入口。HTML 是切换开关，过早替换会让一小段时间内的用户拿到新入口和不存在的新资源。

build/                      # 同一轮构建目录
  index.html
  assets/app.7b21.js
  assets/app.2fa0.css

# 发布检查顺序
1. 上传 assets/app.7b21.js 与 assets/app.2fa0.css
2. 请求两个资源 URL，检查 200 和 Content-Type
3. 检查 index.html 的引用与文件名一致
4. 最后切换 index.html

旧资源不要随新 HTML 一起删除。旧页面可能还开在用户的标签页里，接口重试、懒加载和分片脚本都可能晚几分钟才发起请求。保留一个发布窗口，等确认旧入口访问量降下来再清理。

入口 HTML 应该缓存多久

对大多数单页前端，入口 HTML 更适合短缓存或重新验证；带哈希的 JS、CSS、字体则可以设置较长缓存，因为内容变化会产生新 URL。具体响应头要以站点实际配置为准，不能把“文件名有哈希”误解成“所有文件都能永久缓存”。

• 入口 HTML：优先保证能较快发现新版本，发布后可通过响应头验证。
• 哈希资源：可长缓存，但必须禁止发布脚本复用同一文件名。
• 运行时配置：如果由 HTML 注入，必须和本轮 HTML 一起核对，不能只看 JS 哈希。

失败时怎么回滚和留证

如果新页面出现白屏，先恢复上一版 HTML，让它重新指向旧哈希资源；确认旧资源仍可访问后，再处理新版本。不要只把 HTML 恢复而删除新旧资源，也不要直接覆盖同名文件，否则很难判断用户拿到的是哪一份内容。

常见问题：前端缓存发布怎么核对

为什么强制刷新能解决问题？

强制刷新通常绕过或重新验证了入口缓存，所以它能掩盖 HTML 入口过期的问题，但不能修复资源未上传、引用写错或服务端文件被覆盖。

资源文件一定要用很长的哈希吗？

不一定。只要同一构建中名称稳定且内容变化会变名即可；位数应结合碰撞风险、文件名可读性和现有工具链决定。

能不能每次都给 app.js 加版本查询参数？

可以作为临时方案，但它把缓存失效依赖到入口拼接和中间层处理上。长期维护通常更容易核对内容哈希文件名与清单。

发布前的四项核对

把下面四项放进流水线门禁，缓存问题会从“用户反馈后猜原因”变成发布时就能失败：

1. 构建清单中的每个 JS/CSS 路径都能在发布目录找到。
2. 新资源已经能直接请求，状态码、类型和文件摘要符合预期。
3. 入口 HTML 的引用只来自本轮构建，不混入上一轮清单。
4. 回滚版本的 HTML 与资源仍保留，且有明确的切换记录。