Netlify Edge Network ve Cache Nasıl Çalışır? Performans Rehberi

Netlify CDN cache, statik dosyaları Netlify’nin global edge noktalarında tutarak her isteğin origin veya Function’a gitmesini azaltır. Statik asset’ler deploy sürümüyle birlikte cache’lenir ve içerik yeni deploy’da değiştiğinde otomatik olarak invalidation uygulanır. Netlify Functions, Edge Functions ve proxy response’ları ise dynamic kabul edildiği için varsayılan olarak cache’lenmez; bunları cache’e almak istiyorsanız uygun response header’larını açıkça tanımlamanız gerekir.

Cache performansını yalnız Lighthouse skoru veya tek bir TTFB ölçümüyle değerlendirmek yanıltıcıdır. İlk ve tekrar istek, edge miss/hit, deploy sonrası invalidation, kullanıcı konumu, response varyantı ve browser cache ayrı ayrı gözlemlenmelidir.

Öne Çıkanlar

• Statik asset response’ları Netlify edge node’larında cache’lenir ve yeni deploy içerik değiştirdiğinde otomatik invalidation alır.
• Netlify statik asset’i yeni deploy veya manual purge yoksa edge üzerinde bir yıla kadar fresh kabul edebilir; browser’a gönderilen varsayılan Cache-Control farklıdır.
• Functions, Edge Functions ve proxy response’ları varsayılan olarak cache’lenmez.
• Netlify’ye özel en öncelikli header Netlify-CDN-Cache-Control, ardından CDN-Cache-Control, sonra Cache-Control gelir.
• stale-while-revalidate, eski response’u kısa süre sunarken arka planda yenilemeye izin verir.
• durable shared cache, normal Netlify Functions response’larında kullanılabilir; Edge Functions için desteklenmez.
• Netlify-Vary, query, header, dil, ülke veya cookie’ye göre cache key varyantları oluşturabilir.
• Cache-Status header’ı edge ve durable cache’in miss, hit veya stale durumunu gösterir.

Netlify Edge Network ve CDN Ne Yapar?

Netlify deploy çıktısını global edge ağına dağıtır. Ziyaretçi bir HTML, CSS, JavaScript, font veya image istediğinde request uygun edge node tarafından karşılanabilir. İçerik cache’deyse origin compute çalıştırmadan response sunulur.

Basitleştirilmiş akış:

``text Kullanıcı isteği ↓ En uygun Netlify edge node ↓ Cache hit? ── evet → response │ hayır ↓ Static deploy / Function / Edge Function / proxy ↓ Cache policy uygunsa sakla ↓ Response ``

Edge network yalnız dosya kopyalamak değildir. TLS termination, routing, redirects, Edge Functions, cache key oluşturma, Image CDN ve request processing gibi katmanlar aynı zincirde yer alabilir.

Kullanıcıya yakın edge node genel olarak network süresini azaltabilir; fakat gerçek TTFB, DNS, TLS, connection reuse, cache hit, Function region, upstream API ve response boyutundan etkilenir.

Static Asset Caching Varsayılan Olarak Nasıl Çalışır?

Statik asset, deploy içinde değişmeden duran dosyadır. Netlify’nin güncel caching dokümanına göre static asset response’ları global edge node’larda cache’lenir ve content yeni deploy ile değiştiğinde otomatik olarak invalidation alır.

Netlify edge için varsayılan yaklaşım:

``text Netlify-CDN-Cache-Control: public, s-maxage=31536000, must-revalidate Cache-Control: public, max-age=0, must-revalidate ``

Bu iki header farklı cache katmanlarına hitap eder:

• Netlify-CDN-Cache-Control, Netlify edge cache davranışını yönetir.
• Cache-Control, browser ve downstream cache’lere iletilir.

Böylece edge uzun süre cache kullanabilir, browser ise her ziyarette revalidation yaparak güncel deploy’u alabilir. Atomik deploy ve otomatik invalidation, hash’li asset’ler ile HTML’in farklı sürümlerinin karışmasını azaltır.

Netlify, statik response’ların yalnız deploy veya manual purge ile değişebileceğini varsaydığı için edge tarafında daha kısa max-age ayarlama girişimlerini yok sayabilir. Browser davranışını yine Cache-Control ile yönetebilirsiniz.

Hash’li asset neden önemlidir?

Vite gibi build araçları şu tür dosyalar üretir:

``text /assets/app-a7f31c.js /assets/styles-9d421e.css ``

İçerik değiştiğinde filename hash’i değişir. Bu asset’lere browser için de uzun cache vermek güvenlidir:

``toml [[headers]] for = "/assets/*" [headers.values] Cache-Control = "public, max-age=31536000, immutable" ``

Hash’siz /app. js dosyası aynı URL’de değişiyorsa immutable kullanmak stale client sorununa yol açabilir.

Functions, Edge Functions ve Proxy Response’ları Nasıl Cache Edilir?

Dynamic response’lar deploy dışında da değişebilir. Bu nedenle Netlify Functions, Edge Functions ve proxy response’ları varsayılan olarak cache’lenmez.

Varsayılan dynamic header:

``text Cache-Control: public, max-age=0, must-revalidate ``

Cache’e almak için response’ta açık policy gerekir. Normal Function örneği:

```ts export default async () => { const payload = { generatedAt: new Date().toISOString(), value: "public-demo" };

return Response. json(payload, { headers: { "Netlify-CDN-Cache-Control": "public, max-age=60, stale-while-revalidate=120" } }); }; ```

Bu response’un gerçekten public ve tüm kullanıcılar için aynı olduğundan emin olun. Cookie, authorization veya kişisel veri varsa shared cache veri sızıntısı yaratabilir.

Edge Functions cache’i opt-in yapılandırma gerektirir. Framework veya inline config, response caching’i sizin yerinize yönetebilir; kullanılan framework adapter’ın güncel dokümanını kontrol edin.

Proxy response’unda upstream Cache-Control bulunabilir. Netlify’nin header precedence ve proxy davranışını test edin; upstream’in private response’unu yanlışlıkla public cache’e çevirmeyin.

Cache-Control Header’ları Arasındaki Fark Nedir?

Netlify-CDN-Cache-Control

Yalnız Netlify CDN için en spesifik header’dır. Browser’a doğrudan cache talimatı vermeden Netlify edge’i yönetmek için kullanılır.

``text Netlify-CDN-Cache-Control: public, max-age=300 ``

CDN-Cache-Control

Birden fazla CDN/downstream shared cache için standartlaşan header’dır. Netlify bunu kullanabilir ve downstream’e iletir.

``text CDN-Cache-Control: public, s-maxage=300 ``

Cache-Control

Browser ve diğer genel cache’ler tarafından kullanılır.

``text Cache-Control: public, max-age=60 ``

Öncelik:

``text Netlify-CDN-Cache-Control > CDN-Cache-Control > Cache-Control ``

Response birden fazla header içerirse Netlify en spesifik olanı kendi cache’i için kullanır; CDN-Cache-Control ve Cache-Control downstream’e iletilmeye devam edebilir.

Örnek ayrım:

``text Netlify-CDN-Cache-Control: public, max-age=600 Cache-Control: public, max-age=30 ``

Netlify edge 10 dakika, browser 30 saniye policy kullanabilir. Gerçek response header’ını curl -I ile doğrulayın; framework header’ı değiştirmiş olabilir.

Stale-While-Revalidate Ne Zaman Kullanılır?

stale-while-revalidate (SWR), cache süresi dolmuş response’un belirli bir ek süre içinde ziyaretçiye sunulmasına izin verirken arka planda yeni response üretir.

``text Netlify-CDN-Cache-Control: public, max-age=60, stale-while-revalidate=300 ``

Kavramsal davranış:

• İlk 60 saniye: fresh cache response.
• Sonraki 300 saniye: stale response hızlıca sunulabilir ve arka planda refresh başlatılabilir.
• Bu pencere sonrası: yeni response için origin/Function gerekir.

SWR şu içeriklerde yararlı olabilir:

• Her birkaç dakikada güncellenen public liste,
• Ürün katalog görünümü,
• Public CMS content,
• Dış API’nin geçici yavaşlığını tolere eden veri.

Şu durumlarda dikkat:

• Stok veya fiyat anlık doğruluk gerektiriyorsa,
• Kullanıcıya özel veri varsa,
• Revocation veya güvenlik değişikliği anında görünmeliysa,
• Hukuki/time-sensitive content stale sunulmamalıysa.

SWR kullanıldığında içerik güncelliği SLA’sını ürün ekibiyle açıkça belirleyin.

Durable Cache Nedir?

Normal Netlify Function response’unda durable directive, response’u shared durable cache’e koyar. Bir edge node kendi cache’inde response bulamazsa Function’ı çalıştırmadan önce durable cache’i kontrol edebilir.

``ts export default async () => { return Response.json( { publicData: "example" }, { headers: { "Netlify-CDN-Cache-Control": "public, durable, max-age=60, stale-while-revalidate=120" } } ); }; ``

Potansiyel faydalar:

• Daha az Function invocation,
• Edge miss’lerinde daha tutarlı response süresi,
• Dış API quota ve rate limit baskısının azalması,
• Farklı edge node’lar arasında shared cached response.

Netlify tek cache version için her durumda yalnız bir Function invocation garantisi vermez. Farklı region’larda kısa sürede gelen istekler eventual consistency nedeniyle birden fazla invocation oluşturabilir.

23 Ağustos 2026 itibarıyla durable Edge Functions response’larında desteklenmez. Directive’i Edge response’a eklemek beklenen shared cache etkisini oluşturmaz.

Cache Key Variation Nasıl Çalışır?

Cache key, hangi request’lerin aynı cached object’i paylaşacağını belirler. Varsayılan olarak standard Vary header değerleri dikkate alınır. Bazı dynamic response’larda query parametreleri de cache key’e girer.

Netlify’ye özel Netlify-Vary ile daha kontrollü varyant oluşturulabilir:

``text Netlify-Vary: query=category|sort ``

Bu durumda utm_source gibi response’u değiştirmeyen query’ler cache key’i parçalamaz.

Dil bazlı:

``text Netlify-Vary: language ``

Ülke bazlı:

``text Netlify-Vary: country ``

Cookie bazlı:

``text Netlify-Vary: cookie=experiment ``

Desteklenen ana vary alanları:

• query,
• header,
• language,
• country,
• cookie.

Her yeni vary boyutu cache hit oranını düşürebilir. Kullanıcı ID gibi yüksek cardinality değerini shared cache key’e koymak, neredeyse her kullanıcı için ayrı object üretir ve operasyonel faydayı azaltır. Kişisel içerikte private/no-store yaklaşımı daha doğru olabilir.

Aynı URL tüm response’larda tutarlı Netlify-Vary döndürmelidir. İlk cache object’in vary talimatı sonraki response’lar için etkili olabilir; koşula göre farklı vary header üretmek belirsiz sonuç yaratır.

Deploy Sonrası Otomatik Invalidation Nasıl Çalışır?

Atomic deploy, dosya setini tek sürüm olarak yayınlar. Yeni deploy içerik değiştirince Netlify ilgili static asset cache’lerini invalidation ile günceller. Bu model, eski HTML’in yeni olmayan asset’e işaret etmesi gibi karışık sürüm sorunlarını azaltır.

Default cache ID deploy sürümüyle ilişkilidir. Özel Netlify-Cache-ID kullanarak object’i otomatik deploy invalidation’dan ayırmak mümkündür; bu ileri düzey özellik yanlış kullanılırsa stale content’in deploy sonrasında kalmasına yol açabilir.

Özel cache ID kullanıldığında:

• Otomatik invalidation davranışı değişir,
• ID case-insensitive olabilir,
• ID cache tag olarak purge için kaydedilebilir,
• Manual on-demand invalidation planı gerekir.

Bu seçeneği yalnız deploy’lar arasında cache’i bilerek korumak istediğiniz ve purge sahibini tanımladığınız durumda kullanın.

On-Demand Invalidation Nasıl Yapılır?

Netlify cache tüm site veya tag bazında purge edilebilir. Tag ile invalidation için response’a cache tag eklenir:

``text Netlify-Cache-Tag: products,catalog-v3 ``

Ardından uygun Netlify API/SDK ile belirli tag purge edilir. API token’ı browser’a konmamalı; server-side yönetim veya güvenli CI secret kullanılmalıdır.

Tag tasarımında:

• Çok genel tag tüm cache’i gereksiz yere siler,
• Çok ayrıntılı tag yönetimi karmaşıklaştırır,
• Tenant/user PII tag adına konmamalıdır,
• Content publish webhook’u ile purge güvenli şekilde doğrulanmalıdır,
• Tekrar gelen webhook idempotent olmalıdır.

Manual purge’in kendisi performans stratejisi değildir. Yanlış cache TTL veya vary tasarımını sürekli purge ile telafi etmek maliyet ve karmaşıklık yaratır.

Cache Davranışı curl ile Nasıl Test Edilir?

Header’ları görmek için:

``bash curl -sS -D - -o /dev/null https://example.netlify.app/assets/app.js ``

Tekrar isteği:

``bash curl -sS -D - -o /dev/null https://example.netlify.app/assets/app.js ``

Dynamic endpoint:

``bash curl -sS -D - -o /dev/null https://example.netlify.app/api/public-data ``

İncelenecek header’lar:

• Cache-Control,
• CDN-Cache-Control,
• Netlify-CDN-Cache-Control,
• Cache-Status,
• Age,
• Vary,
• Netlify-Vary,
• ETag,
• Last-Modified.

Netlify edge miss örneği:

``text Cache-Status: "Netlify Edge"; fwd=miss ``

Hit:

``text Cache-Status: "Netlify Edge"; hit ``

SWR ile stale sunum:

``text Cache-Status: "Netlify Edge"; hit; fwd=stale ``

Durable cache devredeyse birden fazla Cache-Status header’ı görülebilir. Netlify Edge ve Netlify Durable satırlarını ayrı okuyun.

Her istek farklı cache instance’a düşebilir. Trafiği düşük bir test sitesinde ilk birkaç tekrarın tamamının miss olması mümkündür. Tek bir miss/hit çiftine dayanmayın.

Browser ile Cache Nasıl İncelenir?

Browser DevTools Network sekmesinde:

1. “Disable cache” kapalıyken normal davranışı görün. 2. Hard reload ve normal navigation’ı ayırın. 3. Service worker’ın response’u ele geçirip geçirmediğini kontrol edin. 4. Disk cache, memory cache ve network response’u ayırın. 5. Response headers ile transferred size’ı kaydedin.

Browser cache hit, Netlify edge hit ile aynı şey değildir. Browser hiç network isteği göndermediyse edge davranışını ölçemezsiniz. CDN testi için curl veya cache’i bypass etmeyen kontrollü HTTP aracı kullanın.

Dört Aşamalı Zorunlu Test

Aynı static asset ve public Function endpoint’i için:

Aşama	Static asset	Function response	Kaydedilecekler
İlk istek	Ölçülmedi	Ölçülmedi	Cache-Status, Age, TTFB
İkinci/tekrar istek	Ölçülmedi	Ölçülmedi	hit/miss, body version
Yeni deploy sonrası	Ölçülmedi	Ölçülmedi	invalidation, deploy ID
Manual tag/site purge sonrası	Ölçülmedi	Ölçülmedi	miss/hit dönüşü

Her aşamada en az birkaç tekrar ve iki farklı test lokasyonu kullanılabilir. TTFB ölçüm komutu:

``bash curl -sS -o /dev/null \ -w 'status=%{http_code} ttfb=%{time_starttransfer} total=%{time_total}\n' \ https://example.netlify.app/api/public-data ``

> Editör notu — zorunlu özgün kanıt: Bu taslak hazırlanırken static asset ve Function response için dört aşamalı cache testi çalıştırılmadı. Yayından önce aynı deploy’da cache header’ları, body version, Cache-Status, Age, TTFB, test lokasyonu, sample size, connection reuse ve deploy/purge zamanları kaydedilmelidir. Tek Lighthouse skoru veya tek istek performans garantisi gibi sunulmamalıdır.

> Görsel notu: Edge miss/hit/durable akış şeması, redakte response header ekranı ve ilk istek–tekrar–deploy–purge ölçüm grafiği hazırlanmalıdır.

> İç link editör notu: Edge Functions karşılaştırması, deploy türleri ve Astro rehberi yayımlandığında cache seçimi bölümlerine doğal bağlantı eklenmelidir.

Yaygın Netlify CDN Cache Hataları

Function response’u cache olmuyor

Dynamic response varsayılan olarak cache’sizdir. Uygun Netlify/CDN cache header eklenmemiş veya response private/no-store olabilir.

Kişisel veri başka kullanıcıya görünüyor

Public shared cache yanlış kullanılmış veya vary key kullanıcı/auth durumunu ayırmıyor olabilir. Cache’i hemen purge edin, endpoint’i private/no-store yapın ve incident incelemesi başlatın.

Deploy sonrası eski content görünüyor

Browser/service worker cache’i, custom cache ID ile automatic invalidation opt-out veya external CDN katmanı olabilir. Her cache katmanını ayrı inceleyin.

Her request miss oluyor

İstekler farklı edge instances’a gidiyor, query parametreleri cache key’i bölüyor, cookie/header varyantı çok geniş veya TTL çok kısa olabilir.

Age header yok

Her cache katmanı Age döndürmeyebilir. Cache-Status ve body version ile birlikte yorumlayın.

durable Edge Function’da etkisiz

Durable cache normal Functions response’ları için desteklenir. Edge Functions’ta farklı opt-in edge cache yaklaşımı kullanın.

Basic auth açınca cache kayboluyor

Netlify dokümanına göre basic-auth site genelinde caching’i devre dışı bırakabilir. Preview protection ve performans testini aynı varsayımla değerlendirmeyin.

Çok fazla cache varyantı oluşuyor

Her query/cookie/header’ı key’e eklemek hit oranını düşürür. Response’u gerçekten değiştiren az sayıda alanı seçin.

Netlify CDN Cache Kontrol Listesi

• [ ] Response static mi dynamic mi açıkça sınıflandırıldı.
• [ ] Browser ve Netlify edge TTL’leri ayrı tasarlandı.
• [ ] Hash’li asset’lerde uzun immutable cache doğrulandı.
• [ ] Dynamic response varsayılan cache’siz davranışla test edildi.
• [ ] Public/private veri sınıfı cache öncesi belirlendi.
• [ ] Header precedence anlaşıldı.
• [ ] SWR için kabul edilen stale süre yazıldı.
• [ ] Durable yalnız uygun Function response’unda kullanıldı.
• [ ] Vary boyutları minimum ve tutarlı.
• [ ] Deploy sonrası invalidation doğrulandı.
• [ ] Manual purge ve cache tag sahibi belli.
• [ ] Cache-Status, body version ve TTFB birlikte kaydedildi.

Sık Sorulan Sorular

Netlify statik dosyaları otomatik cache’ler mi?

Evet. Static asset response’ları global edge node’larda cache’lenir ve deploy içerik değiştirince otomatik invalidation uygulanır.

Netlify Functions response’u otomatik cache olur mu?

Hayır. Functions, Edge Functions ve proxy response’ları dynamic olduğu için varsayılan olarak cache’lenmez. Açık cache header ve güvenli cache key tasarımı gerekir.

Cache-Control ile Netlify-CDN-Cache-Control farkı nedir?

Cache-Control browser ve genel downstream cache’leri; Netlify-CDN-Cache-Control özellikle Netlify edge cache’i yönetir ve Netlify açısından daha yüksek önceliğe sahiptir.

Cache hit nasıl anlaşılır?

Response’taki Cache-Status header’ında "Netlify Edge"; hit gibi değerler aranır. Durable cache varsa ayrı Netlify Durable satırı görülebilir.

Deploy cache’i otomatik temizler mi?

Default deploy cache ID kullanan static içerik, atomic deploy invalidation’dan yararlanır. Custom cache ID ile opt-out edilmiş object için manual purge gerekebilir.

Kaynaklar

• Caching overview
• Cache API
• Deploy overview
• Functions overview
• Edge Functions optional configuration
• Netlify Edge platform

Sonuç

Netlify CDN cache stratejisinde static ve dynamic response’ları ayırmak temel adımdır. Statik dosyalar deploy sürümüyle güçlü edge caching ve otomatik invalidation alırken, Function, Edge Function ve proxy response’ları güvenlik nedeniyle varsayılan olarak cache’lenmez. Browser, Netlify edge ve durable cache header’larını ayrı yönetin; kişisel içeriği shared cache’e koymayın ve vary boyutlarını gereksiz büyütmeyin. Performansı ilk istek, tekrar, deploy ve purge aşamalarında Cache-Status, body version ve TTFB ile ölçün.

Cache ve edge davranışını kendi demo projenizde ölçmek 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.