In NGINX configuration, the @ symbols within the location block are used to define named locations. These are internally used endpoints and cannot be matched directly by the client request. They are usually called via the error_page, try_files, or rewrite directives. 1. The naming location starts with @, such as location @notfound, will not respond to direct requests, but will trigger from other configuration parts; 2. It is often used for custom error handling, internal routing and backend proxy backing; 3. For example, combined with try_files, forwarding to @backend when static files do not exist; 4. Notes include: not directly accessed, avoiding naming conflicts, and using descriptive names. Named locations can contain standard NGINX instructions, support variables, which act like functions or subroutines in code, do not perform operations themselves, but perform functions when referenced.

In NGINX configuration, the @ symbol inside a location block is used to define a named location . These are internal-only endpoints that can't be matched by client requests directly—they're meant to be called using the error_page , try_files , or rewrite directives.

Named locations are handy for handling things like custom error pages, internal redirects, or processing fallback logic without exposing those paths publicly.

How Named Locations Work

A named location starts with @ followed by a name:

 location @notfound {
    # internal logic here
}

This location won't respond to direct requests like /notfound . Instead, it's triggered from other parts of the config—commonly via error_page or as a fallback in try_files .

For example:

 error_page 404 @notfound;

location @notfound {
    return 404 "Custom not found message";
}

When a 404 happens, NGINX internally forwards the request to the @notfound named location.

Common Use Cases for @-Named Locations

Here are a few real-world scenarios where named locations shine:

• Custom error handling : Redirecting 404s or 500s to a consistent internal handler.
• Internal routing : Using try_files to fall back to an internal location if files aren't found.
• Backend proxy fallbacks : If static files don't exist, pass control to a backend service.

Example with try_files :

 location / {
    try_files $uri $uri/ @backend;
}

location @backend {
    proxy_pass http://myapp;
}

In this case:

• NGINX first tries to serve a static file.
• If it doesn't exist, it routes the request to the @backend named location.

Things to Keep in Mind When Using @

• They're internal only : You can't access them directly via a browser or API call.
• Avoid naming conflicts : Choose unique names to prevent unexpected behavior.
• Use descriptive names : Like @php , @fallback , or @api_error , so it's clear what they do.

Also, remember that:

• You can use variables inside named locations.
• They can include any standard NGINX directives like proxy_pass , return , or rewrite .

So, when you see @something inside a location block, it's just NGINX setting up a label for internal routing—very similar to a function or subroutine in code. It doesn't do anything on its own but becomes powerful when referenced elsewhere.

Basically that's it.

The above is the detailed content of What does @ mean in a location block (named locations)?. For more information, please follow other related articles on the PHP Chinese website!