Pages

Pages nedir?

Cloudflare Pages, Git deposuna bağlanan bir barındırma platformudur. Bir branch’e push ettiğinde Cloudflare projeyi derler, çıkan dosyaları ağına dağıtır ve sana bir *.pages.dev adresi verir. Her branch için ayrı bir preview adresi üretir, ve istersen sunucu tarafı kod da çalıştırabilirsin (Pages Functions).

Ancak bu sayfanın en önemli bilgisi ürünün ne yaptığı değil, Cloudflare’in bu ürün hakkında ne dediğidir.

Bu portalın Pages sayfasının var olma sebebi de bu: Türkçe kaynakların çoğu hâlâ Pages’i yeni projeler için öneriyor. 2026’da bu tavsiye güncel değil.

Nasıl çalışır?

Build hattı

Üç ayar belirlersin: build komutu, çıktı dizini ve gerekirse monorepo için kök dizin. Cloudflare bu komutu çalıştırır ve çıkış koduna bakar.

Kritik davranış: Pages bir build’in başarılı olup olmadığını yalnızca çıkış kodundan anlar. Resmî ifade: “An exit code of 0 will cause the Pages build to be marked as successful and assets will be uploaded regardless of if error logs are written to standard error.” Yani stderr’e hata yazan ama 0 dönen bir build başarılı sayılır ve eksik içerik yayına çıkar.

Build sırasında şu değişkenler otomatik tanımlanır:

Build adımı olmayan projelerde build komutu olarak exit 0 yazılır.

Preview deployment’lar

Production dışındaki her branch iki adres alır: kalıcı bir hash adresi (<hash>.<proje>.pages.dev) ve bir branch takma adı (<branch>.<proje>.pages.dev).

Branch adları normalleştirilir: fix/api branch’i fix-api.<proje>.pages.dev olur. Hash adresleri kalıcıdır — “These are atomic and may always be visited in the future.”

Pull request’lerde preview otomatik oluşur, ama yalnızca deponun kendisinden gelen branch’lerde. Fork’tan gelen PR’larda preview üretilmez.

İstekler nasıl karşılanır

Pages’in yönlendirme sırası, Workers’ın tam tersidir ve geçiş yapanların en sık düştüğü tuzak budur:

Diğer davranışlar: .html uzantılı dosyalar uzantısız adreslerine yönlendirilir, 404 çözümlemesi dizin ağacında yukarı doğru en yakın 404.html’i arar, ve üst düzeyde 404.html yoksa Pages projeyi tek sayfa uygulaması varsayar. Statik dosyalar otomatik olarak Tiered Cache üzerinden sunulur.

Pages Functions aslında Workers’tır

Resmî ifade: “All Pages Functions are billed as Workers. All pricing and inclusions in this document apply to Pages Functions.” Functions dosya tabanlı yönlendirme kullanır: /functions/helloworld.js → site.com/helloworld, [user].js tek segment, [[user]].js herhangi bir derinlik.

Ne zaman kullanılır, ne zaman kullanılmaz

Pages’i seçmek için kalan iki geçerli sebep

1. Alan adının nameserver’ları Cloudflare’de değil. Resmî ifade: “Unlike Pages, Workers does not support any domain whose nameservers are not managed by Cloudflare.” Yalnızca CNAME ekleyebiliyorsanız Workers bir seçenek değil.
2. Production ve preview için farklı binding’ler gerekiyor. Resmî ifade: “Unlike Pages, Workers does not natively support defining different bindings in production vs. non-production builds.” Workers tarafında geçici çözüm Wrangler Environments.

Pages’te olmayan, Workers’ta olan şeyler

Diğer sınırlar

• Hesap başına 100 proje. Resmî not: “This limit is not routinely increased.”
• Advanced Certificates çalışmaz — resmî bilinen sorun.
• Wildcard custom domain (*.alanadi.com) desteklenmiyor.
• Cloudflare Load Balancer *.pages.dev ile çalışmıyor; Error 1000: DNS points to prohibited IP verir.
• Incremental build yok.
• Git bağlantılı proje sonradan Direct Upload’a çevrilemez.

Somut örnekler

1. Güvenlik başlıkları — _headers

Build çıktı dizinine, uzantısız _headers dosyası:

# Yorum satırı
/secure/page
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Referrer-Policy: no-referrer

/static/*
  Access-Control-Allow-Origin: *
  X-Robots-Tag: nosnippet

# Preview adreslerini arama motorlarından gizle
https://myproject.pages.dev/*
  X-Robots-Tag: noindex

Miras alınan bir başlığı kaldırmak için ! öneki:

/*
  Content-Security-Policy: default-src 'self';

/*.jpg
  ! Content-Security-Policy

Sınırlar: en fazla 100 kural, satır başına 2.000 karakter. Birden fazla kural eşleşirse başlıklar birleşir; aynı başlık iki kez tanımlanırsa değerler virgülle birleştirilir.

2. Eski URL’leri taşıma — _redirects

/home301           /                          301
/eski-blog/*       https://blog.alanadi.com/:splat
/urunler/:kod/:ad  /urunler?kod=:kod&ad=:ad
/twitch            https://twitch.tv

Varsayılan kod 302. Kritik kurallar:

• “The order of your redirects matter. If there are multiple redirects for the same source path, the top-most redirect is applied.”
• “Static redirects should appear before dynamic redirects.”
• “Redirects are always followed, regardless of whether or not an asset matches the incoming request.”

Sınırlar: 2.000 statik + 100 dinamik = toplam 2.100 kural, kural başına 1.000 karakter. Desteklenmeyen: sorgu parametresine göre eşleşme, ülke/dil bazlı yönlendirme, çerez bazlı yönlendirme.

3. Fatura kontrolü — _routes.json

Bu dosya Pages’te en çok para kazandıran (ve yokluğunda en çok para kaybettiren) ayardır.

{
  "version": 1,
  "include": ["/api/*"],
  "exclude": ["/build/*", "/assets/*"]
}

Resmî gerekçe: “On a purely static project, Pages offers unlimited free requests. However, once you add Functions on a Pages project, all requests by default will invoke your Function. To continue receiving unlimited free static requests, exclude your project’s static routes.”

exclude her zaman include’dan önceliklidir. En az bir include kuralı zorunlu; toplam en fazla 100 kural, kural başına 100 karakter.

4. Basit bir Function

Dosya proje kökündeki /functions dizinine konur — build çıktısının içine değil.

// functions/api/saat.js  →  site.com/api/saat
export function onRequest(context) {
  return Response.json({
    saat: new Date().toISOString(),
    ulke: context.request.cf?.country ?? null,
  });
}

onRequest bir Response veya Promise<Response> döndürmek zorundadır.

Demo 1: Git bağlantılı site yayına alma

Bu demoyu birlikte yapacağız. Hedef: bir statik siteyi Git üzerinden yayına almak, preview branch ve rollback davranışını görmek.

npm create cloudflare@latest -- --platform=pages

pnpm create cloudflare@latest --platform=pages

yarn create cloudflare --platform=pages

Adım 1 — Depoyu bağla

Panel → Workers & Pages → Create application → Pages → Connect to Git.

Adım 2 — Build ayarları

Adım 3 — İlk deploy

Adım 4 — Preview branch

git checkout -b gelistirme
git commit --allow-empty -m "preview testi"
git push -u origin gelistirme

Adım 5 — Rollback

Demo 2: Aynı projeyi Workers’a taşıma

Bu ikinci demo, sayfanın ana tezini uygulamalı gösterir: aynı site Workers üzerinde nasıl duruyor?

Adım 1 — Yapılandırmayı çevir

wrangler.jsonc:

{
  "name": "sitem",
  "compatibility_date": "2026-08-31",
  "assets": {
    "directory": "./dist",
    "not_found_handling": "404-page"
  }
}

Karşılıklar:

Adım 2 — Çalıştır ve karşılaştır

npx wrangler dev      # http://localhost:8787
npx wrangler deploy

Adım 3 — Workers Builds ile CI/CD

Ölçüm: öncesi ve sonrası

Demo tamamlandığında bu tablo gerçek değerlerle doldurulacak.

Fiyatlandırma

Aşağıdaki rakamlar 31 Ağustos 2026’da resmî kaynaklardan doğrulanmıştır.

Statik içerik

Resmî ifade: “On both free and paid plans, requests to static assets are free and unlimited.” Egress ve bant genişliği ücreti de yoktur.

Functions

Pages Functions birebir Workers gibi ücretlendirilir:

Ücretli plan tabanı: “a minimum charge of $5 USD per month for an account.” Ücretsiz planda Workers ve Pages Functions aynı günlük kotayı paylaşır — 50.000 Function + 50.000 Worker isteği toplam 100.000’i doldurur. Kota her gün UTC gece yarısı sıfırlanır.

Build kotaları

Diğer sınırlar

Lisanslama ve hukuki çerçeve

Pages tescilli bir hizmettir; kullanımı Cloudflare Hizmet Şartları ile düzenlenir. Yüklediğin içeriğin ve kodun mülkiyeti sende kalır.

Build ortamı Cloudflare’in altyapısında çalışır; build sırasında kullandığın gizli değişkenler (API anahtarları vb.) Cloudflare’in ortam değişkeni deposunda saklanır. Kurumsal kullanımda ilgili belgeler Veri İşleme Ek Sözleşmesi ve alt işleyici listesidir.

Statik içerik dünya genelindeki tüm Cloudflare noktalarına dağıtılır. İçeriğin belirli bir coğrafyada kalması gerekiyorsa Pages uygun bir seçenek değildir; Data Localization Suite Pages’i kapsamaz.

Sık yapılan hatalar

_routes.json yazmamak. Tek bir Function eklediğiniz anda tüm statik istekler de faturalanmaya başlar. Pages’te en pahalı ihmal budur.

/functions klasörünü build çıktısının içine koymak. Resmî uyarı: “Make sure that the /functions directory is at the root of your Pages project (and not in the static root, such as /dist).” Yanlış yerdeyse Functions sessizce çalışmaz.

_headers ve _redirects’in Functions yanıtlarına da uygulandığını sanmak. Uygulanmaz. SSR kullanıyorsanız başlıkları kod içinde set edin.

Build’in “başarılı” görünüp eksik deploy edilmesi. Çıkış kodu 0 dönen bir build, stderr’e hata yazsa bile başarılı sayılır. Build komutunuzun hata durumunda gerçekten sıfırdan farklı kod döndürdüğünden emin olun.

Node sürümünü ayarlamamak. Varsayılan hâlâ eski bir sürüm; NODE_VERSION ortam değişkenini tanımlayın. Aynı şey Hugo için HUGO_VERSION ile geçerli.

Panelde eklemeden elle CNAME kaydı açmak. Önce panelden custom domain eklenmeli; tersi sırada 522 hatası alırsınız. Bu resmî bir bilinen sorundur.

Custom domain’e Cache Rule eklemek. Deploy sonrası eski içerik servis edilir.

25 MiB üstü dosya yüklemeye çalışmak. Sınır serttir; resmî çözüm dosyayı R2 public bucket’ta barındırmaktır.