fix: nginx index.html 禁用浏览器缓存，防止部署后旧 chunk 引用导致白屏 #1212

Merged

xiaoxia merged 1 commits from fix/nginx-index-no-cache into develop 2026-08-01 18:28:50 +08:00

Conversation 3 Commits 1 Files Changed 2

+14

xiaoxia commented 2026-08-01 18:20:06 +08:00

Owner

Copy Link

Copy Source

问题

当前 nginx 配置的 location / 对 index.html 没有设置任何 Cache-Control 头。浏览器会按默认策略缓存 HTML 文件。

Vite 构建的 JS/CSS 文件名自带 content hash，配置了 expires 1y 长期缓存——这是正确的。

但问题在于：每次部署后 chunk 文件名变化（新 hash），但浏览器仍用缓存的旧 index.html 指向旧 chunk，导致 Failed to fetch dynamically imported module 白屏。

修复方案

在 location / 块上方新增精确匹配块：

# index.html must never be cached — it contains chunk references
location = /index.html {
    add_header Cache-Control "no-cache, no-store, must-revalidate";
    add_header Pragma "no-cache";
    expires 0;
}

影响范围

• infra/docker/nginx.conf (production)
• infra/docker/nginx-staging.conf (staging)

两个文件都做了相同的修改。

验证方式

部署后，浏览器 DevTools → Network → 查看 index.html 响应头：

• Cache-Control: no-cache, no-store, must-revalidate
• Pragma: no-cache
• 每次刷新都应返回 200（而非 304）

注意事项

• Nginx location = /index.html 是精确匹配，优先级高于 location /（前缀匹配）
• 不影响其他静态资源（JS/CSS 图片等）的缓存策略
• 不影响 API 代理和 generated-files 路由

## 问题 当前 nginx 配置的 `location /` 对 index.html 没有设置任何 Cache-Control 头。浏览器会按默认策略缓存 HTML 文件。 Vite 构建的 JS/CSS 文件名自带 content hash，配置了 `expires 1y` 长期缓存——这是正确的。 但问题在于：**每次部署后 chunk 文件名变化（新 hash），但浏览器仍用缓存的旧 index.html 指向旧 chunk，导致 `Failed to fetch dynamically imported module` 白屏。** ## 修复方案 在 `location /` 块上方新增精确匹配块： ```nginx # index.html must never be cached — it contains chunk references location = /index.html { add_header Cache-Control "no-cache, no-store, must-revalidate"; add_header Pragma "no-cache"; expires 0; } ``` ## 影响范围 - `infra/docker/nginx.conf` (production) - `infra/docker/nginx-staging.conf` (staging) 两个文件都做了相同的修改。 ## 验证方式 部署后，浏览器 DevTools → Network → 查看 index.html 响应头： - `Cache-Control: no-cache, no-store, must-revalidate` - `Pragma: no-cache` - 每次刷新都应返回 200（而非 304） ## 注意事项 - Nginx `location = /index.html` 是精确匹配，优先级高于 `location /`（前缀匹配） - 不影响其他静态资源（JS/CSS 图片等）的缓存策略 - 不影响 API 代理和 generated-files 路由

xiaoxia added 1 commit 2026-08-01 18:20:06 +08:00

fix: 禁止浏览器缓存 index.html，防止部署后旧 chunk 引用导致白屏 ... df38778875

- nginx.conf 和 nginx-staging.conf 新增 location = /index.html 精确匹配块
- 设置 Cache-Control: no-cache, no-store, must-revalidate
- 设置 Pragma: no-cache 和 expires 0
- 确保每次部署后浏览器获取最新的 index.html（含新 chunk hash）

auto-approve-bot commented 2026-08-01 18:21:25 +08:00

Collaborator

Copy Link

Copy Source

【阻塞级判定】

• 是否存在阻塞级问题：否
• 阻塞级问题数量：0 个

📊 审查概览

• 整体评价：通过
• 建议级问题数量：0 个

🔴 阻塞级问题（必须修复）

无

💡 改进建议（不阻塞合并）

无

✅ 良好实践

1. [infra/docker/nginx-staging.conf & nginx.conf] 正确使用精确匹配
   • 使用 location = /index.html 精确匹配优先级高于前缀匹配，确保缓存控制策略仅针对根目录入口文件生效，避免误拦截其他静态资源。
2. [infra/docker/nginx-staging.conf & nginx.conf] 完善的缓存控制策略
   • 组合使用 no-cache, no-store, must-revalidate 以及 Pragma 和 Expires，能够最大程度兼容各种浏览器和代理服务器，确保 SPA 部署后用户始终获取最新的 HTML 文件，有效避免“白屏”或旧版本 Chunk 加载错误。
3. [infra/docker/nginx-staging.conf & nginx.conf] 清晰的代码注释
   • 注释准确说明了禁止缓存的技术原因（包含 chunk 引用），有助于后续维护人员理解配置意图。

---

_{🤖 由 AI 代码审查机器人自动生成 | 2026-08-01 10:21:25 | 模型:}

### 【阻塞级判定】 - 是否存在阻塞级问题：否 - 阻塞级问题数量：0 个 ### 📊 审查概览 - 整体评价：通过 - 建议级问题数量：0 个 ### 🔴 阻塞级问题（必须修复） 无 ### 💡 改进建议（不阻塞合并） 无 ### ✅ 良好实践 1. **[infra/docker/nginx-staging.conf & nginx.conf] 正确使用精确匹配** - 使用 `location = /index.html` 精确匹配优先级高于前缀匹配，确保缓存控制策略仅针对根目录入口文件生效，避免误拦截其他静态资源。 2. **[infra/docker/nginx-staging.conf & nginx.conf] 完善的缓存控制策略** - 组合使用 `no-cache`, `no-store`, `must-revalidate` 以及 `Pragma` 和 `Expires`，能够最大程度兼容各种浏览器和代理服务器，确保 SPA 部署后用户始终获取最新的 HTML 文件，有效避免“白屏”或旧版本 Chunk 加载错误。 3. **[infra/docker/nginx-staging.conf & nginx.conf] 清晰的代码注释** - 注释准确说明了禁止缓存的技术原因（包含 chunk 引用），有助于后续维护人员理解配置意图。 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-08-01 10:21:25 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

gitea-actions bot commented 2026-08-01 18:21:30 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

项目	详情
PR号	#1212
预览链接	https://pr-1212.preview.xiaoxiajianji.com
API环境	staging

💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。

🔄 每次提交新代码后预览环境会自动更新。

🗑️ PR 关闭或合并后，预览环境会自动清理。

🚀 **预览环境已部署** | 项目 | 详情 | |------|------| | PR号 | #1212 | | 预览链接 | [https://pr-1212.preview.xiaoxiajianji.com](https://pr-1212.preview.xiaoxiajianji.com) | | API环境 | staging | > 💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。 > > 🔄 每次提交新代码后预览环境会自动更新。 > > 🗑️ PR 关闭或合并后，预览环境会自动清理。

xiaoxia merged commit 2bb8cc3bb3 into develop 2026-08-01 18:28:50 +08:00

xiaoxia deleted branch fix/nginx-index-no-cache 2026-08-01 18:28:50 +08:00

gitea-actions bot commented 2026-08-01 18:30:09 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

PR #1212 已关闭或合并，对应的预览环境已被清理。

如有需要，可以重新打开 PR 来重新生成预览环境。

🗑️ **预览环境已清理** PR #1212 已关闭或合并，对应的预览环境已被清理。 > 如有需要，可以重新打开 PR 来重新生成预览环境。

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot xiaoxia

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#1212