SoFunction
Updated on 2025-03-03

Implementation example of try_files directive in Nginx

1. Introduction

try_files is a very powerful and commonly used directive in Nginx that is used to check if files exist in order and pass requests to the first found file, or to execute a fallback URI when all files are not found. This directive is especially useful when configuring static websites or single page applications (SPAs), as it ensures that Nginx prioritizes static files, and forwards requests to the backend application or provides a fallback page only if the static file does not exist.

2. Basic syntax

try_files file ... uri;
  • file ... : One or more file paths to check. Nginx will check whether these files exist in the order provided;
  • uri: If all specified files do not exist, a fallback URI is executed. The URI can be a static page (such as a 404 page) or a request handler (such as an entry point for PHP scripts or applications that handle all front-end routing);

Example of using try_files:

try_files  $uri $uri/ /TEST/;

Here $uri is the original URI requested by the client.

Let's explain this instruction step by step:

1) $uri: Nginx will first try to find the file directly from the requested URI. For example, if the user requests /about, Nginx will try to find the /about file.
2) $uri/: If the file is not found in the first step, Nginx will try to treat the requested URI as a directory and add a slash / afterwards. For example, if the user requests /about, Nginx will try to find the /about/ directory.
3) /TEST/: If the file or directory is not successfully found in the first two steps, Nginx will try to return the /TEST/ file.

but:

  • If the user requests an existing file (such as /about), Nginx will return the file directly.
  • If the user requests a directory (such as /about/), Nginx will try to return the default file under that directory.
  • If neither of the above happens, Nginx will eventually try to return /TEST/.
  • Such configuration is ideal for single page applications (SPAs) or those that want to provide a default page for all routes not found. For example, if you have a front-end application hosted under /TEST/ and all pages are rendered in /TEST/, this configuration ensures that no matter what path the user requests, the homepage of the application can be seen.

3. Case

3.1 Static website

Suppose there is a static website, and its HTML, CSS and JS files are stored in the /data/www directory, and I hope that Nginx will first try to directly serve these static files. If the file does not exist, it will return a 404 error.

server {  
    listen       80;  
    server_name  ;  
  
    root   /data/www;  
  
    location / {  
        try_files $uri $uri/ =404;  
    }  
}

In this example, $uri represents the requested URI (excluding the host name and port). If the file or directory pointed to by $uri exists, Nginx will directly serve it. If the file pointed to by $uri does not exist but the directory exists, Nginx will try to add a slash at the end and try the request again. If the file is not found, Nginx will return a 404 error.

3.2 Single-page application

For single-page applications, you want to return the same HTML file (usually) no matter what URL is requested, and then let the front-end route process these URLs, which can be achieved by setting the fallback of the try_files directive to that HTML file.

server {  
    listen       80;  
    server_name  ;  
  
    root   /usr/share/nginx/html;  
  
    location / {  
        try_files $uri $uri/ /;  
    }  
}

In this configuration, Nginx first tries to the service requested file or directory, and if it cannot be found, it will fall back to /, which allows the front-end route to take over and display the correct page. This method is especially suitable for single-page applications built by modern front-end frameworks such as React, Vue, or Angular.

This is the article about the implementation example of the try_files instruction in Nginx. For more related contents of the Nginx try_files instruction, please search for my previous articles or continue browsing the related articles below. I hope everyone will support me in the future!