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;
}

执行顺序:

  1. 检查 $uri 对应的文件是否存在(如 /about.html);
  2. 检查 $uri/ 对应的目录是否存在(如 /docs/);
  3. 都不存在,返回 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。