Değişkenleri (Environment Variables) ve .env Dosyası Kullanım Rehberi

Lokalde her şey kusursuz çalışıyor olabilir ancak projeyi canlıya (production) aldığınızda uygulamanız hata mı veriyor? Ya da daha kötüsü, API anahtarlarını yanlışlıkla GitHub'a pushlayıp o korku dolu e-postayı aldığınız oldu mu? Yazılım dünyasında bu senaryolarla henüz karşılaşmadıysanız, yeterince kod yazmamış olabilirsiniz. İşin şakası bir yana, modern web geliştirmede ortam değişkenleri (environment variables) ve .env dosyaları, projenin sadece ayarlarını değil, güvenliğini de sırtlayan en kritik yapıdır.

Bu rehberde, "bu nedir"den ziyade, React, Next.js veya Node.js projelerinde bu dosyaları nasıl doğru ve güvenli yöneteceğinize odaklanacağız. Kodun içine gömülü şifrelerden kurtulmanın vakti geldi.

Ortam Değişkeni (Environment Variable) Tam Olarak Nedir?

En basit haliyle ortam değişkenleri, uygulamanın çalıştığı yere (lokal, test veya canlı sunucu) göre değişmesi gereken dinamik değerlerdir. Kodun mantığı sabittir ancak veritabanı şifresi, API adresi veya port numarası çalıştığınız makineye göre değişir.

Şöyle düşünebilirsiniz; evinizin anahtarı (şifreler) ve posta kutusu adresiniz (API URL) her evde (ortamda) farklıdır. Siz her taşındığınızda evin duvarlarını yıkıp yeniden yapmazsınız, sadece anahtarı değiştirirsiniz. Yazılımda da sabitleri koddan ayırmak (hardcoding yapmamak) için bu değişkenleri kullanıyoruz.

Neleri burada saklamalısınız?

• API Anahtarları (Stripe, Google Maps, AWS vb.)
• Veritabanı bağlantı linkleri (Connection Strings)
• JWT Secret Key gibi şifreleme anahtarları
• Backend API URL'leri (Lokalde localhost:3000, canlıda api.domain.com)

.env Dosyası Oluşturma ve Sözdizimi Kuralları

Birçok junior geliştiricinin takıldığı ilk nokta burasıdır. .env dosyası aslında basit bir metin dosyasıdır ancak tahammülsüzdür; en ufak bir boşluk hatasında çalışmayı durdurur.

Projenin kök dizininde (root directory) .env adında bir dosya oluşturup içine şu formatta yazıyoruz:

DB_HOST=localhost
DB_USER=root
DB_PASS=cokgizlisifre123
API_KEY=12345abcdef

Dikkat etmeniz gereken altın kurallar:

1. Eşittir işaretinin yanında boşluk bırakmayın: DB_HOST = localhost derseniz çalışmaz. Bitişik olmalı.
2. Tırnak işareti kullanmanıza gerek yok: Değerin içinde boşluk varsa (örneğin: "Gizli Anahtar") tırnak kullanabilirsiniz ancak düz metinler için tırnak kullanmamak daha temizdir.
3. Büyük harf standardı: Zorunlu değil ama evrensel bir yazılımcı kuralıdır; değişken isimleri BUYUK_HARFLE_VE_ALT_TIRE_ILE yazılır.

Kritik Güvenlik Adımı: .gitignore

Bu başlığı okumadan geçerseniz, projenizin güvenlik açığı vermesi an meselesidir. .env dosyası sizin mahrem bilgilerinizi içerir. Bu dosyayı ASLA ve ASLA Git geçmişine (repository) göndermemelisiniz.

Projeye başladığınız ilk saniyede .gitignore dosyanızı açın ve içine şunu ekleyin:

# .gitignore dosyası
.env
.env.local
.env.development.local
.env.test.local
.env.production.local
node_modules/

Ekip arkadaşlarınız ne yapacak? Onlar için projenin kök dizininde bir .env.example dosyası oluşturun. İçine sadece değişken isimlerini yazın ama değerleri boş bırakın.

# .env.example (Güvenli, commit edilebilir)
DB_HOST=
DB_USER=
API_KEY=

Böylece takımdaki diğer geliştiriciler projeyi çektiklerinde, bu dosyayı kopyalayıp kendi .env dosyalarını oluşturabilirler.

Farklı Platformlarda .env Kullanımı

Her framework bu dosyaları okumak için farklı yöntemler kullanır. İşte en popüler olanları:

1. Node.js (Backend)

Node.js'in eski sürümlerinde .env dosyasını okumak için harici bir kütüphaneye ihtiyacımız var: dotenv.

npm install dotenv

Kodunuzun en tepesinde (entry point), yani genellikle index.js veya app.js dosyasının ilk satırında şunu çağırmalısınız:

require('dotenv').config();
console.log(process.env.DB_HOST); // Çıktı: localhost

Not: Node.js v20.6.0 ve üzeri bir sürüm kullanıyorsanız, artık node --env-file=.env app.js komutuyla paketsiz (native) olarak da bu işlemi yapabilirsiniz.

2. Next.js (Frontend & Fullstack)

Next.js bu konuda harika bir yerleşik desteğe sahip. Ancak burada Client (Tarayıcı) ve Server (Sunucu) ayrımına çok dikkat etmelisiniz.

• Sunucu Tarafı: .env içindeki her şeye process.env.API_KEY diyerek erişebilirsiniz. Bu veriler tarayıcıya gitmez, güvendedir.
• Tarayıcı Tarafı: Eğer bir değişkene React bileşenleri içinden (yani tarayıcıdan) erişmeniz gerekiyorsa, değişken isminin başına NEXT_PUBLIC_ koymak zorundasınız.

# .env
API_SECRET=bu_sadece_sunucuda_gorunur
NEXT_PUBLIC_ANALYTICS_ID=bu_tarayicida_gorunur

Eğer API_SECRET'i frontend tarafında console.log yaparsanız undefined alırsınız. Bu bir hata değil, Next.js'in sizi koruma yöntemidir.

3. Vite (React, Vue)

Vite kullanıyorsanız process.env çalışmaz. Vite, değişkenleri import.meta.env objesi üzerinden okur ve değişkenlerin başına VITE_ ön eki gelmesini ister.

# .env
VITE_API_URL=https://api.ornek.com

Kullanımı ise şöyledir:

console.log(import.meta.env.VITE_API_URL);

Vite projelerinde CSS frameworkleri veya makrolar kullanırken de bu yapılandırmalar önemlidir.

Production (Canlı) Ortamda Yönetim

Kodunuzu Vercel, Netlify veya AWS'ye attığınızda .env dosyanız git ile gitmediği için uygulamanız çalışmayacaktır. Peki ne yapacaksınız? Dosyayı sunucuya FTP ile mi atacaksınız? Kesinlikle hayır.

Modern hosting platformlarının hepsinde Settings > Environment Variables menüsü bulunur. Lokaldeki .env dosyanızın içindeki anahtar-değer ikililerini bu panellere tek tek eklemeniz gerekir. CI/CD süreçlerinde uygulama build alırken bu değerleri oradan çeker.

Canlı ortam ile geliştirme ortamı arasındaki bu geçiş mantığını kavramak, hatasız bir deploy süreci için şarttır.

Sık Karşılaşılan Hatalar ve Çözümleri

1. "Değişkeni ekledim ama undefined geliyor." .env dosyasında bir değişiklik yaptığınızda geliştirme sunucusunu (local server) kapatıp yeniden başlatmanız gerekir. Hot-reload genellikle .env değişikliklerini algılamaz.

2. "Değerler string olarak geliyor." Ortam değişkenleri her zaman String (metin) türündedir. Eğer PORT=3000 yazdıysanız ve kodunuzda matematiksel bir işlem yapacaksanız, onu parseInt(process.env.PORT) ile sayıya çevirmelisiniz. FALSE veya TRUE gibi boolean değerler de string olarak gelir ("false" !== false), buna dikkat edin.

3. "React projemde process is not defined hatası alıyorum." Vite kullanıyorsanız process.env yerine import.meta.env kullanmalısınız. Eğer Create React App kullanıyorsanız değişkenlerin başına REACT_APP_ eklemeyi unutmuş olabilirsiniz.

Ortam değişkenlerini doğru yönetmek, sizi gelecekteki güvenlik açıklarından ve "benim bilgisayarımda çalışıyordu" bahanelerinden kurtarır. Bir kere doğru kurun, gerisini düşünmeyin.