前端静态资源指纹化：Hash 策略与缓存更新的协同设计

缓存是为了快，指纹是为了新——两者冲突时，策略决定胜负。

一、场景痛点

你上线了一个前端项目，Nginx 配了 Cache-Control: max-age=31536000，用户浏览器缓存了一年的 JS/CSS。然后你改了代码重新部署，用户反馈"页面没更新"。你查了半天发现：浏览器直接用了缓存的旧文件，根本没请求服务器。

你加了版本号 app.js?v=1.2.3，问题解决了。但 CDN 边缘节点缓存了 ?v=1.2.3 的旧版本，新版本 ?v=1.2.4 的请求穿透到源站，CDN 命中率暴跌。更糟的是，有些代理服务器会忽略 query string 的缓存键，导致新旧版本混用，JS 和 CSS 版本不一致，样式直接崩掉。

核心矛盾：缓存策略追求长期稳定，版本更新要求即时生效，两者必须协同设计，不能各自为政。

二、底层机制与原理剖析

2.1 文件指纹的三种策略

2.2 Hash 算法的选择

ContentHash（推荐）：基于文件内容计算，内容不变 Hash 不变。Webpack/Vite 的 [contenthash] 就是这个。同一份代码在不同机器上构建，只要内容相同，输出文件名一致，CDN 缓存直接命中。
ChunkHash：基于 chunk 的所有模块计算。如果 chunk 内某个依赖变了，整个 chunk 的 Hash 都变，即使入口文件本身没改。
Hash（全局）：基于整个构建输出计算。改任何一个文件，所有输出文件的 Hash 都变，缓存全部失效。这是最差策略，只在开发模式用。

2.3 缓存更新的协同机制

指纹化解决了"文件变了名字也变"的问题，但 HTML 文件本身怎么更新？浏览器缓存了旧 HTML，旧 HTML 引用旧 JS，新 JS 永远不会被请求。

解决方案：HTML 不做长期缓存，只做短期缓存或不缓存。HTML 是入口文件，它的职责是告诉浏览器"当前版本的 JS/CSS 文件名是什么"。HTML 必须每次都能拿到最新版。

三、生产级代码实现

3.1 Vite 构建配置

// vite.config.ts —— 生产级指纹化配置
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
export default defineConfig({
  plugins: [react()],
  build: {
    // 文件名模板：入口用固定名（HTML 引用需要），非入口用 contenthash
    rollupOptions: {
      output: {
        // 入口 chunk 固定命名，便于预加载
        entryFileNames: 'assets/[name]-[contenthash:8].js',
        // 非入口 chunk（动态 import）独立 hash，未改动不失效
        chunkFileNames: 'assets/[name]-[contenthash:8].js',
        // CSS 单独提取，独立 hash
        assetFileNames: (assetInfo) => {
          // CSS 文件用 contenthash，其他资源（图片/字体）也用 contenthash
          const extType = assetInfo.name?.split('.').pop() ?? 'unknown';
          if (/css/.test(extType)) {
            return 'assets/css/[name]-[contenthash:8][extname]';
          }
          if (/png|jpe?g|svg|gif|webp/.test(extType)) {
            return 'assets/img/[name]-[contenthash:8][extname]';
          }
          if (/woff2?|ttf|eot/.test(extType)) {
            return 'assets/font/[name]-[contenthash:8][extname]';
          }
          return 'assets/misc/[name]-[contenthash:8][extname]';
        },
        // 手动 chunk 分割：将稳定依赖分离，减少入口 chunk 变动频率
        manualChunks: (id) => {
          if (id.includes('node_modules')) {
            // React 核心库单独打包：极少变动，缓存收益大
            if (id.includes('react') || id.includes('react-dom')) {
              return 'react-core';
            }
            // 工具库单独打包：lodash/moment 等
            if (id.includes('lodash') || id.includes('moment')) {
              return 'vendor-utils';
            }
            // 其他第三方依赖统一打包
            return 'vendor';
          }
        },
      },
    },
    // contenthash 长度：8 位足够（2^32 组合，冲突概率极低）
    // 不用全 20 位，因为文件名太长影响 CDN URL 缓存键的存储效率
  },
});

3.2 Nginx 缓存配置

# nginx.conf —— HTML 与静态资源分层缓存策略
# HTML 入口文件：短缓存 + stale-while-revalidate，保证用户能快速拿到最新版
# 同时用 stale-while-revalidate 兜底：即使回源慢，用户也能看到旧版本（不至于白屏）
location / {
    root /usr/share/nginx/html;
    try_files $uri $uri/ /index.html;
    # HTML 不做长缓存：每次请求都验证是否有更新
    add_header Cache-Control "public, max-age=60, stale-while-revalidate=300";
    # ETag 辅助：如果 HTML 真没变，304 节省传输
    etag on;
}
# 指纹化静态资源：长期缓存，因为文件名变了 = 新文件
# 只要文件名包含 hash，内容永远不变，可以放心缓存一年
location /assets/ {
    root /usr/share/nginx/html;
    # 一年缓存 + immutable 标记：告诉浏览器这个文件绝对不会变
    # immutable 的作用：浏览器连 revalidate 请求都不发，直接用本地缓存
    add_header Cache-Control "public, max-age=31536000, immutable";
    # 关闭 ETag：文件名已经包含 contenthash，不需要额外验证机制
    etag off;
    # 开启 gzip：指纹化文件名让 CDN 可以放心缓存压缩版本
    gzip on;
    gzip_types text/css application/javascript application/json image/svg+xml;
    gzip_min_length 1024;
}
# Service Worker 更新策略：HTML 变化触发 SW 更新
# SW 的缓存策略由 JS 代码控制，Nginx 只管传输
location /sw.js {
    root /usr/share/nginx/html;
    # SW 文件不能缓存：每次都要拿最新版来触发 update 事件
    add_header Cache-Control "no-cache, no-store, must-revalidate";
}

3.3 CDN 缓存刷新自动化

# cdn_cache_purge.py —— 部署后自动刷新 CDN 中 HTML 的缓存
import hashlib
import json
import logging
import os
import time
import requests
logger = logging.getLogger('cdn-purge')
class CDNCacheManager:
    """CDN 缓存管理：部署后自动刷新入口文件，静态资源靠指纹自然过期"""
    def __init__(self, cdn_api_url: str, api_token: str, site_domain: str):
        self.cdn_api_url = cdn_api_url
        self.api_token = api_token
        self.site_domain = site_domain
        self.session = requests.Session()
        self.session.headers.update({
            'Authorization': f'Bearer {api_token}',
            'Content-Type': 'application/json',
        })
    def purge_html_cache(self):
        """只刷新 HTML 入口文件的 CDN 缓存，不刷静态资源"""
        # 静态资源文件名变了就是新 URL，CDN 自然回源，不需要主动 purge
        # 如果 purge 全站缓存，所有指纹化资源的缓存也失效了，损失巨大
        urls_to_purge = [
            f'https://{self.site_domain}/',
            f'https://{self.site_domain}/index.html',
        ]
        for url in urls_to_purge:
            try:
                resp = self.session.post(
                    f'{self.cdn_api_url}/purge',
                    json={'urls': [url]},
                    timeout=10,
                )
                if resp.status_code == 200:
                    logger.info(f'Purged CDN cache for: {url}')
                else:
                    logger.warning(f'Purge failed for {url}: {resp.status_code} {resp.text}')
            except requests.Timeout:
                # CDN API 超时不阻断部署流程，缓存会在 TTL 到期后自然更新
                logger.warning(f'CDN purge timeout for {url}, will expire naturally')
            except requests.RequestException as e:
                logger.error(f'CDN purge error: {e}')
    def verify_deployment(self, local_build_dir: str):
        """验证部署文件与 CDN 缓存的一致性"""
        # 读取本地构建产物的 HTML，检查其中引用的资源文件名
        html_path = os.path.join(local_build_dir, 'index.html')
        if not os.path.exists(html_path):
            logger.error(f'Local HTML not found: {html_path}')
            return False
        with open(html_path, 'r') as f:
            local_html = f.read()
        # 从线上获取 HTML，比对内容是否一致
        try:
            resp = self.session.get(
                f'https://{self.site_domain}/index.html',
                timeout=10,
                headers={'Cache-Control': 'no-cache'},  # 强制绕过本地缓存
            )
            remote_html = resp.text
            if local_html.strip() == remote_html.strip():
                logger.info('Deployment verification passed: HTML matches')
                return True
            else:
                # 计算两个 HTML 的 hash，便于定位差异
                local_hash = hashlib.sha256(local_html.encode()).hexdigest()[:16]
                remote_hash = hashlib.sha256(remote_html.encode()).hexdigest()[:16]
                logger.warning(
                    f'HTML mismatch: local={local_hash}, remote={remote_hash}'
                )
                return False
        except requests.RequestException as e:
            logger.error(f'Verification request failed: {e}')
            return False
    def deploy_and_purge(self, local_build_dir: str):
        """完整部署流程：先刷新 CDN HTML 缓存，再验证一致性"""
        self.purge_html_cache()
        # 等待 CDN 刷新传播：边缘节点同步需要时间
        time.sleep(3)
        return self.verify_deployment(local_build_dir)

四、边界分析与架构权衡

4.1 contenthash 的不稳定问题

Webpack 4 的 contenthash 在某些场景下不稳定：同一个文件内容，两次构建可能产出不同的 hash。原因是 chunk 之间的依赖关系影响了模块 ID 的分配，进而影响了模块内容的 hash 输入。

Webpack 5 已经用 optimization.realContentHash 修复了这个问题。Vite/Rollup 的 contenthash 本身就是基于最终输出内容计算的，天然稳定。

4.2 immutable 的副作用

Cache-Control: immutable 告诉浏览器"这个文件永远不会变，连 revalidate 都不需要"。但如果你的指纹化策略有 bug（比如两次构建产出相同文件名但不同内容），immutable 就变成灾难：浏览器永远用错误的缓存。

对策：构建 CI 中加一步校验——用内容 hash 校验文件名中的 hash 是否一致。

4.3 适用边界与禁用场景

适用：SPA 应用、静态资源独立部署、CDN 加速的生产环境
禁用：SSR 应用中内联的 CSS/JS（无法指纹化）、频繁热更新的开发环境、文件名长度受限的旧版 CDN（部分 CDN 对 URL 长度有上限）

4.4 Service Worker 与指纹化的冲突

SW 缓存策略可以绕过 HTTP 缓存头。如果你的 SW 用了 cache-first 策略缓存 HTML，指纹化就白做了——SW 会返回旧 HTML，旧 HTML 引用旧 JS，新 JS 永远不会加载。

对策：HTML 在 SW 中必须用 network-first 或 stale-while-revalidate，只有指纹化的静态资源才能用 cache-first。

五、总结

静态资源指纹化的核心思路：内容变则文件名变，文件名变则缓存自然失效，缓存失效则用户自然拿到新版本。HTML 作为入口不做长缓存，静态资源因为文件名包含 contenthash 可以放心缓存一年。Query String 方案有 CDN 和代理兼容性问题，不推荐生产使用。contenthash 是最稳定的 hash 算法，ChunkHash 和全局 Hash 会引发不必要的缓存失效。缓存更新与指纹化必须协同设计——只刷新 HTML 的 CDN 缓存，静态资源靠文件名变化自然更新。