Ortam Değişkeni (Environment Variable) Nedir?
Kısa tanım
Ortam değişkeni (environment variable), işletim sisteminin çalışan bir sürece verdiği ad-değer çiftidir; uygulama ayarlarını kod içine yazılmış sabitler yerine bu değişkenlerden okur. Veritabanı adresi, API anahtarı, e-posta sunucusu ya da uygulamanın hangi ortamda çalıştığı gibi dağıtımdan dağıtıma değişen ayarlar bu yolla verilir. Böylece aynı kod geliştirme, staging ve canlı ortamda değiştirilmeden çalışır ve gizli bilgiler kaynak koda girmez.
Diğer adları: environment variable, env değişkeni, env var, .env dosyası, process.env
Kod ile yapılandırmayı ayırmak
Aynı uygulama geliştiricinin bilgisayarında yerel bir veritabanına, staging ortamında test veritabanına, canlıda ise asıl veritabanına bağlanır. Bu adresleri koda yazmak, her ortam için ayrı bir kod sürümü demektir. Twelve-Factor App yaklaşımı bu yüzden dağıtımlar arasında değişen her ayarın ortam değişkenlerinde tutulmasını önerir ve basit bir test önerir: kod tabanı şu anda açık kaynak yapılsa, herhangi bir kimlik bilgisi açığa çıkar mıydı?
Her ayar ortam değişkeni olmak zorunda değildir. Sayfa yönlendirme kuralları veya iş mantığı gibi ortamdan ortama değişmeyen yapılar kodda kalır; ortam değişkenleri yalnızca dağıtıma özgü değerler içindir.
Tanımlamak ve okumak
Değişkenler kabukta, servis tanımında (systemd, Docker veya Docker Compose), barındırma panelinde ya da CI/CD sisteminin gizli değişken ayarlarında tanımlanabilir. Geliştirme sırasında genellikle bir .env dosyası kullanılır:
# .env (repository'ye eklenmez)
DATABASE_URL=postgres://uygulama:***@localhost:5432/magaza
SMTP_HOST=smtp.example.com
APP_ENV=development// server.js
const dbUrl = process.env.DATABASE_URL;
if (!dbUrl) {
throw new Error("DATABASE_URL tanımlı değil");
}Node.js, 20.6 sürümünden itibaren bu dosyayı ek bir paket olmadan node --env-file=.env server.js ile okuyabilir. Aynı ad hem gerçek ortamda hem dosyada tanımlıysa, Node.js belgelerine göre ortamdaki değer önceliklidir. Bu davranış, sunucuda tanımlı değerlerin unutulmuş bir .env dosyası tarafından ezilmesini engeller.
Gizli bilgiler için yeterli mi?
Ortam değişkeni, parolayı koda yazmaktan kat kat iyidir; ama kendiliğinden güvenli değildir:
- Sürecin başlattığı alt süreçlere aktarılır.
- Hata raporlama araçları, hata ayıklama sayfaları veya dikkatsiz bir
console.log(process.env)ile loglara düşebilir. - Sunucuda aynı kullanıcıyla veya yönetici yetkisiyle çalışan başka bir süreç tarafından okunabilir.
- CI çıktılarında yanlışlıkla yazdırılabilir.
Pratik kurallar: .env dosyalarını .gitignore'a ekleyin ve repository'de yalnızca değerleri boş bırakılmış bir .env.example tutun; her ortam için farklı API anahtarı kullanın; anahtar rotasyonu, erişim kaydı ve paylaşım gerektiren durumlarda bir gizli bilgi yönetimi servisine geçin.
Tarayıcıya sızan değişkenler
Ön yüz derleme araçlarında ortam değişkenleri farklı çalışır. Next.js'te varsayılan olarak değişkenler yalnızca sunucuda okunabilir; NEXT_PUBLIC_ önekiyle başlayanlar ise next build sırasında JavaScript paketinin içine sabit değer olarak yazılır. İki sonucu vardır:
- Bu önekle tanımlanan her değer, sitenin kaynak kodunu açan herkes tarafından görülebilir. Gizli bir anahtar asla
NEXT_PUBLIC_ile başlamamalıdır. - Değer derleme anında dondurulur. Aynı Docker imajı farklı ortamlara taşınırsa, bu değişkenler derlendikleri ortamın değerini taşımaya devam eder.
Sık yapılan hatalar
- Eksik değişkenle sessizce çalışmak: Uygulama açılışta gerekli tüm değişkenleri doğrulamalı ve eksik varsa hemen durmalıdır; aksi halde hata ilk e-posta gönderiminde, saatler sonra ortaya çıkar.
- Tip varsayımı: Ortam değişkenleri her zaman metindir;
"false"değeri JavaScript'te doğru (truthy) kabul edilir. - Görünmeyen karakterler: Panele yapıştırılan değerin sonundaki boşluk veya satır sonu, “parola yanlış” hatasının yaygın bir kaynağıdır.
- Yeniden başlatmayı unutmak: Çalışan bir süreç, değişkenler değiştiğinde yeni değeri kendiliğinden görmez.