Nginx Location Directive: Exact Match, Regex and Proxy Configurations (2025 Guide

🔍 What is Nginx and What Does the Location Directive Do?

Nginx is a web server that routes HTTP requests in the most efficient way. In this guide, you will learn how the Nginx location directive works, match priority, root and alias differences, and reverse proxy settings. The aim is to enable Turkish developers to configure complex routings in an error-free and high-performance manner.

---

📘 What Will You Learn in This Guide?

• Syntax and working logic of the location directive
• Difference of qualifiers like =, ^~, ~, ~*
• Match priority algorithm
• Difference between root and alias
• Creating a reverse proxy using proxy_pass
• Regex performance optimization and debugging techniques

---

⚙️ Step 1 – Location Directive Syntax

location [niteleyici] [URI] {
    # direktifler buraya yazılır
}

Qualifier changes the way Nginx matches URIs.

Qualifier	Description	Behavior	Priority
=	Exact match	If the URI matches exactly, others are skipped	🔺 Highest
^~	Prefix match interceptor	Stops regex checking	🔸 High
~	Regex (case sensitive)	Match by pattern	🔹 Medium
~*	Regex (case insensitive)	Match by pattern	🔹 Medium
(none)	Prefix match	Other checks continue	⚪ Lowest

🔧 Examples

# Tam eşleşme
location = /status {
    return 200 "OK";
}

# Önek eşleşme durdurucusu
location ^~ /static/images {
    root /var/www;
}

# Regex (büyük/küçük harfe duyarsız)
location ~* \.(jpg|png|gif)$ {
    root /var/www/assets;
}

---

🧮 Step 2 – Nginx Match Priority Algorithm

Nginx checks each request in the following order:

1. Exact match = → Highest priority.
2. Longest prefix match is found (no regex check if ^~ is present).
3. Regex matches (~ and ~*) are attempted in configuration order.
4. If the regex does not match, the longest stored prefix match is used.
5. If none match, location / (catch-all) occurs.

🧩 Example:

server {
    location ~ /api/v1 { return 200 "API v1"; }
    location ^~ /api { return 200 "API Önek"; }
    location = /api { return 200 "API Tam"; }
    location / { return 200 "Varsayılan"; }
}

URI	Match	Conclusion
/api	Exact match	"API Full"
/api/users	^~ prefix	"API Prefix"
/api/v1/data	Regex is skipped as ^~ takes precedence	"API Prefix"

---

📁 Step 3 – Static File Presentation: root etc. alias

Feature	root	alias
Behavior	Appends the URI to the root	Replaces URI with alias
/ effect at the end	Flexible	Mandatory
Intended use	Classic root structure	Different folder path

root example

location /static/ {
    root /var/www/site;
}
# /static/css/main.css → /var/www/site/static/css/main.css

alias example

location /static/ {
    alias /var/cdn/assets/;
}
# /static/css/main.css → /var/cdn/assets/css/main.css

⚠️ Attention: When using alias, the trailing slash must be /** in both location and alias paths. Otherwise, Nginx will decode the file path incorrectly and return error 404.

---

🔄 Step 4 – Reverse Proxy Configuration

proxy_pass forwards the incoming request to a backend application.

Simple Example:

location /api/ {
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

Slash Difference at the End:

Status	Request URI	URI Sent to Backend
No Slash	/api/users	/api/users
Slash exists	/api/users	/users

Rule:

• If the backend is running with its own prefix /api → slash do not put.
• If starting from root → slash add.

---

🪄 Step 5 – Debugging and Testing

Method 1: Control with Header

location /images/ {
    add_header X-Location "images-block" always;
}

curl -I http://example.com/images/test.jpg

If you see X-Location: images-block in the response, that block is working.

Method 2: Debug log

error_log /var/log/nginx/error.log debug;

⚠️ Don't forget to get back to warn in production.

---

🔒 File Type Blocking for Security

location ~ \.(env|ini|log|sql|bak|conf)$ {
    deny all;
    return 404;
}

This setting completely blocks access to .env, .sql or .log files.

---

🧠 Step 6 – Setting for Single Page Applications (SPA)

location / {
    root /var/www/spa;
    try_files $uri $uri/ /index.html;
}

This structure prevents 404 errors on SPA redirects (e.g. /dashboard/settings).

---

💬 Frequently Asked Questions (FAQ)

1️⃣ Why does ^~ increase performance?

Because it completely bypasses Regex checks. Reduces CPU load.

2️⃣ Why should location / be last?

It is the most general block and has the lowest priority. It increases the readability of the code.

3️⃣ How do I remember the difference between root and alias?

root → adds, alias → changes. You may think “root append, alias replace” 😎

4️⃣ How to solve SPA 404 error?

Add try_files $uri $uri/ /index.html; and the front-end router will do the rest.

5️⃣ Which files should be blocked?

Configuration files such as .env, .ini, .sql, .bak, .conf must be blocked.

---

🚀 Result

With this guide, you learned the location directive, the heart of Nginx, in detail. Now you can expertly manage match priority, Regex control, root–alias difference and proxy behavior.

✅ In summary:

• = → Exact match
• ^~ → Stops regex checking
• ~ and ~* → Regex
• root adds, alias replaces
• Do not reload without testing → sudo nginx -t

💡 You can distribute your applications securely and with high performance on the GenixNode platform.