大型单页应用滚动更新时静态资源404问题，源于构建产物哈希不一致、Nginx路由配置不当及缓存策略失配；需确保contenthash稳定、Nginx alias指向版本化assets、index.html禁缓存而资源设immutable长期缓存，并配合灰度与健康检查验证。
大型单页应用（SPA）在 Kubernetes 集群中滚动更新时，常出现部分 Pod 已升级、部分仍旧版，导致浏览器请求静态资源（如 app.abc123.js 或 chunk-vendors.def456.css）时，新旧版本 index.html 与资源哈希不匹配——旧 Pod 返回 404，新 Pod 又未被命中，从而触发“静态资源 404”问题。核心不在 Nginx 路由，而在构建产物一致性、缓存策略与服务发现协同失效。
确保构建产物哈希稳定且可跨版本共存
Webpack/Vite 构建时若启用 contenthash（推荐），每次代码变更仅影响对应文件名；但若配置不当（如将公共 chunk 命名固定为 vendor.js 却未加 hash），新旧版本会覆盖同一路径，造成资源错乱。必须保证：
- 所有 JS/CSS/图片资源输出路径均含唯一 contenthash（例如
js/app.[contenthash:8].js） - index.html 不参与 hash，但需通过
publicPath指向统一 CDN 或子路径（如/assets/），避免相对路径解析歧义 - 构建产物目录结构扁平化，禁用嵌套 hash 目录（如
js/chunk/[hash]/main.js），防止 Nginx alias 映射失败
配置 Nginx 以支持多版本资源并行服务
不要依赖单一 root 指向最新构建目录。应将每次构建产物上传至带时间戳或 commit ID 的独立子目录（如 /usr/share/nginx/html/v1.2.3/），再通过软链接或环境变量切换 active 版本。Nginx 配置需兼容：
- 使用
alias替代root处理 assets 路径： location /assets/ { alias /usr/share/nginx/html/current/assets/; } - 对根路径
/启用 try_files，但指向版本化入口： location / { try_files $uri $uri/ /current/index.html; } - 禁止对
/assets/下资源做 try_files 回退，防止错误加载旧版 index.html 内容
控制客户端缓存与服务端路由协同
浏览器强缓存 index.html（max-age=0 或 no-cache）可避免旧 HTML 加载新资源路径；而 JS/CSS 应设长期缓存（max-age=31536000）。关键操作包括：
- 在 Nginx 中为
index.html设置：add_header Cache-Control "no-cache, no-store, must-revalidate"; - 为
.js/.css/.png等资源设置：expires 1y; add_header Cache-Control "public, immutable"; - Ingress 配置中关闭
nginx.ingress.kubernetes.io/configuration-snippet的默认缓存头覆盖行为，确保上述规则生效
验证资源可用性与灰度流量隔离
滚动更新期间，可通过健康检查端点暴露当前 Pod 所服务的构建版本号（如 /healthz?version），配合 Prometheus 抓取各 Pod 实际提供资源的哈希值。同时建议：
- 在 Ingress 中为新版本 Service 添加 canary 标签，并用
nginx.ingress.kubernetes.io/canary-by-header控制灰度流量 - 前端在加载资源前，先请求一个轻量级 manifest.json（含当前版本全部资源路径），校验缺失则主动刷新页面或降级提示
- 利用
Service Mesh（如 Istio）对 /assets/ 路径做重试 + 超时熔断，避免单个 Pod 故障引发全量 404
