Node.js process.env Kullanımı: Ortam Değişkenleri

process.env, shell'in Node.js programına geçirdiği her ortam değişkeni için bir property içeren bir nesnedir: process.env.PORT, process.env.DATABASE_URL ve benzerleri. Ayarlanmamış bir değişken undefined olarak okunur, ayarlanmış bir değişken ise her zaman bir string'dir. Onu başlangıçta bir kez oku, bir varsayılan değer ver ve ihtiyacın olan tipe çevir.

// The shell normally sets these: PORT=8080 APP_NAME=shop node index.js
process.env.PORT = '8080';
process.env.APP_NAME = 'shop';

const port = Number(process.env.PORT ?? 3000);
const name = process.env.APP_NAME ?? 'my-app';
const region = process.env.REGION ?? 'eu-west';

console.log(name, 'on port', port, 'in', region);
console.log(typeof process.env.PORT, typeof port);

Program shop on port 8080 in eu-west yazdırdı (REGION hiç ayarlanmadığı için varsayılan değeri devreye girdi), ardından string number yazdırdı: değişken, Number() onu çevirene kadar metindir. İlk iki atamayı sil ve tekrar çalıştır, tüm varsayılan değerleri görürsün.

Shell'de ortam değişkeni ayarlamak

Değişkenler, Node.js nereden başlatıldıysa oradan gelir. Bir terminalde:

// macOS and Linux: for one command
PORT=8080 NODE_ENV=production node app.js

// macOS and Linux: for the rest of the terminal session
export PORT=8080

// Windows PowerShell
$env:PORT = "8080"; node app.js

// Windows cmd.exe
set PORT=8080
node app.js

Hosting platformlarının (Heroku, Render, Vercel, Docker, Kubernetes) aynı iş için bir ayarlar sayfası ya da dosyası vardır; kodun onları aynı şekilde okur.

Her şey bir string

process.env hatalarının çoğu buradan gelir. 'false' ve '0' boş olmayan string'lerdir, bu yüzden truthy'dirler:

// The shell normally sets this: DEBUG=false node index.js
process.env.DEBUG = 'false';

if (process.env.DEBUG) {
    console.log('naive check: debug is ON');
}

const debug = process.env.DEBUG === 'true';
console.log('correct check: debug is', debug ? 'ON' : 'OFF');

Naif kontrol, false olarak ayarlanmış bir değişken için debug is ON yazdırdı; bu yüzden beklediğin tam string ile karşılaştır. Sayılarda Number(process.env.X) eksik bir değeri NaN'a çevirir, bu yüzden ilk örnekte ?? ile yapıldığı gibi varsayılan değeri çevirmeden önce uygula.

NODE_ENV

NODE_ENV bir Node.js özelliği değil, bir gelenektir: Node.js onu asla ayarlamaz. Onu kütüphaneler okur. Örneğin Express, değer production olduğunda hata sayfalarından stack trace'leri gizler; birçok araç da yalnızca geliştirmeye özel kontrolleri atlar.

// The shell normally sets this: NODE_ENV=production node index.js
process.env.NODE_ENV = 'production';

const isProduction = process.env.NODE_ENV === 'production';

console.log('mode:', process.env.NODE_ENV);
console.log('verbose logs:', !isProduction);

Program mode: production ve verbose logs: false yazdırdı; 'production''ı 'development' yaparsan ikinci satır tersine döner. production, development ve test değerlerinde kal, çünkü kütüphaneler tam olarak bu kelimeleri kontrol eder.

.env dosyaları: --env-file ve dotenv

Her değişkeni node'dan önce yazmak bir süre sonra bıktırır. Bir .env dosyası onları proje klasöründe, satır başına bir tane olacak şekilde tutar:

// .env
PORT=8080
DATABASE_URL=postgres://localhost/shop
API_KEY=dev-key-123

Node.js 20.6 ve sonrası onu bir flag ile, paket gerekmeden okur:

node --env-file=.env app.js

Eski sürümlerde ya da tercih edersen dotenv paketini kur (npm install dotenv) ve onu giriş dosyanın en başında, process.env'i okuyan herhangi bir koddan önce yükle:

require('dotenv').config(); // copies .env into process.env

console.log(process.env.PORT); // 8080

İkisi de shell'de zaten ayarlı olan bir değişkenin üzerine yazmaz, yani production ayarları dosyaya baskın gelir.

Eksik değişkenlerde erken hata ver

Eksik bir veritabanı URL'si programı başlangıçta net bir mesajla durdurmalı, bir saat sonra ilk istekte çökertmemeli:

// The shell normally sets these
process.env.DATABASE_URL = 'postgres://localhost/shop';

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

if (missing.length > 0) {
    console.log('Missing environment variables:', missing.join(', '));
} else {
    console.log('Config OK');
}

Program Missing environment variables: API_KEY yazdırdı; en üste process.env.API_KEY = 'test'; ekle, Config OK yazdırır. Gerçek bir programda mesajın ardından process.exit(1) çağır, çünkü bir deploy script'i ya da container platformu başlangıcın başarısız olduğunu sıfır olmayan çıkış kodundan anlar.

Gizli bilgileri asla commit etme

.env dosyasını oluşturduğun gün .gitignore'a ekle. Bunun yerine değişken adlarını ve sahte değerleri içeren bir .env.example commit et, böylece başkaları neyi ayarlaması gerektiğini bilir. Bir repository'ye bir kez push edilmiş bir anahtarı, commit'i sonradan silsen bile sızmış say ve değiştir.