Browser Cache Nasıl Yapılandırılır? CDN ve Sunucu Adımları

Browser cache (tarayıcı önbelleği), bir sitenin sayfa yükleme hızını doğrudan etkileyen en pratik performans başlıklarından biridir. Doğru yapılandırıldığında kullanıcı tekrar ziyaretlerde CSS/JS görsellerini yeniden indirmez; yanlış yapılandırıldığında ise güncellemeler gecikir, eski dosyalar görünür ve “sitede eski sürüm var” şikâyetleri artar. Bu rehberde; cache politikasını Cache-Control, ETag, varyantlar (Vary) ve dosya sürümleme yaklaşımıyla net şekilde nasıl kurgulayacağınızı adım adım anlatıyorum.

1) Browser cache’te hedef: hız + güncelleme doğruluğu

Öncelik, iki hedefi birlikte tutturmaktır: - Hız: Statik kaynaklar (CSS, JS, görsel, font) tarayıcıda uzun süre kalır. - Doğruluk: Uygulama güncellenince tarayıcı eski dosyaları servis etmez.

Bunu sağlamanın teknik anahtarı şudur: - Statik dosyaları sürümlü (hashed) isimle: Örn. app.9f3a2c1.js veya style.2026-08-30.css. - Sunucudan bu dosyalara uzun ömürlü cache ver, ama dosya adı değişince cache otomatik “yenilenmiş” olur. - HTML gibi dinamik dosyalarda ise kısa ömür uygula.

Bu yaklaşım, NetKıyas’ta sık görülen bir sorunu da bitirir: “Yeni deploy sonrası bazı kullanıcılar eski JavaScript’i çekiyor.” Bunun nedeni çoğunlukla dosya isimleri değişmeden uzun cache verilmesidir.

Statik vs dinamik kaynak ayrımı

Aşağıdaki ayrım pratikte en doğru başlangıçtır: - Statik: /assets/, /static/, /images/, fontlar, build çıktıları (bundle) → uzun cache - Dinamik: / (ana sayfa), /login, /api/*, kategori/sayfa endpoint’leri → kısa cache

2) Cache-Control başlığını net kural setiyle ayarlayın

Tarayıcı önbelleğini yöneten temel HTTP başlığı Cache-Control’dır. En sık kullanılan direktifler: - max-age=SECONDS: Cache’in tarayıcıda kaç saniye kalacağını belirler. - public: Hem tarayıcı hem ara sunucu (CDN/proxy) cache’leyebilir. - private: Sadece tarayıcı cache’ler. - no-store: Cache kesinlikle saklanmaz (özellikle kişisel içerik). - must-revalidate: Cache süresi dolunca yeniden doğrula. - s-maxage=SECONDS: CDN için ayrı ömür.

Önerilen pratik politika (örnek)

Aşağıdaki değerler; tipik bir web uygulaması için başlangıç kabul edilebilir bir politika setidir: - HTML (sayfalar): Cache-Control: no-cache, must-revalidate - CSS/JS (hashed): Cache-Control: public, max-age=31536000, immutable - Görsel/font: Cache-Control: public, max-age=31536000, immutable - API yanıtları (kullanıcıya özel değilse): Cache-Control: public, max-age=60 (ihtiyaca göre) - Kullanıcıya özel içerik: Cache-Control: private, no-cache, must-revalidate

immutable direktifi, dosya adı değişmediği sürece kaynağın değişmeyeceğini söyler. Bu yüzden sadece hashed isim ile kullanın.

Cache-Control örnekleri (mantık olarak)

Statik dosya: public, max-age=31536000, immutable
HTML: no-cache, must-revalidate
Özel içerik: private, no-cache, must-revalidate

3) ETag ve 304 doğrulaması: ne zaman kullanılır?

Browser cache’in ikinci ayağı ETag’dir. Sunucu, bir kaynağın değişip değişmediğini tarayıcıya If-None-Match ile sorarak kontrol edebilir. Tarayıcı aynı dosyayı doğrulama isteğinde bulunur; değişmediyse sunucu 304 Not Modified döner ve veri indirme minimuma iner.

Net karar kuralı: - Uzun cache (immutable) verdiğiniz hashed dosyalarda genellikle ETAG gerekmez; zaten isim değişmeden içerik değişmez varsayılır. - Kısa cache / no-cache verdiğiniz dinamik içerikte ise ETAG doğrulaması performans sağlar.

ETag yanlış kullanılırsa sorunlar çıkarabilir: - Kaynak sık değişiyorsa ETAG üretimi maliyetli olabilir. - Varyant (Content-Encoding) veya dil/cihaz bazlı farklılıklar yönetilmezse tarayıcı yanlış şeyi cache’leyebilir.

Bu yüzden ETAG kullanıyorsanız bir sonraki bölümdeki Vary yaklaşımı kritiktir.

4) Vary başlığı: CDN ve tarayıcı varyantlarını doğru yönetin

Bir kaynağın farklı varyantları olabilir: - Accept-Encoding (gzip/brotli) - Dil Accept-Language - Versiyonlama User-Agent (kaçınmak genelde daha iyidir)

HTTP’de Vary başlığı, cache’in hangi istek özelliklerine göre ayrıştırıldığını belirler. Vary doğru değilse CDN/tarayıcı tek bir cevabı farklı durumlarda yanlış kullanabilir.

Net öneri: - Sunucunuz otomatik sıkıştırma (gzip/brotli) uyguluyorsa en azından Vary: Accept-Encoding olmalıdır. - Dil bazlı içerik üretiyorsanız Vary: Accept-Language gerekir. - Mümkünse içerikleri cihaz bazlı üretmeyin; cihaz/UA bağımlılığı cache isabetini düşürür.

5) Apache / Nginx / CDN tarafında uygulanacak net örnekler

Aşağıda amaç, politika mantığını kurmak; ancak sunucu yapılandırmanızın dosya yolu, framework yapısı ve CDN varlığı farklı olabilir. Bu nedenle “mantık” aynı kalır: HTML kısa, hashed statikler uzun.

5.1 Nginx: dosya uzantısı ve klasöre göre uzun cache

Örnek mantık: - /assets/ ve .css/.js/.png/.jpg/.svg/.woff2 için uzun ömür - HTML için no-cache / kısa doğrulama

server bloğunuzda benzer bir yapı kullanabilirsiniz:

location ~* \.\d+\.(css|js)$ {
  add_header Cache-Control "public, max-age=31536000, immutable" always;
}

location /assets/ {
  try_files $uri =404;
  add_header Cache-Control "public, max-age=31536000, immutable" always;
}

location ~* \.(png|jpe?g|gif|svg|webp|woff2?)$ {
  add_header Cache-Control "public, max-age=31536000, immutable" always;
}

location / {
  add_header Cache-Control "no-cache, must-revalidate" always;
}

Not: Eğer hashed isim kullanmıyorsanız immutable vermeyin. Ayrıca dosya uzantılarına göre politikayı uygulamak, framework’ünüzün ürettiği dosya pattern’lerini net bilmenizi gerektirir.

5.2 Apache: mod_headers ile dosya türlerine göre politika

Apache tarafında benzer mantık mod_headers ile yapılır. Örnek mantık: - FilesMatch ile uzantıya göre - Header set/Header always set ile davranış

<IfModule mod_headers.c>
  <FilesMatch "\\.(css|js)$">
    Header set Cache-Control "public, max-age=31536000, immutable"
  </FilesMatch>

  <FilesMatch "\\.(html)$">
    Header set Cache-Control "no-cache, must-revalidate"
  </FilesMatch>
</IfModule>

Yine: Bu örnekte tüm .css/.js için uzun cache verilir; ancak sürümlü (hashed) dosya ismi kullanılmıyorsa güncelleme gecikebilir. En doğrusu, statik klasör (örn. /assets/) veya hashed pattern üzerinden ayırmaktır.

5.3 CDN kullanıyorsanız: s-maxage ile tarayıcıdan bağımsız kontrol

CDN’de s-maxage kullanarak CDN’deki ömrü tarayıcıdan bağımsız ayarlarsınız. Örnek politika mantığı: - CDN: s-maxage=3600 - Tarayıcı: max-age=31536000

Bu, CDN’in “yanlış/eskimiş” içerikle uzun süre kilitlenmesini azaltır.

Örnek: - Cache-Control: public, max-age=31536000, immutable, s-maxage=3600

5.4 CMS/Framework senaryoları: üretim çıktısı pattern’i

WordPress, Laravel, Next.js, React (bundler) gibi sistemlerde static dosyalar genellikle bir build pipeline’ı ile assets altında oluşur. Bu durumda yapılandırmayı şu mantıkla yapın: - Build çıktısı klasörü → immutable - HTML ve rota endpoint’leri → kısa doğrulama

6) En sık yapılan hatalar ve net düzeltmeler

Aşağıdaki hatalar, browser cache yapılandırmalarında en sık görülen sorunlardır:

Hata 1: hashed dosya kullanmadan uzun cache + immutable

Belirti: Deploy sonrası bazı kullanıcılar eski JS/CSS görür. Net düzeltme: - Dosya adını build aşamasında hash’leyin. - immutable yalnızca hash’li dosyalara verin.

Hata 2: HTML’de uzun max-age vermek

Belirti: Menü/ürün listeleri güncellenmez. Net düzeltme: - HTML: no-cache, must-revalidate veya max-age=0, must-revalidate.

Hata 3: Vary eksikliği (Accept-Encoding)

Belirti: Bazı kullanıcılar görsellerin veya sıkıştırılmış içeriklerin bozuk görünmesi gibi tuhaf durumlar raporlar. Net düzeltme: - Sıkıştırma kullanıyorsanız Vary: Accept-Encoding ekleyin.

Hata 4: CDN cache purging beklentisiyle yanlış politika

Belirti: CDN temizlense bile tarayıcı eski sürümü kullanmaya devam eder. Net düzeltme: - Tarayıcı tarafı için hashed isim + uzun cache. - HTML için kısa cache.

7) Doğru kurduğunuzu nasıl doğrularsınız? (kontrol listesi)

Yapılandırmayı körlemesine yapmak yerine, net doğrulama adımları uygulayın.

7.1 Header kontrolü

Her kaynak tipi için tarayıcı devtools (Network) veya curl ile yanıt başlıklarını inceleyin: - Statik dosya yanıtında Cache-Control gerçekten max-age=31536000 ve mümkünse immutable içeriyor mu? - HTML için no-cache var mı?

Örnek curl: - Cache-Control ve ETag değerlerini kontrol edin.

7.2 304 doğrulama testi

Dinamik içerikler için tarayıcı “yeniden indirmeden doğrulama” yapmalıdır. Uygulama mantığınıza uygun olarak: - Aynı sayfayı tekrar yüklediğinizde tarayıcı bazı isteklere 304 Not Modified döndürüyor mu?

7.3 Deploy sonrası güncellenmiş sürüm testi

Net test adımı: 1. Hash’li statik dosyaların dosya adları değişiyor mu? (ör. app.<hash>.js) 2. Deploy sonrası temiz bir tarayıcı profili (veya hard refresh) ile doğru sürüm yükleniyor mu? 3. Ön belleği açık tutarak (normal yenileme) doğru güncelleme geliyor mu? (özellikle HTML ve rotalar)

8) Hız artışı beklerken “ne kadar” sorusunu sayıya çevirin

Cache politikasını kurduktan sonra asıl ölçüm şudur: ilk yükleme ve tekrar yükleme farkı.

Aşağıdaki tablo, karar vermeyi kolaylaştırmak için pratik beklenen sonuç mantığını özetler:

Kaynak tipi	Önerilen cache	Tekrar ziyarette etkisi	Tipik risk
HTML	`no-cache, must-revalidate`	Orta düzey	Güncelleme gecikmesi (uzun cache verirsen)
Hashed CSS/JS	`public, max-age=31536000, immutable`	Yüksek	Hash kullanılmazsa eski sürüm
Görseller/font	`public, max-age=31536000, immutable`	Yüksek	Dosya adı sabit kalırsa güncelleme
API	İhtiyaca göre (`max-age` kısa)	Değişken	Kişisel veri cache (private/no-store)

Sonuç: Aksiyon planı

Net bir sonuç için bugün şu sırayla ilerleyin: (1) Statik build çıktısı klasörünü netleştirin ve hash’li dosya kullandığınızdan emin olun, (2) HTML’e kısa doğrulama (no-cache, must-revalidate) verin, (3) statik dosyalara uzun ömür (max-age=31536000, immutable) tanımlayın, (4) CDN varsa s-maxage ile CDN davranışını tarayıcıdan bağımsız ayarlayın, (5) Network ekranında header’ları ve deploy sonrası sürüm doğrulamasını yapın. Bu beş adımı tamamladığınızda browser cache hem hız kazandırır hem de güncelleme hatalarını belirgin şekilde azaltır.