Eski içerikleri yeni yapıya taşı

Netlify redirects, ziyaretçinin istediği bir URL’yi başka bir adrese yönlendirmek veya URL’yi değiştirmeden farklı bir kaynaktan içerik sunmak için kullanılır. Kurallar publish directory içindeki uzantısız _redirects dosyasına ya da repository’deki netlify. toml dosyasına yazılabilir. Redirect tarayıcıya yeni konumu bildirir; rewrite ise çoğunlukla 200 status code ile adres çubuğunu koruyup başka dosya, Function veya dış API yanıtını sunar.

En kritik iki konu kural sırası ve shadowing davranışıdır. Netlify ilk eşleşen kuralı uygular. _redirects kuralları önce, ardından netlify. toml kuralları işlenir. Geniş bir wildcard kuralını en üste koymak, daha özel yönlendirmelerin hiç çalışmamasına neden olabilir.

Öne Çıkanlar

• _redirects dosyası build sonunda gerçek publish directory içinde bulunmalıdır.
• netlify.toml, daha yapılandırılmış syntax ve ek proxy seçenekleri sunar.
• Netlify ilk eşleşen redirect kuralını yukarıdan aşağıya işler.
• _redirects dosyasındaki kurallar netlify.toml redirect’lerinden önce değerlendirilir.
• 301 ve 308 kalıcı; 302 ve 307 geçici yönlendirme için kullanılır.
• 200 kuralı çoğunlukla rewrite/proxy davranışıdır; ziyaretçinin URL’si değişmez.
• force veya _redirects içindeki !, mevcut dosyanın route’u gölgelemesine rağmen kuralı zorlar.
• Edge Functions, redirect motorundan önce çalışabilir.

Redirect ile Rewrite Arasındaki Fark Nedir?

Redirect, ziyaretçiye “aradığın kaynak başka adreste” der. Browser yeni URL’ye ikinci bir istek yapar ve adres çubuğu değişir.

``text /eski-yazi → /yeni-yazi ``

Rewrite ise kullanıcının gördüğü URL’yi korur; Netlify arka planda başka bir içerik veya endpoint sunar.

``text /api/status → /.netlify/functions/status ``

Temel farklar:

Kriter	Redirect	Rewrite / proxy
Tipik status	301, 302, 307, 308	200
Adres çubuğu	Değişir	Değişmez
Yeni browser isteği	Genellikle evet	Netlify arka planda işler
SEO amacı	URL taşıma/canonical	İç routing veya backend proxy
Kullanım örneği	Eski blog URL’si	SPA fallback, Function, dış API

Bir URL kalıcı olarak taşındıysa 301/308; bakım veya kısa kampanya yönlendirmesi geçiciyse 302/307 daha uygundur. HTTP method ve body koruma ihtiyacında 307/308 davranışı ayrıca değerlendirilmelidir.

_redirects Dosyası Nasıl Oluşturulur?

Dosyanın adı tam olarak _redirects olmalı ve uzantısı bulunmamalıdır. Her kural tek satırda yazılır:

``text /eski-sayfa /yeni-sayfa 301 /kampanya /yeni-kampanya 302 ``

Dosya kaynak projede herhangi bir yerde durabilir; önemli olan build sonunda publish directory içine kopyalanmasıdır.

Vite projesinde yaygın yapı:

``text public/ └── _redirects ``

Build sonrasında:

``text dist/ ├── index.html ├── _redirects └── assets/ ``

Dosyanın gerçekten deploy çıktısında olduğunu doğrulayın:

``bash npm run build ls -la dist ``

src/_redirects oluşturmak, framework dosyayı otomatik kopyalamıyorsa yeterli değildir. Netlify yalnız publish edilen çıktıyı görür.

Kurallar case-sensitive’dir. Özel karakter içeren path’ler URL encoded yazılmalıdır. Yorum satırları # ile başlar:

```text

Eski içerikleri yeni yapıya taşı

/Blog/Eski-Yazi /blog/yeni-yazi 301 ```

Buradaki /Blog ile /blog aynı kaynak path değildir.

netlify.toml ile Redirect Nasıl Yazılır?

Her kural ayrı [[redirects]] tablosudur:

``toml [[redirects]] from = "/eski-sayfa" to = "/yeni-sayfa" status = 301 ``

Wildcard örneği:

``toml [[redirects]] from = "/old-blog/*" to = "/blog/:splat" status = 301 ``

TOML formatı şu alanları açıkça tanımlayabilir:

• from: Eşleşecek kaynak path,
• to: Hedef path veya URL,
• status: HTTP status code,
• force: Mevcut içerik olsa da kuralı zorlama,
• query: Gerekli query parametreleri,
• conditions: Ülke, dil, rol veya cookie koşulları,
• headers: Proxy isteğine eklenecek header’lar,
• signed: Signed proxy için environment variable adı.

Secret değerini doğrudan headers içine yazmayın. Signed proxy veya server-side Function gibi güvenli yöntem kullanın.

Kural Sırası Nasıl Çalışır?

Netlify bir istek için ilk eşleşen kuralda durur. Bu nedenle özel kural önce, geniş wildcard sonra yazılır.

Doğru sıra:

``text /api/health /.netlify/functions/health 200 /eski-hakkimizda /hakkimizda 301 /* /index.html 200 ``

Yanlış sıra:

``text /* /index.html 200 /api/health /.netlify/functions/health 200 ``

İlk satır her isteği yakaladığı için /api/health kuralı çalışmayabilir.

İki dosya birlikte kullanılıyorsa işlem sırası şöyledir:

1. _redirects içindeki kurallar,
2. netlify. toml içindeki kurallar.

Aynı source path iki yerde tanımlanırsa _redirects kuralı önce eşleşebilir. Bakımı kolaylaştırmak için routing kurallarını mümkünse tek kaynağa toplayın.

Netlify’nin request işleme zincirinde Edge Functions redirect motorundan önce devreye girebilir. Edge Function’ın response döndürmesi veya URL’yi değiştirmesi, beklediğiniz redirect’in çalışmamasına yol açabilir. Karmaşık projede tüm request processing order incelenmelidir.

SPA Fallback Nasıl Eklenir?

React Router, Vue Router veya benzeri client-side routing kullanan SPA’da kullanıcı ana sayfadan /dashboard route’una geçebilir. Fakat /dashboard adresi doğrudan açıldığında server fiziksel dosya arar ve 404 dönebilir.

Yaygın _redirects kuralı:

``text /* /index.html 200 ``

TOML karşılığı:

``toml [[redirects]] from = "/*" to = "/index.html" status = 200 ``

Bu kural URL’yi değiştirmez. index. html döner, ardından client router path’i yorumlar.

SPA fallback’i listenin sonunda tutun. Gerçek API ve özel redirect kuralları önce gelmelidir. Ayrıca Next. js veya Astro SSR gibi framework adapter routing’i olan projelerde bu kuralı otomatik eklemeyin; server route’larını gölgeleyebilir.

Test:

``bash curl -I https://example.netlify.app/dashboard ``

200 görmek yeterli değildir. Browser’da gerçekten dashboard component’inin render edildiğini ve bilinmeyen route’un doğru 404 ekranına gittiğini de kontrol edin. Her bilinmeyen URL’yi 200 döndürmek SEO ve hata gözlemi açısından yanıltıcı olabilir.

Wildcard ve Placeholder Nasıl Kullanılır?

Bir path segmentini taşımak için :splat kullanılır:

``text /docs/* /rehber/:splat 301 ``

Örnek eşleşme:

``text /docs/install → /rehber/install ``

Named placeholder örneği:

``text /blog/:year/:slug /arsiv/:year/:slug 301 ``

Çok sayıda benzer redirect’i ayrı ayrı yazmak yerine wildcard veya placeholder kullanmak dosyayı küçültür. Netlify, 10. 000 veya daha fazla redirect gereken yapılarda wildcard/placeholder kullanımını öneriyor; daha karmaşık kurallarda Edge Functions değerlendirilebilir.

Wildcard kullanırken fazla geniş eşleşmeye dikkat edin. /blog/* yalnız beklenen blog yollarını mı, yoksa /blog/api gibi başka route’ları da mı yakalıyor? Test matrisi gerçek URL örnekleri içermelidir.

Force ve Shadowing Nedir?

Netlify varsayılan olarak deploy edilen gerçek dosyayı redirect kuralına tercih edebilir. Buna shadowing denir. Örneğin /about/index. html varsa /about için yazılan redirect beklediğiniz gibi çalışmayabilir.

_redirects içinde zorlamak için:

``text /about /company 301! ``

netlify. toml içinde:

``toml [[redirects]] from = "/about" to = "/company" status = 301 force = true ``

Force, mevcut içeriği bilerek geçersiz kılar. Yanlış kullanılırsa gerçek asset veya sayfayı ulaşılamaz hâle getirebilir. Kullandığınız her forced rule için gerekçe ve test yazın.

Dış API’ye Proxy Rewrite Nasıl Yapılır?

Browser’dan /api/products isteği gönderip arka planda dış API’ye ulaşmak için:

``toml [[redirects]] from = "/api/*" to = "https://api.example.com/:splat" status = 200 force = true ``

Bu yaklaşım URL’yi aynı origin altında tutabilir ve bazı CORS sorunlarını azaltabilir. Fakat proxy güvenlik katmanı değildir. Dış endpoint kimlik doğrulama gerektiriyorsa private key’i client’a veya açık TOML dosyasına koymayın.

Dikkat edilmesi gerekenler:

• Kullanıcı kontrollü path’in hangi hedeflere ulaşabildiği,
• Timeout ve upstream hata davranışı,
• Rate limiting,
• Request/response header’ları,
• Kişisel verinin üçüncü tarafa iletilmesi,
• Cache ve hata status’larının korunması,
• API maliyeti ve abuse.

Daha karmaşık doğrulama, authentication veya response dönüşümü için Netlify Function daha uygun olabilir.

Query Parametreli ve Koşullu Redirect Nasıl Yapılır?

TOML ile belirli query parametresi zorunlu tutulabilir:

``toml [[redirects]] from = "/search" to = "/new-search" status = 302 query = { legacy = "true" } ``

Bu kural yalnız beklenen query koşulu eşleştiğinde uygulanır. Dil veya ülke koşulları da tanımlanabilir; ancak coğrafi redirect, kullanıcı tercihlerini, SEO crawling’i ve privacy beklentisini etkileyebilir.

Koşullu yönlendirmede kullanıcıya manuel dil/ülke seçimi bırakmak ve seçimi cookie ile hatırlamak çoğu zaman daha iyi deneyimdir. IP konumunu kesin gerçek kabul etmeyin.

Domain Redirect Nasıl Yapılır?

Eski domain’i yeni domaine taşırken path’i koruyan wildcard tercih edin:

``toml [[redirects]] from = "https://old.example.com/*" to = "https://new.example.com/:splat" status = 301 force = true ``

Eski domain’in de Netlify projesine bağlı ve DNS’inin Netlify’ye yönelmiş olması gerekir. Aksi hâlde istek Netlify redirect motoruna ulaşmaz.

Taşıma sırasında:

• Query parametrelerinin korunması,
• HTTP ve HTTPS host’ları,
• Apex ve www,
• Canonical URL,
• Sitemap,
• Eski backlink’ler,
• Redirect chain ve loop

kontrol edilmelidir.

Redirect Loop Neden Oluşur?

Loop, A URL’sinin B’ye, B’nin tekrar A’ya yönlenmesiyle oluşur:

``text /a → /b /b → /a ``

Domain seviyesinde de görülebilir:

``text example.com → www.example.com www.example.com → example.com ``

Birden fazla katmanda kural varsa teşhis zorlaşır: Netlify primary domain redirect’i, _redirects, uygulama middleware’i ve external proxy aynı isteği değiştirebilir.

İzlemek için:

``bash curl -I https://example.com/path curl -IL --max-redirs 10 https://example.com/path ``

-L redirect zincirini takip eder. Production’da sonsuz deneme yapmamak için maksimum redirect sayısı sınırlandırın.

10 Rotalı Test Matrisi

Yayın öncesinde en az şu rotalar doğrulanmalıdır:

#	İstek	Beklenen	Kontrol amacı
1	/old-page	301 → /new-page	Exact kalıcı redirect
2	/campaign	302 → yeni kampanya	Geçici redirect
3	/docs/install	301 → /guide/install	Wildcard/splat
4	/api/health	200 Function yanıtı	Internal rewrite
5	/api/items/42	200 proxy sonucu	External proxy
6	/dashboard	200 SPA shell + doğru UI	SPA fallback
7	/about	Forced redirect	Shadowing/force
8	/search?legacy=true	Koşullu redirect	Query match
9	Eski domain path’i	Yeni domainde aynı path	Domain migration
10	Loop senaryosu	Loop olmamalı	Zincir güvenliği

> Editör notu — zorunlu özgün test: Bu taslaktaki on rota gerçek Netlify deploy’unda çalıştırılmadı. Yayından önce _redirects ve netlify. toml için iki ayrı branch oluşturulmalı; her rotada curl -i sonucu, Location, status code, final URL, kural sırası ve deploy commit’i kaydedilmelidir. Proxy testinde yalnız güvenli demo endpoint kullanılmalı; private API key eklenmemelidir.

> Görsel notu: Browser request → Edge Function → _redirects → netlify. toml → static file/Function/upstream sırasını gösteren özgün şema ile 10 rotanın status haritası hazırlanmalıdır.

> İç link editör notu: netlify. toml, React deploy, domain ve Edge Functions yazıları yayına girdiğinde ilgili bölümlere doğal bağlantı eklenmelidir.

Yaygın Netlify Redirects Hataları

_redirects deploy’a girmiyor

Dosya kaynak klasörde var ama publish directory’ye kopyalanmıyor olabilir. Build sonrası çıktı ağacını kontrol edin.

Kural hiç çalışmıyor

Daha önceki geniş kural eşleşiyor, path case’i farklı veya özel karakter encode edilmemiş olabilir.

SPA fallback API’yi HTML döndürüyor

/* /index. html 200 kuralı API rewrite’ından önce gelmiştir. API kuralını üste taşıyın.

Redirect yerine sayfa açılıyor

Mevcut dosya shadowing yapıyor olabilir. Gerçekten gerekli ise force kullanın.

301 değişikliği tarayıcıda kalıyor

Browser ve CDN kalıcı redirect’i cache’lemiş olabilir. Kural geliştirirken önce 302 kullanıp doğrulama sonrası 301’e geçmek daha güvenlidir.

Proxy 200 yerine upstream hatasını gizliyor

Gerçek response status ve body’yi gözlemleyin. Rewrite kullanmak upstream servisinin güvenilirliğini değiştirmez.

Çok fazla redirect deploy’u bozuyor

Kuralları wildcard ve placeholder ile sıkıştırın. On binlerce karmaşık karar için Edge Function veya uygulama yönlendirmesi daha uygun olabilir.

Netlify Redirects Kontrol Listesi

• [ ] Routing kuralları tek bir ana kaynakta tutuluyor.
• [ ] _redirects gerçek publish directory’de.
• [ ] Exact kurallar wildcard’dan önce.
• [ ] SPA fallback en sonda.
• [ ] Status code geçici/kalıcı amaca uygun.
• [ ] Force kullanılan her kural gerekçeli.
• [ ] Proxy secret’ı client veya repository’de değil.
• [ ] Apex/www ve eski domain zinciri test edildi.
• [ ] curl -IL ile loop kontrolü yapıldı.
• [ ] Unknown URL doğru 404 davranışını koruyor.
• [ ] Edge Function ve framework routing etkisi incelendi.

Sık Sorulan Sorular

_redirects mi, netlify.toml mı kullanılmalı?

Basit kurallarda ikisi de uygundur. TOML daha yapılandırılmış ve ek özelliklere sahiptir. Çakışmayı azaltmak için tek ana kaynak seçin.

200 redirect ne anlama gelir?

Pratikte rewrite/proxy davranışıdır. Kullanıcının URL’si değişmeden başka dosya veya endpoint yanıtı sunulur.

SPA için 301 mi, 200 mü gerekir?

SPA fallback için 200 rewrite gerekir. 301 kullanılırsa tüm route’lar browser’da index. html adresine dönüşür.

Netlify redirects case-sensitive mi?

Evet. Kaynak path’lerde büyük-küçük harf farkı önemlidir ve özel karakterler URL encoded olmalıdır.

Redirect kuralları hangi sırada işlenir?

İlk eşleşen kural kazanır. _redirects dosyası önce, ardından netlify. toml kuralları işlenir; Edge Functions redirect motorundan önce çalışabilir.

Kaynaklar

• Redirects and rewrites overview
• Redirect options
• Rewrites and proxies
• File-based configuration
• Request processing order

Sonuç

Netlify redirects yapılandırmasının başarısı, syntax kadar kural sırasına bağlıdır. Kalıcı URL taşımalarında doğru status code’u kullanın, exact kuralları wildcard’dan önce yazın, SPA fallback’i listenin sonunda tutun ve proxy’yi güvenlik katmanı sanmayın. _redirects ile netlify. toml birlikte kullanılabiliyor olsa da çakışmayı önlemek için tek bir ana kaynak seçmek daha kolaydır. Her değişikliği status, Location, final URL ve loop açısından gerçek deploy’da test edin.

Redirect ve rewrite kurallarını bir demo projede uygulamak için [ücretsiz Netlify hesabı oluşturabilirsiniz](https://join. netlify. com/wmkqymu1heo2). Bu bir iş ortaklığı bağlantısıdır; bağlantı üzerinden kayıt olmanız veya ücretli plana geçmeniz halinde Ortak Alan komisyon kazanabilir.