使用 HTML5 History 模式时，Nginx 需配置 try_files $uri $uri/ /index.html 实现前端路由 fallback，同时前置声明 API 和静态资源规则避免冲突，并注意子路径部署时的 alias 与 base 一致性。
当使用 Vue Router、React Router 等前端路由库开启 HTML5 History 模式时，页面跳转不再依赖 # 哈希，而是真实的 URL 路径（如 /user/123）。但这类路径在刷新或直接访问时，Nginx 默认会尝试查找对应物理文件或目录——而实际这些路径由前端 JavaScript 控制，服务器上并不存在。结果就是 404 错误。解决的关键是：让 Nginx 对所有非静态资源请求，都 fallback 到 index.html，交由前端路由接管。
核心配置：location 匹配 + try_files 回退
在 server 块中添加以下配置，覆盖所有非 API 和非静态资源的请求：
location / {
try_files $uri $uri/ /index.html;
}说明：
-
$uri：先检查是否存在匹配的静态文件（如/css/app.css） -
$uri/：再检查是否为目录（如/assets/） -
/index.html：都不匹配时，返回根目录下的index.html，由前端 JS 解析当前 URL 并渲染对应视图
避免干扰 API 和静态资源
上述通配规则不能影响真实存在的后端接口和静态文件。需在 location / 之前，显式声明更高优先级的匹配规则：
立即学习“前端免费学习笔记（深入）”；
- API 请求通常带前缀（如
/api/或/v1/），单独配置代理：
location ^~ /api/ {
proxy_pass http://backend;
proxy_set_header Host $host;
}- 静态资源（js/css/img/font 等）可统一用正则或前缀隔离，确保它们被正确命中并缓存：
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?|ttf|eot)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}注意 SPA 的 index.html 必须可访问
确保构建产物中 index.html 位于 Nginx root 目录下（如 /usr/share/nginx/html/），且权限可读。若使用子路径部署（如部署在 /admin/ 下），还需调整前端路由的 base 配置，并在 Nginx 中相应修改回退路径：
location /admin/ {
alias /usr/share/nginx/html/admin/;
try_files $uri $uri/ /admin/index.html;
}注意：alias 后路径末尾需加 /，且 try_files 中的 fallback 路径要与 alias 逻辑一致。
验证与调试技巧
配置完成后，可通过以下方式快速验证：
- 直接浏览器访问一个前端路由路径（如
/dashboard），首次加载应正常；F5 刷新仍显示对应页面，而非 404 - cURL 检查响应头和内容：
curl -I http://your-domain.com/dashboard应返回 200 和text/html - 查看 Nginx error log（
/var/log/nginx/error.log）确认无 “open() failed” 类报错 - 临时注释掉
try_files行，观察是否立即出现 404，可反向确认逻辑生效
