Vercel Ortam Değişkenleri Güncellenmiyor mu? Build Zamanı ve Runtime

Vercel panelinde bir değişkeni düzeltiyorsunuz, siteyi yeniliyorsunuz ve eski değer duruyor. Bazen daha kötüsü olur: sunucu logu yeni değeri yazıyor ama tarayıcı hâlâ eski API adresine istek atıyor. İkisinin de arkasında aynı iki gerçek var ve ikisi de hata değil. Bu yazı onları Vercel dokümanı ve node_modules içindeki Next.js 16 dokümanı üzerinden anlatıyor (Kasım 2026 itibarıyla).

Gerçek 1: değişiklik yalnız yeni deployment'lara uygulanır

Vercel dokümanı bunu doğrudan söylüyor: ortam değişkenlerindeki değişiklikler önceki deployment'lara uygulanmaz, yalnız yenilerine uygulanır ve değişen değerin geçerli olması için projeyi yeniden deploy etmeniz gerekir. Deployment bir anlık görüntüdür. Hangi değişkenlerle build edilip çalıştığı oluşturulduğu anda sabitlenir; ayarı sonradan düzenlemek canlıdaki deployment'a dokunmaz.

Çözüm, doğru türde yeni bir deployment üretmek:

• Production değişkenleri bir sonraki Production deployment'a uygulanır. Production dalına commit push edin ya da vercel --prod çalıştırın.
• Preview değişkenleri bir sonraki Preview deployment'a uygulanır: başka bir dala push ya da düz vercel.
• Development değişkenleri yalnız yerelde kullanılır. vercel env pull ile indirilir ve bir .env dosyasına yazılır.

Sık yapılan hata, değişkeni Production için değiştirip eski bir Preview'ı yeniden deploy etmek ya da tersi. Kaydederken hangi ortam kutularının işaretli olduğuna bakın.

Panelden Redeploy en kısa yol. Vercel'in deployment dokümanı, "ortam değişkenlerini değiştirme"yi yeniden deploy etmeniz gereken durumlar arasında sayıyor. Redeploy penceresi mevcut build cache'in kullanılıp kullanılmayacağını da soruyor; build cache'i başka bir yazıda ele aldım.

Gerçek 2: NEXT_PUBLIC_ değerleri JavaScript'in içine gömülür

Redeploy sunucu tarafındaki çoğu durumu çözer. Tarayıcı tarafında ek bir incelik var ve bu Vercel'in değil Next.js'in davranışı. Next.js dokümanına göre NEXT_PUBLIC_ önekli bir değişken build zamanında satır içi yerleştirilir: next build sırasında process.env.NEXT_PUBLIC_... ifadesinin her geçtiği yer değerin kendisiyle değiştirilir ve sonuç istemci paketiyle gider.

// Build öncesi
const api = process.env.NEXT_PUBLIC_API_URL;
 
// Tarayıcıya giden (değer build ortamından alınır)
const api = "https://api.example.com";

Doküman sonucu açıkça yazıyor: build bittikten sonra uygulama bu değişkenlerdeki değişikliklere yanıt vermez; değerler build anındakiyle donar. Örnek olarak ortamlar arasında taşınan bir Docker imajı veriliyor, ama aynı mantık Vercel'de de geçerli. Değer, deployment'ı üreten build'e aittir.

Dolayısıyla NEXT_PUBLIC_ değişikliğinde "sadece yeniden başlat" yoktur. Değişiklikten sonra gerçekten build edilmiş bir deployment gerekir.

Dinamik erişim satır içi yerleştirilmez

Yerleştirme, tam olarak process.env.NEXT_PUBLIC_ADI ifadesi üzerinde yapılan bir metin değişimidir. Next.js dokümanı şu iki biçimin yerleştirilmediği konusunda uyarıyor:

const name = "NEXT_PUBLIC_API_URL";
const a = process.env[name]; // yerleştirilmez
 
const env = process.env;
const b = env.NEXT_PUBLIC_API_URL; // yerleştirilmez

Tarayıcıda bu okumalar undefined döner. getEnv("NEXT_PUBLIC_API_URL") gibi bir yardımcı sunucuda çalışıp istemcide çalışmıyorsa ilk bakılacak yer burası. Değerin kullanıldığı yere tam process.env.NEXT_PUBLIC_API_URL ifadesini yazın.

Sunucu değişkenleri: build zamanı mı, istek zamanı mı?

Önek taşımayan değişken tarayıcıya hiç gitmez, ama ne zaman okunduğu yine de önemli. Next.js dokümanına göre dinamik render sırasında ortam değişkenlerini sunucuda istek anında okuyabilirsiniz. Örnekleri, process.env okumadan önce next/server içinden connection() çağırıyor; böylece değer istek geldiğinde değerlendiriliyor:

import { connection } from "next/server";
 
export default async function Page() {
  await connection();
  const flag = process.env.FEATURE_FLAG;
  return <p>Flag: {flag}</p>;
}

Doküman, cookie, header gibi istek zamanı API'lerinin de rotayı aynı şekilde dinamik render'a aldığını belirtiyor. Build sırasında statik üretilen sayfa farklıdır: build'de process.env'den ne okuduysa üretilen çıktının parçasıdır. Statik üretilen sayfaları ve NEXT_PUBLIC_ değerlerini build zamanı, dinamik rotalardaki istek anı okumalarını runtime sayın.

Runtime okumalar bile yalnız çalıştıkları deployment'ın değişkenlerini görür. Dinamik render Gerçek 1'i değiştirmez; sunucu değişkenini düzenledikten sonra yine yeniden deploy edersiniz.

Tarayıcının rebuild olmadan değiştirebileceği bir değer istiyorsanız, Next.js dokümanı runtime değeri istemciye (istek üzerine ya da başlangıçta) ileten kendi API'nizi kurmanızı öneriyor. Ayarı döndüren küçük bir route handler yeter; yalnız açığa çıkarması güvenli değerler döndürmeli.

Kontrol edilecek diğer şeyler

Bunlar Vercel dokümanından ve hızlıca elenebilir:

• Boyut. Node.js, Python, Ruby ve Go çalışma zamanlarında değişkenler deployment başına toplam 64 KB olabilir ve tek bir değişken bunu aşamaz. edge çalışma zamanındaki fonksiyon ve Middleware'de değişken başına sınır 5 KB. Büyük bir sertifika ya da JWT'de buna takılınır.
• Dal geçersiz kılmaları. Preview için bir değişken belirli bir Git dalıyla sınırlanabilir. Dala özel değişken, aynı adlı genel Preview değişkenini geçersiz kılar; yani o dal az önce düzenlediğinizden farklı bir değer kullanıyor olabilir.
• Yerel dosyalar. Next.js değişkenleri şu sırayla arar: process.env, sonra .env.$(NODE_ENV).local, .env.local, .env.$(NODE_ENV), .env. .env.local içindeki eski bir değer çektiğinizi gölgeleyebilir. src klasörü varsa .env dosyaları yine proje kökünde durur, src içinde değil.
• Nerede değiştirdiğiniz. Değişkenler proje ya da ekip düzeyinde tanımlanabilir. Projenin gerçekten kullandığını düzenlediğinizden emin olun.

Kısa hata ayıklama sırası

1. Baktığınız sayfa değişiklikten sonra oluşturulmuş bir deployment'tan mı? Panel ayarına değil, deployment'ın oluşturulma zamanına bakın.
2. Doğru ortam mı: Production, Preview ya da Development?
3. Değişken NEXT_PUBLIC_ mi? Öyleyse yalnız yeni bir build işe yarar ve her kullanım birebir process.env.NEXT_PUBLIC_ADI olmalı.
4. Sunucu değişkeniyse kod istek anında mı çalışıyor, yoksa sayfa üretilirken mi değerlendirildi?
5. Dal geçersiz kılması, .env.local dosyası ya da ekip düzeyi bir değişken farklı bir değer mi veriyor?

Özet

Vercel ortam değişkenlerini deployment başına dondurur, bu yüzden her değişiklik yeni bir deployment ister. Üstüne NEXT_PUBLIC_ değişkenleri build sırasında JavaScript'e yazılır; onları yalnız yeniden build edilmiş deployment değiştirir ve birebir ifade olarak yazılmaları gerekir. Dinamik render edilen sunucu kodundaki okumalar, kendi deployment'larının değerini istek anında görür. Her değere "hangi build'e ve hangi deployment'a ait" diye bakınca bayat değişken şikayetlerinin çoğu kendiliğinden açıklanır.