.env Dosyası Nedir? Ortam Değişkenleri Rehberi

Bir web uygulaması geliştirirken veritabanı şifresi, API anahtarı, üçüncü taraf servis bilgileri gibi hassas verilerle çalışmanız kaçınılmazdır. Bu bilgileri doğrudan kaynak koduna yazmak ciddi bir güvenlik açığı oluşturur. İşte .env dosyaları tam bu noktada devreye girer: ortam değişkenlerini (environment variables) güvenli ve düzenli bir şekilde yönetmenizi sağlar.

Ortam Değişkenleri Nedir?

Ortam değişkenleri (environment variables), işletim sistemi düzeyinde tanımlanan anahtar-değer çiftleridir. Uygulamanız çalışırken bu değerlere erişebilir. Ortam değişkenleri sayesinde aynı kod tabanı, farklı ortamlarda (geliştirme, test, üretim) farklı ayarlarla çalışabilir.

# Terminal üzerinden ortam değişkeni tanımlama
export DATABASE_URL="postgresql://localhost:5432/mydb"
export API_KEY="sk-abc123def456"

# Node.js'de okuma
process.env.DATABASE_URL
process.env.API_KEY

.env Dosyası ve Söz Dizimi

.env dosyası, projenizin kök dizininde yer alan düz metin dosyasıdır. Her satırda bir ortam değişkeni tanımlanır:

# Veritabanı ayarları
DATABASE_URL=postgresql://user:password@localhost:5432/mydb
DB_HOST=localhost
DB_PORT=5432

# API anahtarları
STRIPE_SECRET_KEY=sk_live_abc123
SENDGRID_API_KEY=SG.xxxx

# Uygulama ayarları
NODE_ENV=development
PORT=3000
APP_URL=http://localhost:3000

# Boşluklu değerler tırnak içinde
APP_NAME="Benim Uygulamam"

Söz dizimi kuralları:

• # ile başlayan satırlar yorum satırıdır
• Değişken adları genellikle BÜYÜK_HARF ve alt çizgi kullanır
• Eşittir işaretinin etrafında boşluk bırakılmaz
• Boşluk içeren değerler çift tırnak içinde yazılır
• Boş satırlar görmezden gelinir

dotenv Kütüphanesi

Node.js'de .env dosyasını otomatik olarak yüklemek için dotenv paketi kullanılır:

# Kurulum
npm install dotenv

# Kullanım (uygulamanın en başında)
require('dotenv').config()

# veya ES Modules ile
import 'dotenv/config'

# Artık process.env üzerinden erişilebilir
console.log(process.env.DATABASE_URL)

Python'da python-dotenv, Ruby'de dotenv gem'i, PHP'de vlucas/phpdotenv paketi benzer işlevi görür.

Ortam Bazlı .env Dosyaları

Farklı ortamlar için ayrı .env dosyaları kullanmak yaygın bir pratiktir:

• .env — Varsayılan değerler (tüm ortamlarda geçerli)
• .env.local — Yerel geliştirme ortamı (git'e eklenmez)
• .env.development — Geliştirme ortamına özel
• .env.production — Üretim ortamına özel
• .env.test — Test ortamına özel

Yükleme önceliği genellikle şöyledir: .env.local > .env.[ortam] > .env. Daha spesifik dosya, genel dosyadaki değerin üzerine yazar.

Güvenlik: .env Dosyasını Asla Commit Etmeyin!

Bu, ortam değişkenleri yönetiminin en kritik kuralıdır. .gitignore dosyanıza .env'yi mutlaka ekleyin:

# .gitignore
.env
.env.local
.env.*.local

Bunun yerine bir .env.example dosyası oluşturun ve gerçek değerler yerine yer tutucu bilgiler koyun:

# .env.example (git'e eklenir)
DATABASE_URL=postgresql://user:password@host:5432/dbname
API_KEY=your-api-key-here
SECRET_KEY=your-secret-key

Yeni geliştiriciler bu dosyayı kopyalayıp kendi değerlerini girer.

Framework Bazlı Farklılıklar

Next.js

Next.js yerleşik .env desteği sunar; dotenv paketine ihtiyaç yoktur. Tarayıcıda erişilecek değişkenler NEXT_PUBLIC_ ön ekiyle başlamalıdır:

# Yalnızca sunucu tarafında
DATABASE_URL=postgresql://...
SECRET_KEY=abc123

# İstemci tarafında da erişilebilir
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_GA_ID=G-XXXXX

Vite

Vite'de istemci tarafına açık değişkenler VITE_ ön ekini kullanır:

VITE_API_URL=https://api.example.com
VITE_APP_TITLE=Uygulama Başlığı

# JavaScript'te erişim
import.meta.env.VITE_API_URL

Create React App

CRA'da ise REACT_APP_ ön eki kullanılır:

REACT_APP_API_URL=https://api.example.com