🧭 Nginx Location Direktifi: Tam Eşleşme, Regex ve Proxy Yapılandırmaları (2025 Rehberi

---

🔍 Nginx Nedir ve Location Direktifi Ne İşe Yarar?

Nginx, HTTP isteklerini en verimli şekilde yönlendiren bir web sunucusudur. Bu rehberde, Nginx location direktifinin nasıl çalıştığını, eşleşme önceliğini, root ve alias farklarını ve ters vekil (reverse proxy) ayarlarını öğreneceksiniz. Amaç, Türk geliştiricilerin karmaşık yönlendirmeleri hatasız ve performanslı biçimde yapılandırmasını sağlamaktır.

---

📘 Bu Rehberde Ne Öğreneceksiniz?

• location direktifinin sözdizimi ve çalışma mantığı
• =, ^~, ~, ~* gibi niteleyicilerin farkı
• Eşleşme önceliği algoritması
• root ve alias arasındaki fark
• proxy_pass kullanarak ters vekil sunucu oluşturma
• Regex performans optimizasyonu ve hata ayıklama teknikleri

---

⚙️ Adım 1 – Location Direktifi Söz Dizimi

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

Niteleyici, Nginx’in URI eşleştirme biçimini değiştirir.

Niteleyici	Açıklama	Davranış	Öncelik
=	Tam eşleşme	URI birebir eşleşirse, diğerleri atlanır	🔺 En yüksek
^~	Önek eşleşme durdurucusu	Regex kontrolünü durdurur	🔸 Yüksek
~	Regex (büyük/küçük harf duyarlı)	Desene göre eşleşme	🔹 Orta
~*	Regex (büyük/küçük harf duyarsız)	Desene göre eşleşme	🔹 Orta
(yok)	Önek eşleşme	Diğer kontroller devam eder	⚪ En düşük

🔧 Örnekler

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

---

🧮 Adım 2 – Nginx Eşleşme Önceliği Algoritması

Nginx, her isteği aşağıdaki sırayla kontrol eder:

1. Tam eşleşme = → En yüksek öncelik.
2. En uzun önek eşleşmesi bulunur (^~ varsa regex kontrolü yapılmaz).
3. Regex eşleşmeleri (~ ve ~*) yapılandırma sırasına göre denenir.
4. Regex eşleşmezse, saklanan en uzun önek eşleşmesi kullanılır.
5. Hiçbiri eşleşmezse location / (catch-all) devreye girer.

🧩 Örnek:

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	Eşleşme	Sonuç
/api	Tam eşleşme	"API Tam"
/api/users	^~ öneki	"API Önek"
/api/v1/data	^~ öncelikli olduğu için Regex atlanır	"API Önek"

---

📁 Adım 3 – Statik Dosya Sunumu: root vs. alias

Özellik	root	alias
Davranış	URI’yı kök dizine ekler	URI’yı takma dizinle değiştirir
Sondaki / etkisi	Esnek	Zorunlu
Kullanım amacı	Klasik kök yapı	Farklı klasör yolu

root örneği

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

alias örneği

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

⚠️ Dikkat: alias kullanırken hem location hem de alias yollarında sondaki slash / olmalıdır. Aksi halde Nginx dosya yolunu yanlış çözer ve 404 hatası döndürür.

---

🔄 Adım 4 – Ters Vekil (Reverse Proxy) Yapılandırması

proxy_pass, gelen isteği bir backend uygulamasına yönlendirir.

Basit Örnek:

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

Sondaki Slash Farkı:

Durum	İstek URI	Arka Uca Gönderilen URI
Slash yok	/api/users	/api/users
Slash var	/api/users	/users

Kural:

• Eğer backend kendi /api önekiyle çalışıyorsa → slash koyma.
• Eğer root’tan başlıyorsa → slash ekle.

---

🪄 Adım 5 – Hata Ayıklama ve Test Etme

Yöntem 1: Header ile kontrol

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

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

Yanıtta X-Location: images-block görüyorsan o blok çalışıyordur.

Yöntem 2: Debug log

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

⚠️ Üretimde warn seviyesine geri dönmeyi unutma.

---

🔒 Güvenlik İçin Dosya Türü Engelleme

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

Bu ayar .env, .sql veya .log dosyalarına erişimi tamamen engeller.

---

🧠 Adım 6 – Tek Sayfa Uygulamalar (SPA) İçin Ayar

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

Bu yapı, SPA yönlendirmelerinde (örneğin /dashboard/settings) 404 hatalarını engeller.

---

💬 Sıkça Sorulan Sorular (SSS)

1️⃣ ^~ neden performans kazandırır?

Çünkü Regex kontrollerini tamamen atlar. CPU yükünü azaltır.

2️⃣ location / neden en sonda olmalı?

En genel bloktur, en düşük önceliğe sahiptir. Kodun okunabilirliğini artırır.

3️⃣ root ve alias farkını nasıl aklımda tutarım?

root → ekleme yapar, alias → değiştirir. “root append, alias replace” diye düşünebilirsin 😎

4️⃣ SPA 404 hatası nasıl çözülür?

try_files $uri $uri/ /index.html; ekle, gerisini front-end router halleder.

5️⃣ Hangi dosyalar engellenmeli?

.env, .ini, .sql, .bak, .conf gibi yapılandırma dosyaları mutlaka engellenmelidir.

---

🚀 Sonuç

Bu rehberle Nginx’in kalbi olan location direktifini detaylı şekilde öğrendin. Artık eşleşme önceliği, Regex kontrolü, root–alias farkı ve proxy davranışlarını ustaca yönetebilirsin.

✅ Özetle:

• = → Tam eşleşme
• ^~ → Regex kontrolünü durdurur
• ~ ve ~* → Regex
• root ekler, alias değiştirir
• Test etmeden reload yapma → sudo nginx -t

💡 Uygulamalarını Rabisu Bulut platformunda güvenli ve yüksek performanslı bir şekilde dağıtabilirsin.