Vercel Cron Job Next.js Kurulumu ve Limitler

Modern web geliştirmede sunucusuz (serverless) mimarilerin yaygınlaşması, geleneksel sunucu yönetimini ve klasik Linux crontab alışkanlıklarını kökten dönüştürdü. Next.js projelerini barındırmak için sektör standardı haline gelen Vercel platformu, arka planda sürekli çalışan sanal makineler yerine isteğe bağlı tetiklenen Serverless ve Edge fonksiyonları sunar. Ancak e-posta bültenlerinin gönderimi, veritabanı senkronizasyonu, süresi dolmuş oturumların tasfiyesi veya site haritasının yenilenmesi gibi rutin arka plan operasyonları için periyodik tetikleme ihtiyacı devam eder.

Vercel Cron Jobs özelliği, projelerinizin kök dizininde yer alan bir yapılandırma dosyası üzerinden Serverless Function uç noktalarınızı belirli zaman aralıklarıyla otomatik olarak çağırmanızı sağlar. Bu yapı, geliştiricileri bağımsız bir VPS kiralamaktan veya sunucu içinde crontab komutları yapılandırmaktan kurtarır. Klasik sistemlerin işleyişini incelemek için cron job nedir rehberimizi ziyaret edebilirsiniz. Bununla birlikte Vercel Cron mimarisinin kendine has saat dilimi kuralları, güvenlik mekanizmaları ve özellikle ücretsiz Hobby planında günde bir çalıştırma ile sınırlı katı kuralları bulunmaktadır.

Bu rehberde, Next.js App Router üzerinde güvenli bir cron route handler oluşturmayı, vercel.json dosyasını doğru sözdizimiyle yapılandırmayı, UTC ve Türkiye saati arasındaki zaman farkını yönetmeyi, yetkisiz erişimleri önleyen CRON_SECRET doğrulamasını ve karşılaşılan yaygın hata çözümlerini inceleyeceğiz. Ayrıca Vercel plan limitlerini aşmadan sık aralıklarla iş yürütmek isteyenler için harici HTTP zamanlayıcı mimarisini adım adım ele alacağız.

Vercel Cron Çalışma Modeli ve Serverless Mimarisi

Vercel Cron Jobs, sunucuda sürekli bellekte bekleyen bir arka plan servisi (daemon) değildir. Vercel altyapısı, dağıtık bir zamanlayıcı havuzu üzerinden projenizin canlı (production) ortamındaki ilgili URL adresine zamanı geldiğinde standart bir HTTP GET isteği gönderir. Bu istek, hedef API rotasını ayağa kaldırır, fonksiyon kodunu çalıştırır ve dönen HTTP yanıtının ardından fonksiyon ortamı dondurularak sonlandırılır.

Bu çalışma modelinin geliştiricilere sunduğu belirgin avantajlar ve dikkat edilmesi gereken dinamikler şunlardır:

1. Sıfır Sunucu Yönetimi: İşletim sistemi güncellemeleri, bellek sızıntıları veya sistem düzeyinde crond servisinin çökmesi gibi riskler tamamen ortadan kalkar. Fonksiyonlar yalnızca çalıştıkları süre boyunca kaynak tüketir.
2. Yalnızca Canlı Ortamda Tetikleme: Vercel Cron Jobs mekanizması güvenlik ve kaynak tasarrufu gerekçesiyle yalnızca Production dalına (varsayılan olarak main veya master) yapılan canlı dağıtımlarda devreye girer. Önizleme (Preview) veya yerel geliştirme (Localhost) ortamlarında otomatik cron tetiklenmez.
3. Fonksiyon Süre Sınırları (Execution Timeout): Tetiklenen uç nokta normal bir Serverless Function olduğundan, projenizin bulunduğu planın çalışma süresi sınırlarına tabidir. Fluid Compute etkin Node.js fonksiyonlarında Hobby için varsayılan ve azami süre 300 saniyedir; Pro için varsayılan 300, genel azami süre 800 saniyedir. Süreyi aşan işlemler platform tarafından anında kesilir.

Next.js App Router ile Cron Endpoint Hazırlama

Next.js 13 ve sonraki sürümlerde gelen App Router yapısında, cron görevlerini karşılamak için Route Handler dosyaları kullanılır. Vercel Cron istekleri doğrudan HTTP GET metodu ile geldiğinden, hazırlayacağınız uç noktada GET fonksiyonunu dışa aktarmanız gerekir.

Aşağıdaki örnekte, veritabanında süresi dolmuş geçici kayıtları temizleyen ve gelen isteğin Vercel tarafından gönderildiğini doğrulayan tam teşekküllü bir Route Handler yer almaktadır. Dosyayı projenizde app/api/cron/cleanup/route.ts yolunda oluşturun:

import { NextRequest, NextResponse } from 'next/server';

export async function GET(request: NextRequest) {
  // Gelen Authorization basligini al
  const authHeader = request.headers.get('authorization');
  const cronSecret = process.env.CRON_SECRET;

  // Guvenlik kontrolu: Yetkisiz erisimleri engelle
  if (!cronSecret || authHeader !== `Bearer ${cronSecret}`) {
    return NextResponse.json(
      { error: 'Yetkisiz erisim: Gecersiz cron anahtari' },
      { status: 401 }
    );
  }

  try {
    const baslangic = Date.now();

    // Periyodik olarak calistirilacak is mantigi
    // Ornek: Veritabani temizligi veya senkronizasyon islemi
    console.log('[CRON] Gunluk temizlik gorevi baslatildi.');

    // Simule edilen islem suresi
    const temizlenenKayitSayisi = 42;

    const gecenSure = Date.now() - baslangic;

    return NextResponse.json({
      success: true,
      message: 'Gorev basariyla tamamlandi',
      temizlenenKayitSayisi,
      sureMs: gecenSure,
    });
  } catch (error) {
    console.error('[CRON HATA] Islem sirasinda hata olustu:', error);
    return NextResponse.json(
      { error: 'Sunucu ici hata olustu' },
      { status: 500 }
    );
  }
}

Eğer geleneksel Pages Router kullanıyorsanız, benzer mantığı pages/api/cron/cleanup.ts dosyası içerisinde standart bir API işleyicisi (handler) olarak yazabilir ve req.method === 'GET' kontrolü ekleyebilirsiniz. Node.js çalışma ortamının ayrıntılarını öğrenmek için Node.js cron job kılavuzumuza başvurabilirsiniz.

vercel.json Yapılandırması ve Sözdizimi

Vercel platformunun hangi uç noktayı hangi periyotla tetikleyeceğini bilmesi için projenizin kök dizininde bir vercel.json yapılandırma dosyası bulunmalıdır. Dosya içerisindeki crons dizisi, her görev için URL yolunu ve cron ifadesini tanımlar.

Aşağıda iki farklı görevi barındıran örnek bir vercel.json dosyası yer almaktadır:

{
  "crons": [
    {
      "path": "/api/cron/cleanup",
      "schedule": "0 5 * * *"
    },
    {
      "path": "/api/cron/sitemap-refresh",
      "schedule": "30 2 * * 1"
    }
  ]
}

Buradaki yapılandırma parametreleri şu anlamlara gelir:

• path: Canlı alan adınızın arkasına eklenecek mutlak URL yoludur. Başında mutlaka eğik çizgi (/) bulunmalıdır.
• schedule: Standart 5 alanlı cron ifadesidir (dakika, saat, ayın günü, ay, haftanın günü). Karakter kuralları ve zaman dizilimleri hakkında detaylı bilgiye crontab sözdizimi sayfamızdan ulaşabilirsiniz.

UTC ve Türkiye Saati (UTC+3) Zamanlama Farkı

Vercel Cron zamanlayıcısı tamamen UTC (Coordinated Universal Time) saat dilimine göre çalışır. Sistemde yerel saat dilimi seçeneği bulunmaz. Türkiye ise yıl boyunca kalıcı olarak UTC+3 zaman dilimini kullanmaktadır.

Zamanlama yaparken Türkiye saatinden tam 3 saat geriye gitmeniz gerekir. Bu hesaplama yapılmadığında görevleriniz beklediğinizden 3 saat geç veya erken çalışacaktır:

Gece yarısı (00:00 - 02:59) aralığındaki görevlerde gün değişimine dikkat edilmelidir. Örneğin Türkiye saatiyle Salı gecesi 01:00'de çalışması gereken bir görev, UTC olarak Pazartesi günü saat 22:00'ye denk gelir (0 22 * * 1).

CRON_SECRET ile Uç Nokta Güvenliği ve Doğrulama

Vercel projenizde oluşturduğunuz API rotaları varsayılan olarak internete açıktır. Eğer uç noktanızı korumazsanız, kötü niyetli bir kullanıcı veya otomatik web tarayıcıları https://siteniz.com/api/cron/cleanup adresine istek göndererek veritabanı işlemlerinizi tetikleyebilir veya sunucu kaynaklarınızı tüketebilir.

Vercel bu sorunu çözmek için yerleşik bir kimlik doğrulama mekanizması sunar. Bir cron görevi tetiklendiğinde Vercel altyapısı HTTP isteğine otomatik olarak şu başlığı ekler:

Authorization: Bearer <CRON_SECRET_DEGERI>

Uç noktanızı güvenli hale getirmek için şu adımları uygulayın:

1. Terminalinizde güçlü ve tahmin edilemez rastgele bir anahtar üretin:

   openssl rand -hex 32

2. Vercel Dashboard'a gidin. Projenizi seçip Settings > Environment Variables bölümünü açın.
3. Değişken adı olarak CRON_SECRET, değer olarak ürettiğiniz anahtarı girin. Ortam olarak Production seçeneğini işaretleyip kaydedin.
4. Uygulamanızın canlı dağıtımını yeniden tetikleyin (Redeploy). Route handler kodunuz artık yalnızca bu gizli anahtarı taşıyan isteklere 200 OK yanıtı verecek, diğer tüm çağrıları 401 Unauthorized ile reddedecektir.

Hobby ve Pro Plan Limitleri Karşılaştırması

Vercel Cron Jobs kullanırken projenizin abonelik planı en kritik belirleyicidir. Birçok geliştirici yerel ortamda çalışan cron görevlerinin Vercel'e yüklendiğinde çalışmamasının nedenini plan limitlerinde bulmaktadır.

Hobby planındaki "görev başına günde en fazla bir kez çalıştırma" kısıtlaması, saatlik sipariş senkronizasyonu veya 5 dakikalık stok kontrolü yapmak isteyen projeler için yetersiz kalmaktadır. vercel.json dosyasına */10 * * * * gibi sık aralıklı bir ifade yazıldığında, Vercel dağıtım aşamasında hata vererek işlemi durdurur.

Günde tek bir tetikleme size yetiyorsa ve zamanlamayı da kod deposunda sürmeyi tercih ediyorsanız, GitHub Actions schedule ile depo tabanlı zamanlama ücretsiz bir ara yoldur: cron ifadesi depodaki YAML dosyasında tanımlanır ve UTC olarak yorumlanır, yani Türkiye saati hesabı burada da yapmanız gerekir.

Çalışmayan veya Tekrarlanan Çağrılar İçin Çözümler

Vercel üzerinde cron görevleri koştururken sıkça karşılaşılan dört teknik problem ve bunların kesin çözüm yolları aşağıda listelenmiştir:

1. 401 Unauthorized Hatası ve Eksik Environment Variables

Vercel Cron tetiklendiğinde günlüklerde 401 Unauthorized yanıtı görünüyorsa, Vercel ortam değişkenlerinde CRON_SECRET tanımlanmamış veya tanımlandıktan sonra proje yeniden derlenmemiştir (redeploy). Çözüm olarak Vercel Dashboard üzerinde Environment Variables sekmesini kontrol edin, değişkenin "Production" ortamına açık olduğundan emin olun ve yeni bir dağıtım başlatın.

2. FUNCTION_INVOCATION_TIMEOUT ve 504 Gateway Timeout

Eğer cron göreviniz toplu e-posta gönderimi veya büyük veri setlerini işleme gibi ağır operasyonlar yürütüyorsa, fonksiyonunuz için yapılandırılmış çalışma süresini aşabilir. Fonksiyon süresi aşıldığında Vercel işlemi zorla sonlandırır ve HTTP 504 hatası döner. Çözüm için veritabanı işlemlerini sayfalama (pagination) ile parçalara bölün, işleri asenkron kuyruklara aktarın ya da ağır işleri harici işçilere (worker) devredin. Sistemik sorunları araştırmak için cron job çalışmıyor rehberimizdeki kontrol adımlarını izleyebilirsiniz.

3. Hobby Planında "Crons are limited to once per day" Dağıtım Hatası

Hobby hesabınızda vercel.json dosyasına günde birden fazla çalışacak bir ifade (örneğin 0 * * * * veya */15 * * * *) eklediğinizde dağıtım şu hata ile başarısız olur: Hobby accounts are limited to daily cron jobs. This cron expression would run more than once per day.. Vercel üzerinde ücretli Pro plana geçmek istemiyorsanız, çözümü bir sonraki bölümde anlatılan harici bir zamanlama servisine geçiş yapmaktır.

4. Çift Tetikleme (Duplicate Invocations) ve Ağ Yeniden Denemeleri

Vercel, başarısız cron çağrılarını otomatik olarak yeniden denemez; ancak aynı zamanlanmış çağrı zaman zaman birden fazla kez teslim edilebilir. Eğer route handler fonksiyonunuz idempotent değilse (aynı isteğin iki kez çalışması güvenli değilse), müşterilere iki kez e-posta gidebilir veya mükerrer bakiye kesintisi yaşanabilir. Çözüm olarak veritabanında işlem başlangıcında bir kilit kaydı (lock / idempotency key) oluşturun ve işlemi tamamlanan görevi işaretleyerek mükerrer yürütmeyi engelleyin.

cronjob.com.tr ile Harici HTTP Zamanlayıcı Kurulumu

Vercel Hobby planının günde 1 çalıştırma kısıtını aşmak veya Pro planda dahi Vercel'in karmaşık cron limitlerine takılmadan Türkiye saatiyle esnek yönetim sağlamak için en sağlıklı yöntem harici bir HTTP zamanlayıcı kullanmaktır. Next.js Route Handler uç noktanız zaten internete açık ve CRON_SECRET ile korunduğundan, bu adrese dışarıdan periyodik istek göndermek mimariyi bozmadan zamanlama esnekliği kazandırır; Vercel fonksiyon limitleri geçerliliğini korur.

Ücretsiz cron job servisi cronjob.com.tr üzerinden Next.js uç noktanızı dakikalık veya saatlik periyotlarla tetiklemek için aşağıdaki yapılandırmayı uygulayabilirsiniz:

• Hedef URL: Canlı Next.js uygulamanızın uç noktasını girin (örneğin https://siteniz.com/api/cron/cleanup).
• HTTP Metodu: GET seçeneğini işaretleyin (veya endpoint'inizi POST destekleyecek şekilde tasarladıysanız POST seçin).
• Özel Header: Başlık alanına Authorization: Bearer <CRON_SECRET_DEGERINIZ> satırını ekleyin. Böylece Next.js içindeki güvenlik kontrolü sorunsuz geçer.
• Zamanlama ve Saat Dilimi: Hazır zaman aralıklarından (en az 1 dakika) birini seçebilir ya da 5 alanlı standart cron ifadesi tanımlayabilirsiniz. En büyük kolaylık, saat dilimini doğrudan Europe/Istanbul olarak seçebilmenizdir; böylece UTC hesaplamalarıyla uğraşmanıza gerek kalmaz.
• Yanıt Bekleme Süresi (Timeout): Cron ifadeli görevlerde sistem 290 saniyeye kadar yanıt bekler (1 dakikalık aralıklarda 55 saniye). Uç noktanız HTTP 200–399 arası bir durum kodu döndüğünde istek başarılı kabul edilir.
• İzleme ve E-posta Bildirimi: Next.js fonksiyonunuz veritabanı hatası nedeniyle çökerse veya 500 dönerse, sistem ardışık hata eşiği (varsayılan 3) aşıldığında e-posta ile bildirim gönderir. Sorun çözüldüğünde kesinti süresi raporlanır. Ayrıca son 7 güne ait tüm yanıt süreleri ve ilk 64 KB yanıt gövdeleri panelde loglanır.

Edge tarafında kalmak isteyen projeler için bir başka seçenek Cloudflare Workers cron tetikleyicisi kurulumudur; cron tanımı wrangler.toml dosyasındaki triggers.crons anahtarıyla yapılır ve işletim sistemi katmanı hiç devreye girmez.

Farklı bulut ortamlarında sunucusuz zamanlama stratejilerini kıyaslamak için cron alternatifleri incelememize göz atabilirsiniz.

Sıkça Sorulan Sorular (SSS)

Vercel Cron Job Hobby (ücretsiz) planda günde kaç kez çalıştırılabilir?

Vercel Hobby planında cron görevleri günde en fazla bir kez çalıştırılabilir. Dakikalık veya saatlik zamanlamalar Hobby planında desteklenmez ve dağıtım sırasında hataya yol açar.

Vercel Cron istekleri GET mi yoksa POST mu olarak gönderilir?

Vercel Cron servisi zamanlanmış tetikleme isteklerini varsayılan olarak HTTP GET metodu ile gönderir. Bu nedenle Next.js Route Handler dosyanızda GET fonksiyonunu dışa aktarmanız gerekir.

CRON_SECRET başlığı Vercel tarafından otomatik eklenir mi?

Evet, Vercel Dashboard üzerinde tanımladığınız CRON_SECRET ortam değişkeni, Vercel Cron tetikleyicisi tarafından her çağrıda Authorization: Bearer [CRON_SECRET] başlığı olarak otomatik eklenir.

Vercel Cron Job Preview dağıtımlarında çalışır mı?

Hayır, Vercel Cron görevleri yalnızca Production dalına (genellikle main branch) yapılan canlı dağıtımlarda tetiklenir. Preview veya çekme isteği (PR) ortamlarında cron çalıştırılmaz.

İlgili Rehberler