核心解法是配置try_files $uri $uri/ /index.html;，需在location /块内配齐root、index index.html及该指令，顺序不可错；子路径需同步调整fallback路径，API须独立location /api/代理以防误捕获。
刷新页面返回 404，不是前端路由写错了，而是 Nginx 按路径找真实文件，根本没把请求交还给 index.html。核心解法就一条：try_files $uri $uri/ /index.html;，但必须配对生效，否则照样 404。
location / 里漏了 try_files 或顺序错了
try_files 必须放在 location / 块内，且三要素要齐：正确的 root、显式的 index index.html、以及严格按顺序写的 try_files $uri $uri/ /index.html;。
-
$uri匹配真实文件（如/js/app.a1b2c3.js），顺序放最前，否则静态资源全被兜底到index.html -
$uri/匹配真实目录（如/assets/），注意末尾斜杠不能少 -
/index.html是最终 fallback，路径必须和root拼起来能定位到文件，比如root /var/www/myapp;就要求磁盘上存在/var/www/myapp/index.html - 别在它后面加
rewrite或return，会打断内部重写流程
API 请求被 try_files 拦截返回 HTML
如果后端接口走同域名下的 /api/，而你只写了 location /，那 /api/login 也会被 try_files 判定为“不存在的文件”，最后返回 index.html——浏览器看到的是 200，内容却是 HTML，前端 fetch 拿不到 JSON。
- 必须单独声明
location /api/，且写在location /之前或同级 -
location /api/末尾带斜杠，确保最长前缀匹配优先于/ -
proxy_pass结尾也加斜杠：proxy_pass http://backend/;，避免路径拼接出错 - 验证方法：用
curl -I http://localhost/api/health，响应头里Content-Type应为application/json，不是text/html
HTML 缓存导致新路由白屏或报错
加了 try_files 后，浏览器若缓存了旧版 index.html，而新版已增加路由逻辑或修改了 JS 加载方式，用户刷新时仍加载旧 HTML，就会白屏或控制台报 Route not found 类错误。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
立即学习“前端免费学习笔记（深入）”；
- 给 HTML 强制不缓存：
add_header Cache-Control "no-cache, no-store, must-revalidate"; - JS/CSS/图片等静态资源必须用内容哈希命名（如
main.8f3a2d.js），再配长期缓存：expires 1y; - 别依赖
meta标签或 JS 控制缓存，HTTP 响应头才真正起效 - 上线后清一次 CDN 缓存，否则旧 HTML 可能从边缘节点返回
子路径部署时 fallback 路径没改
项目没部署在域名根目录，而是 https://example.com/admin/ 这种子路径，try_files $uri $uri/ /index.html; 里的 /index.html 会去找根目录下的文件，自然 404。
- 此时
root应指向子路径物理位置，例如root /var/www/admin; -
try_files的 fallback 要同步调整为/admin/index.html，或者更稳妥地用index.html（相对路径）配合alias，但alias和try_files易冲突，推荐前者 - 构建时也要配前端框架的
publicPath或base，确保资源引用路径正确，否则/js/app.js会 404 - 验证时别只测
/admin/，一定要测/admin/some-route，看是否返回index.html且地址栏不变
最容易被忽略的是：配置改完没跑 nginx -t 就 reload，或者压根没确认 index.html 真在 root 指向的目录里——Nginx 不报错，但所有请求都 fallback 失败，静默返回 404。
