Nginx部署SPA需用try_files指令解决前端路由404问题：location / { try_files $uri $uri/ /index.html; }，并配合静态资源缓存、API代理和子路径适配确保正确fallback。
在 Nginx 中部署 Vue、React 等单页应用（SPA）时，前端路由（如 Vue Router 的 history 模式或 React Router 的 BrowserRouter）依赖浏览器 History API，不向服务器发起新请求。当用户直接访问或刷新 /about、/user/123 这类前端路由路径时，Nginx 默认会尝试查找对应的真实文件或目录——而这些路径后端并不存在，结果返回 404。
try_files 是解决该问题的核心指令：它按顺序检查文件或路径是否存在，若全部失败，则回退到指定的 URI（通常是 /index.html），让前端接管路由逻辑。
基础配置：让所有非资源请求都 fallback 到 index.html
这是最常用也最稳妥的写法，适用于绝大多数 SPA 部署场景：
location / {
try_files $uri $uri/ /index.html;
}
说明：
立即学习“前端免费学习笔记（深入）”；
-
$uri：检查是否匹配静态文件（如/js/app.js、/logo.png） -
$uri/：检查是否匹配目录（如/assets/） -
/index.html：以上都不命中时，返回index.html，由前端 JS 解析当前 URL 并渲染对应页面
⚠️ 注意：/index.html 必须是 URI（以 / 开头），不是文件路径；Nginx 会自动触发内部重定向，不会暴露真实路径给客户端。
排除静态资源，避免干扰构建产物的缓存策略
如果项目构建后输出了带哈希的资源（如 /js/app.a1b2c3.js），且你希望对这些资源启用强缓存（Cache-Control: immutable），需单独声明静态资源 location，防止它们被 try_files 错误 fallback：
React 与 Next.js 性能优化指南，源自 Vercel 工程团队。适用于编写、审查或重构 React/Next.js 代码时使用。
# 优先匹配静态资源，直接返回并设置缓存
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2|ttf|eot|map)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}
<h1>主入口：只处理非静态资源请求</h1><p>location / {
try_files $uri $uri/ /index.html;
}
</p>这样既保障了资源缓存效率，又确保 /api/login 或 /admin 这类路径仍能正确 fallback。
配合 API 代理，避免跨域与路径冲突
开发时前端常通过 proxy（如 vue.config.js 的 devServer.proxy）转发 API 请求；生产环境建议由 Nginx 统一代理，避免 CORS 且更可控。注意不要让 API 路径被 try_files 拦截：
# API 接口统一代理到后端服务
location ^~ /api/ {
proxy_pass https://backend.example.com/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
<h1>其他所有请求走 SPA fallback</h1><p>location / {
try_files $uri $uri/ /index.html;
}
</p>关键点：
- 使用
^~前缀确保/api/优先于/匹配，避免被try_files错误捕获 - 不要在
location /api/内写try_files，否则可能把接口请求也 fallback 到index.html
进阶：支持子路径部署（base URL 不为 /）
若应用部署在子路径下（如 https://example.com/my-app/），前端需配置 base: "/my-app/"，Nginx 也要做适配：
location /my-app/ {
alias /var/www/my-app/;
try_files $uri $uri/ /my-app/index.html;
}
说明：
立即学习“前端免费学习笔记（深入）”；
- 用
alias（不是root）更准确映射子路径到物理目录 -
try_files的 fallback URI 必须与 base 一致，即/my-app/index.html - 确保前端构建时设置了正确的
publicPath或base，否则资源加载路径会出错
不复杂但容易忽略。只要理清“哪些请求该真实响应、哪些该交还前端”，try_files 就能稳稳撑起 SPA 的路由体验。
