Node.js’te Ortam Değişkenleri Nasıl Tanımlanır ve Kullanılır? Uygulamalı Rehber

Veritabanı şifrelerini, API anahtarlarını ve gizli bilgileri doğrudan kaynak koda yazmak, veri sızıntılarının en kestirme yoludur. Üretim uygulamaları bu verileri güvenle yönetmek için ortam değişkenleri kullanır – gelin bunu doğru şekilde yapalım.

Ortam Değişkenleri Neden Bu Kadar Önemli?

1. Her şeyi koda gömmek (hardcode) – Veritabanı şifresi config.js içinde, API anahtarı bir yorum satırında, tüm sırlar git’e commit edilmiş. Bu, hacklenmenin en garantili yollarından biridir. Yapmayın.
2. Ortam değişkenleri kullanmak – Hassas verileri koddan ayırırsınız. Geliştirme, test ve üretim için farklı değerler kullanabilirsiniz. Güvenli, ölçeklenebilir ve sektörde standart.
3. Gizli yönetim hizmeti kullanmak – AWS Secrets Manager, HashiCorp Vault vb. Büyük ölçekli sistemler için kurumsal yaklaşım.

Ortam Değişkenleri Aslında Nedir?

DB_PASSWORD=supersecret123
API_KEY=abc123xyz789
NODE_ENV=production

const password = process.env.DB_PASSWORD; // "supersecret123"
const apiKey = process.env.API_KEY;       // "abc123xyz789"
const env = process.env.NODE_ENV;        // "production"

Neden Önemli?

Sorun: Değişkenleri Elle Ayarlamak Yorucu

export DB_HOST=localhost
export DB_PASSWORD=mypassword
export API_KEY=key123

$env:DB_HOST="localhost"
$env:DB_PASSWORD="mypassword"
$env:API_KEY="key123"

Dotenv Kullanımı: En Kolay Yol

Adım 1: Dotenv’i Kurun

npm install dotenv

yarn add dotenv

Adım 2: .env Dosyası Oluşturun

DB_HOST=localhost
DB_PORT=5432
DB_USER=admin
DB_PASSWORD=mysecurepassword
API_KEY=abc123xyz789
NODE_ENV=development
JWT_SECRET=your-jwt-secret-key
LOG_LEVEL=info

Adım 3: Uygulamada Değişkenleri Yükleyin

// app.js veya server.js – İLK SATIR
require('dotenv').config();


// Artık process.env kullanılabilir
const express = require('express');
const app = express();


const dbHost = process.env.DB_HOST;
const dbPort = process.env.DB_PORT;
const apiKey = process.env.API_KEY;


console.log(`Veritabanına bağlanılıyor: ${dbHost}:${dbPort}`);
app.listen(3000);

Adım 4: .env Dosyasını .gitignore’a Ekleyin

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

Adım 5: Şablon Dosyası Paylaşın (Sır Olmadan)

# .env.example – Commit edilecek olan bu
DB_HOST=localhost
DB_PORT=5432
DB_USER=admin
DB_PASSWORD=change_me
API_KEY=change_me
NODE_ENV=development
JWT_SECRET=change_me
LOG_LEVEL=info

cp .env.example .env
# Sonra .env içini gerçek değerlerle güncelleyin

Uygulamalı Örnek: Express API ve Ortam Değişkenleri

// server.js
require('dotenv').config();


const express = require('express');
const postgres = require('pg');


const app = express();


// Ortamdan yapılandırmayı oku
const config = {
  db: {
    host: process.env.DB_HOST,
    port: process.env.DB_PORT,
    user: process.env.DB_USER,
    password: process.env.DB_PASSWORD,
    database: process.env.DB_NAME
  },
  api: {
    port: process.env.PORT || 3000,
    apiKey: process.env.API_KEY,
    jwtSecret: process.env.JWT_SECRET
  },
  env: process.env.NODE_ENV || 'development'
};


// Zorunlu değişkenleri doğrula
if (!config.api.apiKey) {
  throw new Error('API_KEY ortam değişkeni zorunludur');
}


// Veritabanına bağlan
const pool = new postgres.Pool(config.db);


// Rotalar
app.get('/api/users', (req, res) => {
  const authHeader = req.headers.authorization;
  const token = authHeader?.split(' ');[11]


  // JWT_SECRET ile token doğrulama
  if (!token) {
    return res.status(401).json({ error: 'Unauthorized' });
  }


  // Connection pool ile sorgu çalıştır
  pool.query('SELECT * FROM users', (err, result) => {
    if (err) throw err;
    res.json(result.rows);
  });
});


// Sunucuyu başlat
const port = config.api.port;
app.listen(port, () => {
  console.log(`Sunucu ${config.env} modunda ${port} portunda çalışıyor`);
});

• Veritabanı bilgileri .env dosyasından gelir
• API anahtarları ve diğer sırlar ortam değişkeni olarak yönetilir
• Aynı kod, farklı .env dosyalarıyla dev, staging ve prod’da çalışır
• Hiçbir hassas bilgi git deposuna girmez

Ortam Değişkenleri İçin En İyi Pratikler

1. Gerekli Değişkenleri Uygulama Başlangıcında Doğrulayın

require('dotenv').config();


const required = ['DB_HOST', 'DB_USER', 'DB_PASSWORD', 'API_KEY'];
const missing = required.filter(key => !process.env[key]);


if (missing.length > 0) {
  throw new Error(`Eksik ortam değişkenleri: ${missing.join(', ')}`);
}

2. Merkezî Bir Config Nesnesi Kullanın

// config.js
require('dotenv').config();


module.exports = {
  database: {
    host: process.env.DB_HOST,
    port: process.env.DB_PORT,
    user: process.env.DB_USER,
    password: process.env.DB_PASSWORD
  },
  api: {
    key: process.env.API_KEY,
    jwtSecret: process.env.JWT_SECRET
  },
  app: {
    port: process.env.PORT || 3000,
    environment: process.env.NODE_ENV || 'development'
  }
};


// Kullanım
const config = require('./config');
console.log(config.database.host);

3. Farklı Ortamlar İçin Farklı .env Dosyaları

.env           # Varsayılan / geliştirme
.env.production # Üretime özel ayarlar
.env.test       # Test ortamı

const envFile = process.env.NODE_ENV === 'production'
  ? '.env.production'
  : '.env';

require('dotenv').config({ path: envFile });

4. İlgili Değişkenleri Ön Eklerle Gruplayın

# Veritabanı
DB_HOST=localhost
DB_PORT=5432
DB_USER=admin


# Redis
REDIS_HOST=localhost
REDIS_PORT=6379


# Üçüncü parti servisler
STRIPE_API_KEY=sk_...
SENDGRID_API_KEY=SG_...

5. Her Değişkeni Belgelerle Açıklayın

# Veritabanı bağlantısı
DB_HOST=localhost      # PostgreSQL sunucu adresi
DB_PORT=5432           # PostgreSQL portu
DB_USER=admin          # Veritabanı kullanıcı adı
DB_PASSWORD=change_me  # Veritabanı şifresi


# API ayarları
API_KEY=change_me      # Üçüncü parti servis API anahtarı
JWT_SECRET=change_me   # JWT imzalama için gizli anahtar


# Uygulama
PORT=3000              # Express sunucu portu
NODE_ENV=development   # Ortam (development/staging/production)

Üretimde Dotenv Yerine Ne Kullanılır?

AWS Secrets Manager

HashiCorp Vault

CI/CD Ortam Değişkenleri

Kubernetes Secrets

Node.js’i Gerçek Anlamda Öğrenmek

Sonuç: Sırlar Kodda Değil, Ortamda Kalmalı