Ortam değişkenleri (Environment Variables)

Kısaca: Kodun dışında ayarlanan yapılandırma değerleri (API anahtarları, veritabanı URL’leri, sırlar) — örneğin depoya sabit yazılmak yerine Vercel panosunda.

Biraz daha ayrıntılı: Bazı değerler (örneğin veritabanı bağlantı dizeleri) ilgili panoda her zaman yeniden görüntülenebilir; diğerleri (örneğin API anahtarları) oluşturulurken yalnızca bir kez gösterilir ve kaybolursa yeniden üretilmelidir. Vercel’in ayrıca bir “Sensitive” bayrağı vardır: ayarlandığında değer artık kimse tarafından — CLI (vercel env pull) ile veya ekip sahibi tarafından bile — geri alınamaz.

Ayrıntılı

Yerel yapılandırma

Yerelde Next.js’te ortam değişkenleri genellikle bir .env.local dosyasıyla ayarlanır (geleneksel olarak asla işlenmez, .gitignore içinde hariç tutulur — aksi halde sırlar Git geçmişine girer ve dosya sonradan silinse bile bulunabilir kalır, çünkü Git geçmişi varsayılan olarak hiçbir şeyi unutmaz). Next.js birkaç .env* dosyasını otomatik olarak sabit bir öncelik sırasıyla okur (.env.local, .env.development/.env.production’ı geçersiz kılar; bunlar da .env’i geçersiz kılar) — yerel geliştirme değerlerini gerçek üretim değerlerinden, ikisini aynı dosyada karıştırmadan temiz biçimde ayırmak için kullanışlıdır.

NEXT_PUBLIC_ öneki

Next.js’e özgü önemli bir fark: NEXT_PUBLIC_ önekli değişkenler derleme zamanında istemci paketine gömülür ve bu yüzden tarayıcıda herkes tarafından görülebilir (örneğin geliştirici araçlarıyla) — diğer tüm değişkenler yalnızca sunucuda kullanılabilir kalır. Bir sıra yanlışlıkla NEXT_PUBLIC_ öneki vermek onu fiilen herkese açık yapar. Teknik olarak bu, Next.js’in koddaki tüm process.env.NEXT_PUBLIC_* başvurularını derleme zamanında doğrudan gerçek değerle değiştirmesinden kaynaklanır (derleme zamanında dize ikamesi) — bir çalışma zamanı sorgusu DEĞİLDİR; bu yüzden bu değerleri değiştirmek geçerli olmak için her zaman yeni bir derleme gerektirir.

DATABASE_URL=postgresql://...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...  # bilerek herkese açık, istemci tarafı Stripe.js için
STRIPE_SECRET_KEY=sk_live_...                    # sunucuda kalır

Vercel’de ortam ayrımı

Vercel’de değerler ayrıca ortam başına (production/preview/development) ayrı yönetilir — örneğin bir önizleme dağıtımı (preview deploy), kodda hiçbir şeyin ayırt edilmesine gerek kalmadan gerçek üretim veritabanı yerine bir test veritabanıyla çalışabilir. Bu, özellikle yıkıcı test senaryolarında değerlidir: yanlışlıkla test verilerini silen veya değiştiren bir önizleme dağıtımı, ortam ayrımı sıkı biçimde korunduğu sürece gerçek üretim veritabanına asla çarpmaz.

”Sensitive” bayrağı

Vercel’in ayrıca bir “Sensitive” bayrağı vardır: ayarlandığında değer artık kimse tarafından — CLI (vercel env pull) ile veya ekip sahibi tarafından bile — geri alınamaz. Bu bilinçli bir tek yönlü sokaktır: değer çalışma zamanında uygulama tarafından hâlâ kullanılabilir, ancak projeye tam yönetici hakları olsa bile sonradan kimse onu düz metin olarak geri okuyamaz. Pratikte bu şu demektir: hassas bir değeri “Sensitive” olarak ayarlamadan önce başka bir yerde (örneğin bir parola yöneticisinde) güvenle saklanmalıdır — kaybolan hassas bir değer yalnızca özgün sağlayıcıda tamamen yeniden üretilerek kurtarılabilir, Vercel’den tekrar okunarak değil.

Ayrıca bak: Vercel, Bearer belirteci