.env Dosyası Nedir? Ortam Değişkenleri için En İyi Pratikler

.env Dosyası Nedir ve Neden Kullanılır?

.env dosyası, bir uygulamanın çalışması için gereken yapılandırma değerlerini ve gizli anahtarları (API anahtarı, veritabanı parolası, token gibi) kaynak kodun dışında tutmak için kullanılan düz metin dosyasıdır. Amaç, hassas veya ortama özgü bilgileri doğrudan koda gömmek yerine, uygulamanın çalıştığı ortamdan (environment) okumaktır. Bu yaklaşım, yazılım geliştirmede yaygın kabul gören 12-factor app metodolojisinin üçüncü maddesiyle örtüşür: yapılandırma kod tabanından tamamen ayrılmalı ve ortam değişkenleri üzerinden sağlanmalıdır.

Bunun pratik faydası şudur: aynı kod tabanı, tek satır değiştirilmeden farklı ortamlarda (geliştirme, test/staging, production) farklı ayarlarla çalışabilir. Geliştirme ortamında veritabanı yerelde çalışırken, production'da uzak bir sunucuda olabilir; API anahtarları sandbox ve canlı hesaplar arasında değişebilir. Bu değerleri koda yazmak yerine .env dosyasına koymak hem güvenliği artırır hem de dağıtım (deployment) sürecini basitleştirir — sunucuya yalnızca o ortama ait .env dosyası (veya ortam değişkenleri) tanımlanır, kodun kendisi değişmez.

KEY=VALUE Söz Dizimi Kuralları

.env dosyasının biçimi basittir: her satır bir ANAHTAR=DEĞER çiftidir. Değişken adı bir harf veya alt çizgiyle başlamalı, devamında harf, rakam ve alt çizgi bulunabilir. Eşittir işaretinin etrafında boşluk bırakılmaması önerilir; bazı ayrıştırıcılar boşluklu yazımı tolere etse de, tutarlılık için PORT=3000 şeklinde yazmak PORT = 3000 yazmaktan daha güvenlidir.

Değerde boşluk varsa (örneğin birden çok kelimeden oluşan bir bağlantı dizesi ya da uygulama adı), değeri tek ya da çift tırnak içine almak gerekir: APP_NAME="Keydal Panel". Tırnaksız bırakılan boşluklu değerler bazı ayrıştırıcılarda satırın yanlış yorumlanmasına yol açabilir. # ile başlayan satırlar yorum satırıdır ve ayrıştırıcı tarafından yok sayılır; boş satırlar da dosyayı bölümlere ayırmak için serbestçe kullanılabilir.

# veritabanı ayarları
DB_HOST=localhost
DB_PORT=5432
DB_NAME=keydal_app

# uygulama ayarları
NODE_ENV=production
APP_NAME="Keydal Panel"
API_KEY=sk_live_ornekanahtar123

dotenv Kütüphaneleri .env Dosyasını Nasıl Yükler?

Node.js projelerinde dotenv paketi en yaygın çözümdür. Uygulamanın başında require('dotenv').config() çağrıldığında kütüphane çalışma dizinindeki .env dosyasını okur, her satırı ayrıştırır ve anahtar-değer çiftlerini process.env nesnesine yükler; kod içinde bu değerlere process.env.DB_HOST gibi erişilir. Aynı format ve mantık başka ekosistemlerde de karşılığını bulur: PHP tarafında vlucas/phpdotenv, Python tarafında python-dotenv aynı .env söz dizimini okuyup kendi ortam değişkeni mekanizmalarına aktarır.

Burada dikkat edilmesi gereken bir davranış var: aynı anahtar dosyada birden fazla kez tanımlanırsa hiçbir hata verilmez — ayrıştırıcı (Node'un dotenv'i dahil) dosyadaki son değeri geçerli sayar. Bu, üstteki bir satırda tanımladığınız bir değerin fark etmeden ezilmesine yol açabilir; özellikle uzun ve düzensiz büyümüş .env dosyalarında kolayca gözden kaçan bir hatadır.

.env Asla Commit Edilmemeli: .gitignore ve .env.example

Peki ekip arkadaşlarınız hangi değişkenlerin gerekli olduğunu nasıl bilecek? Bunun cevabı .env.example dosyasıdır: gerçek değerler yerine yer tutucu (placeholder) değerler içeren, .env ile aynı anahtarlara sahip bir şablon dosyası. Bu dosya normal bir kod dosyası gibi Git'e commit edilir. Yeni bir geliştirici projeyi klonladığında .env.example'ı .env olarak kopyalar ve kendi ortamına ait gerçek değerleri girer; hangi değişkenin zorunlu olduğunu tahmin etmek zorunda kalmaz.

• Değişken adlarında büyük harf ve alt çizgi kullanın (DATABASE_URL gibi) — bu, kabuğun (shell) yerleşik değişkenleriyle (PATH, HOME vb.) çakışmayı önlemeye yardımcı olur.
• .env.example dosyasını her yeni değişken eklendiğinde güncel tutun; aksi halde şablon gerçek yapılandırmadan geride kalır ve işe yaramaz hale gelir.
• Gizli anahtarları ve gizli olmayan yapılandırmayı (PORT, NODE_ENV gibi) aynı dosyada tutabilirsiniz, ancak hangisinin gerçekten hassas olduğunu bir yorum satırıyla belirtmek okunabilirliği artırır.
• Prodüksiyon sırlarını yerel .env dosyasından kopyalamak yerine, sunucunun veya barındırma platformunun kendi ortam değişkeni mekanizmasından tanımlayın.

Production Ortamında .env Dosyası Kullanmalı mısınız?

Yerel geliştirmede .env dosyası pratiktir: her geliştirici kendi makinesinde farklı yerel değerlerle (kendi veritabanı, kendi API anahtarı) çalışır, dosya proje kökünde durur ve dotenv gibi bir kütüphane onu otomatik yükler. Production ortamında ise durum farklıdır. Birçok barındırma platformu, container orkestrasyon aracı (Docker Compose, Kubernetes) ve CI/CD sistemi, ortam değişkenlerini kendi arayüzü veya yapılandırma dosyası üzerinden doğrudan tanımlamanıza izin verir; bu durumda sunucu diskinde ayrı bir .env dosyası taşımanıza gerek kalmaz.

Bu ayrım önemlidir çünkü sunucuda duran bir .env dosyası, yanlış bir yapılandırma veya güvenlik açığı sonucu okunabilir hale gelirse tüm gizli anahtarları tek seferde ifşa eder. Değişkenleri platformun secret/environment yönetimi üzerinden enjekte etmek, gizli anahtarların düz metin bir dosya olarak diskte bulunmasını ortadan kaldırır. .env dosyasını yine de kullanan projelerde, dosyanın sunucuda yalnızca uygulama kullanıcısının okuyabileceği izinlerle tutulması ve versiyon kontrolüne asla dahil edilmemesi gerekir.

Sık Yapılan Hatalar

• Gerçek gizli anahtarları herkese açık bir depoya commit etmek — .gitignore eklenmeden yapılan ilk commit çoğu zaman bu hatayı ortaya çıkarır.
• Tutarsız tırnak kullanımı: bazı değerler çift tırnakla, bazıları tek tırnakla, bazıları tırnaksız yazıldığında, ayrıştırıcı tırnak karakterlerini değerin bir parçası sanabilir ve uygulama değeri tırnaklarla birlikte okur.
• .env.example dosyası olmadan projeyi paylaşmak — yeni geliştirici hangi değişkenlerin tanımlanması gerektiğini kod içindeki process.env çağrılarını tek tek arayarak bulmak zorunda kalır.
• Gizli anahtarlarla gizli olmayan yapılandırmayı hiçbir açıklama olmadan aynı dosyada karıştırmak — hangi değerin rotate edilmesi gerektiğini, hangisinin sadece bir ayar olduğunu belirsizleştirir.
• Aynı anahtarı dosyada birden fazla kez tanımlamak — hata vermeden sessizce son değerin geçerli olmasına yol açar.

Formatlama ve Doğrulama

Elle düzenlenen .env dosyalarında boşluk hataları, tekrarlanan anahtarlar veya geçersiz değişken adları kolayca gözden kaçar. KEYDAL'in .env Formatlayıcı aracı yapıştırdığınız içeriği tarayıcınızda analiz eder; boşlukları normalize eder, tekrarlanan değişkenleri ve geçersiz adları işaretler. Yapıştırdığınız içerik hiçbir zaman sunucuya gönderilmez, tüm işlem yerel olarak gerçekleşir.

.env Formatlayıcı

.env dosyanızı yapıştırın; boşluk, tekrarlanan değişken ve geçersiz ad hatalarını anında görün.