Nginx root vs. alias for serving static files

root appends the request URI to a filesystem directory. alias replaces the matched location prefix with another path. Use root when the URL structure mirrors the directories on disk; use alias when a URL prefix should map somewhere else.

How root builds a path

server {
    listen 80;
    server_name example.com;
    root /var/www/html;

    location /images/ {
        # /images/logo.png maps to /var/www/html/images/logo.png
    }
}

The location inherits the server's root. Nginx appends /images/logo.png to /var/www/html.

How alias replaces a prefix

location /images/ {
    alias /data/pics/;
    # /images/logo.png maps to /data/pics/logo.png
}

Here /images/ is replaced with /data/pics/, and only the remaining logo.png is appended.

For a directory mapping, keep the trailing slash on both the location prefix and the alias path. Omitting the location's trailing slash can match unintended prefixes and create unsafe path mappings. Do not assume that removing both slashes is an equivalent safe configuration.

alias is valid in a location, not directly in a server block. In a regular-expression location, the alias should refer to captures from that expression. try_files checks paths using the active root or alias and can cause internal redirects; test the complete configuration rather than treating it as a universal add-on.

Choose the directive that matches the layout

Ask whether /images/ exists below the intended document root. If it does, root is usually straightforward. If the files actually live in /data/pics/, an alias expresses that mapping directly.

After a change, request both an existing file and a nonexistent one. Check the contents and status codes. Guance HTTP checks can test individual CSS, JavaScript, or image URLs. A single homepage HTTP check does not automatically request every referenced asset.

FAQ

How do I debug a 404 after adding an alias? Inspect the Nginx error log. An open() failure can show the path Nginx tried, such as /data/picslogo.png, making a missing separator visible. Also verify permissions and which location matched the request.

Can root appear inside a location? Yes. A location-specific root overrides the inherited value, while still appending the full URI.

Can alias contain variables? Yes, except $document_root and $realpath_root. Prefer fixed paths or an explicit allowlisted mapping; do not turn an arbitrary request Host header directly into a filesystem path.

Related reading

• Troubleshoot SSL_ERROR_RX_RECORD_TOO_LONG (Chinese)
• Risks of trusting every HTTPS certificate in Java and Python

Sources

This guide is based on the documentation below; the examples have not been tested against a live deployment.

• Nginx core module
• Guance HTTP checks