try_files 是 Nginx 中用于按顺序探测文件或目录是否存在的指令,核心逻辑是:依次检查前面的 “file 参数”,找到第一个存在的就使用它;如果全部不存在,则执行最后一个 “uri 参数” 或 “=code 参数”。它最典型的用途是替代简单的 rewrite 规则,在前端路由回退、PHP 入口统一、默认图片等场景中非常常见。
语法与两种参数
try_files file1 [file2 ... fileN] uri;
try_files file1 [file2 ... fileN] =code;
file 参数(非最后一个)
- 如果参数不以
/结尾,try_files把它当作文件检查:将参数中的变量展开,拼接root或alias指定的路径,检查磁盘上是否存在该文件。 - 如果参数以
/结尾(如$uri/),则把它当作目录检查。 - 非最后一个参数只做“存在性检查”,不会触发内部重定向;找到后就在当前
location上下文中处理该文件或目录。
最后一个参数(回退参数)
- 如果最后一个参数是 URI,则触发内部重定向,Nginx 会重新走一遍 location 匹配流程,而不是向客户端发 301/302。
- 如果最后一个参数是
=code,直接返回指定的 HTTP 状态码,如=404。 - 最后一个参数也可以指向命名 location(如
@backend)。 - 最后一个参数必须能解析到实际存在的资源或合法状态码,否则会返回 500。
一个容易忽略的细节:$uri 变量本身的值不以 / 结尾(比如 /foo 结尾是 o),所以 try_files $uri 检查的是“是否存在名为 foo 的文件”,而不是目录。要检查目录,必须显式写成 $uri/。
最基础的示例:$uri 与 $uri/
location / {
root /var/www/html;
try_files $uri $uri/ =404;
}
执行顺序:
- 检查
$uri对应的文件是否存在(如/about.html); - 检查
$uri/对应的目录是否存在(如/docs/); - 都不存在,返回
404。
这是静态站点的“无重写”兜底配置,与 index 指令配合时,目录存在后会进一步由 index 决定返回哪个首页文件。
典型场景与配置示例
场景一:SPA(Vue / React)history 路由回退
使用 history 模式时,直接访问或刷新 /user/123/orders 这类前端路由,磁盘上并不存在对应文件,Nginx 会返回 404。try_files 的作用是:真实文件优先,找不到再统一返回 index.html,交给前端路由接管。
server {
listen 80;
server_name example.com;
root /var/www/my-app/dist;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
}
建议最后一个参数写 /index.html(以 / 开头),明确表示内部重定向;不以 / 开头会被当作内部文件路径处理,行为不够直观。
场景二:静态资源与 SPA 回退分离
SPA 的兜底逻辑如果对所有路径生效,旧版本遗留的 JS/CSS 请求(如 /assets/old-chunk.js)也会返回 index.html,浏览器会因 MIME 类型不匹配而报错。稳妥做法是给静态资源单独配置,找不到就老实返回 404:
location /assets/ {
expires 1y;
add_header Cache-Control "public, immutable";
try_files $uri =404;
}
location / {
try_files $uri $uri/ /index.html;
}
这样 /assets/ 下不存在的文件不会被降级为 index.html,前端可以正常捕获 404 并提示刷新。
场景三:PHP 入口统一(WordPress / Laravel 等)
将不存在的路径统一交给 index.php 处理,同时保留查询参数:
location / {
try_files $uri $uri/ /index.php?$query_string;
}
如果使用 PATH_INFO 风格,可以写为:
location / {
try_files $uri $uri/ /index.php?$args;
}
注意:与 rewrite 不同,try_files 的回退 URI 不会自动保留 $args,如果希望保留查询参数,必须显式带上 $query_string 或 $args。
场景四:默认图片 / 兜底静态文件
当请求的图片不存在时,返回一个默认图片:
location /images/ {
try_files $uri /images/default.gif;
}
location = /images/default.gif {
expires 30s;
}
这里 try_files 的前一个参数检查文件,最后一个参数 /images/default.gif 触发内部重定向,再通过精确匹配的 location = 处理缓存头。
场景五:配合命名 location 做后端回退
当回退目标需要统一交给后端(如 FastAPI、Node)处理时,可以用命名 location:
location / {
try_files $uri $uri/ @backend;
}
location @backend {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
命名 location 只能作为 try_files 的最后一个参数使用;如果把 @backend 写在中间,Nginx 会把它当作普通文件路径,不会识别为命名 location。
try_files 与 rewrite 的关键区别
| 维度 | try_files |
rewrite |
|---|---|---|
| 主要用途 | 按顺序探测文件/目录是否存在,选择“用哪个” | 按正则修改 URI |
| 触发条件 | 文件不存在时执行回退 | 条件匹配即执行改写 |
| 重定向类型 | 最后一个参数触发内部重定向 | 可内部(last/break),也可外部(permanent/redirect) |
| 查询参数保留 | 回退 URI 不会自动保留,需显式带上 $args/$query_string |
默认保留查询参数 |
| 适合场景 | 静态文件优先、SPA 回退、PHP 入口 | 路径结构变换、旧链接迁移 |
多数“文件存在就用它,不存在就交给别处”的需求,try_files 比 rewrite 更直接,也更不容易误伤同目录下的其他真实文件。
使用时的注意事项
1. alias 与 try_files 混用需谨慎try_files 的文件路径由 file 参数结合 root 或 alias 构造。在某些 Nginx 版本中,alias 与 try_files 混用可能丢失路径前缀,导致预期外的 404 或错误路径。如果必须使用 alias,建议先在小范围验证路径拼接结果。
2. $uri 与 $uri/ 不可混淆
只写 $uri 时检查的是文件;要检查目录,必须写成 $uri/。如果只写 try_files $uri $uri/; 而没有回退参数,在某些情况下可能造成内部循环,应始终提供最后一个回退参数。
3. 回退目标必须可达
最后一个参数无论是 URI、命名 location 还是 =code,都必须能产生有效响应。如果回退 URI 指向的资源不存在,又没有后续处理,可能返回 500 而不是预期的 404 或页面。
4. $args 不会自动传递
回退到 URI 时,原始查询参数默认不会被保留。需要保留时写成 try_files $uri $uri/ /index.php?$query_string; 之类的形式。
5. 子路径部署时 try_files 回退路径要同步调整
如果应用部署在 /admin/ 下,回退应写为 /admin/index.html,同时 root/alias、构建工具的 base 都要对齐,否则会出现白屏或资源 404。