如何利用 try_files 指令完美支持 Vue/React 等单页应用的路由回退-Nginx-PHP中文网

nginx部署spa需用try_files指令解决前端路由404问题：location / { try_files $uri $uri/ /index.html; }，并配合静态资源缓存、api代理和子路径适配确保正确fallback。

如何利用 try_files 指令完美支持 vue/react 等单页应用的路由回退

在 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：

Orderly Sdk React Hooks

Orderly React SDK 钩子使用参考指南，包括 useOrderEntry、usePositionStream、useOrderbookStream、useCollateral 等。

下载

# 优先匹配静态资源，直接返回并设置缓存
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 的路由体验。

前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索前端的入门与实战技巧！