nginx中try_files用于spa路由兜底,需在location /内配置root、index和try_files $uri $uri/ /index.html;子路径部署用alias并调整兜底路径;api接口须前置独立location拦截。

Nginx 中 try_files 配置默认首页兜底,核心不是“显示首页”,而是让所有未命中静态资源的请求,安静返回 /index.html(状态码 200),由前端接管路由渲染。这常见于 Vue、React 等单页应用(SPA)部署场景。
必须写在 location / 块内
location / {
root /var/www/myapp; # 指向构建输出目录(如 dist/)
index index.html; # 显式声明默认索引文件
try_files $uri $uri/ /index.html;
}
-
$uri:优先检查请求路径是否对应真实文件(如/js/app.js、/logo.png)→ 存在则直接返回 -
$uri/:再检查是否为真实存在的目录(如/assets/)→ 存在且开启autoindex才可能列出内容(SPA 通常不依赖此项,但保留更健壮) -
/index.html:前两者都不匹配时,内部重写为根目录下的index.html,URL 不变,浏览器仍显示/user/profile,但 HTML 内容是index.html
⚠️ 注意:
-
root路径必须真实包含index.html文件 -
index index.html;必须显式声明,否则 Nginx 在 fallback 到/index.html时可能因索引未定义而报错 - 不要用
=404或@notfound代替/index.html,那会中断前端路由流程
子路径部署(如 /admin/)要同步改三处
若应用访问地址是 https://example.com/admin/:
- 前端构建时设
base: '/admin/'(Vue)或basename="/admin/"(React Router) - Nginx 配置用
alias(不是root):
location /admin/ {
alias /var/www/myapp/dist/; # alias 后必须带尾部斜杠
index index.html;
try_files $uri $uri/ /admin/index.html;
}
-
try_files的兜底项必须写成/admin/index.html,因为alias会把该路径拼接到实际目录前(即/var/www/myapp/dist/admin/index.html) - 若误写为
/index.html,Nginx 会去站点根目录找,大概率 404
API 接口必须提前拦截,避免被兜底
后端接口如 /api/login,需单独配置并放在 location / 之前:
location /api/ {
proxy_pass https://backend-server;
}
location / {
root /var/www/myapp;
index index.html;
try_files $uri $uri/ /index.html;
}
Nginx 按最长前缀匹配,/api/ 会先被截获代理,不会进入主 location / 的 try_files 流程。
不复杂但容易忽略











