.env Dosyaları: Ayrıştırma, JSON Dönüşümü ve Yapılandırma

.env dosyası, yapılandırma ve gizli bilgileri kaynak kodunuzun dışında tutan, düz metin halindeki bir KEY=VALUE çiftleri listesidir. Node, Vite, Next.js, Python, Ruby ve Docker Compose tarafından süreç ortamına yüklenen biçim de budur. env to json araması yapıyorsanız genellikle iki şeyden birini istersiniz: bir .env dosyasını araçlar için yapılandırılmış JSON’a dönüştürmek ya da bunu güvenli yapacak kadar kuralları kavramak.

İnsanların kafasını karıştıran üç nokta var; önce bunları yoldan çekelim:

1. .env dosyası düzdür. İç içe yapı yoktur. Her anahtar en üst düzeyde durur.
2. Her değer bir karakter dizisidir. dotenv türleri asla dönüştürmez. PORT=8080, 8080 olarak değil "8080" olarak yüklenir.
3. Dil bilgisi gayriresmidir. Resmi bir belirtim yoktur; bu yüzden yükleyiciler sınır durumlarında (tırnaklar, yorumlar, kaçış dizileri) birbirinden ayrılır.

Bu kılavuz dotenv ayrıştırma kurallarını, .env↔JSON eşlemesini (ve neden her iki yönde dönüştürmek isteyebileceğinizi), .env ile JSON arasında ne zaman seçim yapacağınıza dair bir karar matrisini ve yapılandırmanızı yayına çıkmadan önce nasıl doğrulayacağınızı kapsar. Burada anlatılan her şey .env’den JSON’a Dönüştürücü aracında tamamen tarayıcınızda çalışır; dolayısıyla gerçek kimlik bilgileriyle dolu bir .env bile sayfadan asla ayrılmaz.

.env dosyası nedir?

.env dosyası, ortam yapılandırması için fiili standarttır. dotenv kitaplığı (ve neredeyse her dile yapılan uyarlamaları) dosyayı okur ve her çifti çalışan sürece enjekte eder. Uygulamanız da bağlantı dizesini sabit kodlamak yerine process.env.DATABASE_URL değerini okur. Dosya veritabanı parolaları, API anahtarları, OAuth gizli bilgileri ve erişim token’ları barındırdığı için neredeyse her zaman git tarafından yok sayılır ve hassas olarak ele alınır.

Bir satırın yapısı

Anlamlı her satır, ilk = işaretinden bölünen bir KEY=VALUE çiftidir. Yorum satırları ve boş satırlar atlanır, isteğe bağlı bir export öneki sıyrılıp atılır:

# Database — this whole line is a comment
DATABASE_URL=postgres://user:pass@localhost:5432/mydb
DATABASE_POOL_SIZE=10

# A blank line above is ignored
export DEPLOY_ENV=production   # the `export` prefix is removed
JWT_SECRET="super secret value"

Anahtar, ilk = işaretinden önceki her şeydir ve çevresindeki boşluklar kırpılır. export öneki, dosyanın bir kabukta doğrudan source’lanabilmesi için vardır; dotenv yükleyicileri bunu otomatik olarak sıyırır. İlk = işaretinden bölmek önemlidir çünkü DATABASE_URL gibi değerler sorgu dizelerinde çoğunlukla kendi = karakterlerini içerir.

Yapılandırma neden ortamda yaşar

Bunun gerekçesi, yapılandırmayı ortamda saklamayı söyleyen On İki Faktörlü Uygulama yaklaşımından gelir. Yapılandırma dağıtımdan dağıtıma değişir (dev, staging, production), kod ise aynı kalır. Bunu ortamda tutmak, kaynağı düzenlemeden veya yeniden dağıtmadan bir veritabanı ana makinesini değiştirebileceğiniz ve aynı yapının her yerde çalışacağı anlamına gelir.

Sık rastlanan bir yanlış okuma: insanlar “yapılandırma asla bir dosyada olmaz” sözünü alıntılayıp .env’in yasak olduğu sonucuna varır. Asıl kural daha dardır. Yapılandırma, kodla iç içe ve sürüm denetiminde izlenen, uygulamanın içine işlenmiş bir dosya olmamalıdır. Geliştirme için yerel, git tarafından yok sayılan bir .env ise gayet sorunsuz ve standarttır. Kaçınılması gereken şey, gizli bilgileri içine gömülü gerçek bir .env dosyasını üretime göndermektir.

.env ayrıştırma kuralları (araçların anlaşamadığı sınır durumları)

.env dosyasını ayrıştırmak için karşılaştırılacak resmi bir belirtim olmadığından, her yükleyici sınırlarda kendi kararlarını verir. Aşağıdaki kurallar yaygın olarak izlenen dotenv geleneklerinden oluşur; dönüştürücünün uyguladığı ve çoğu çalışma zamanının üzerinde anlaştığı kurallardır bunlar.

Tırnaklar ve kaçış dizileri

Bir değerin nasıl tırnaklandığı her şeyi değiştirir:

• Çift tırnaklar kaçış dizilerini işler. \n bir satır sonu, \t bir sekme, \r bir satır başı, \\ bir ters eğik çizgi ve \" da bire bir çift tırnak olur. Çift tırnaklı bir değer, kapatan tırnağa kadar birden çok satıra da yayılabilir; PEM özel anahtarlarının bir .env içine böyle sığması bundan kaynaklanır.
• Tek tırnaklar birebirdir. Tıpkı kabukta olduğu gibi hiçbir kaçış işlemesi yapılmaz. 'no \n escapes here' ters eğik çizgiyi ve n’yi olduğu gibi korur.
• Tırnaksız değerler satır sonuna kadar uzanır ve sondaki boşluklar kırpılır. Satır içi bir # (bir boşluğun ardından bir kare işareti), sıyrılıp atılan bir yorum başlatır.

İşte bu son kural, hex renklerle insanların başını derde sokar. COLOR=#ff0000, #’ten sonraki her şeyi kaybeder. Tırnak içine alın, yani COLOR="#ff0000" yazın, böylece değer korunur.

Her şey bir karakter dizisidir

Bu, dotenv biçimi hakkındaki tek en önemli gerçektir. PORT=8080, 8080 sayısı olarak yüklenmez. "8080" karakter dizisi olarak yüklenir, çünkü process.env değerleri çalışma zamanında her zaman karakter dizisidir. dotenv türleri asla dönüştürmez.

Bu, gerçek hatalara yol açar. if (process.env.DEBUG), DEBUG=false olsa bile doğru (truthy) olur, çünkü "false" boş olmayan bir karakter dizisidir. Sayısal karşılaştırmalar sessizce başarısız olur çünkü "8080", 8080 değildir. Herhangi bir “türleri çıkarsa” özelliği (dönüştürücüdeki düğme dahil) dotenv’in üzerine eklenen bir kolaylık katmanıdır, standardın bir parçası değildir. Bunu kullanırken JSON’un, uygulamanızın gerçekte aldığından farklı olacağını aklınızda tutun.

Yinelenen anahtarlar, çok satırlı değerler ve aradeğerleme

Aynı anahtar iki kez göründüğünde, son geçen kazanır. Önceki değer sessizce düşürülür. Bu sık rastlanan bir yanlış yapılandırma tuzağıdır: uzun bir dosyanın altına yakın yerde başıboş bir yineleme, kullanmayı düşündüğünüz değeri sessizce gölgeler. İyi bir dönüştürücü, yinelenenleri yutmak yerine bir uyarıyla işaretler.

Çok satırlı değerler yalnızca çift tırnak içinde çalışır; kapatan " işaretine kadar satırlara sarılarak yayılır. Ve ${VAR} aradeğerlemesi, yani bir değişkene başka bir değişkenden başvurmak, bazı yükleyicilerde vardır ama evrensel değildir. Çalışma zamanları arasında buna güvenmeyin; bir yığında sorunsuz aradeğerleme yapan bir dosya, başka birinde birebir ${VAR} dizesini yükleyebilir.

Bir bakışta ayrıştırma kuralları

Girdi satırı	Ayrıştırılan değer	Kural
PORT=8080	"8080"	Tırnaksız, karakter dizisi olarak korunur (tür dönüşümü yok)
APP_NAME=My App # title	"My App"	Tırnaksız: satır içi # yorumu sıyrılır, sondaki boşluk kırpılır
GREETING="Hello,\nWorld"	Hello,⏎World	Çift tırnaklar \n’yi gerçek bir satır sonu olarak işler
LITERAL='no \n escapes'	no \n escapes	Tek tırnaklar birebirdir, kaçış işlemesi yok
COLOR=#ff0000	""	Tırnaksız # bir yorum başlatır; değer kaybolur, tırnaklayın
export AWS_REGION=us-east-1	us-east-1	export öneki sıyrılır
EMPTY=	""	Boş değer geçerli bir boş karakter dizisidir

.env mi JSON yapılandırması mı: hangisini ne zaman kullanmalı

Dürüst yanıt “JSON daha iyidir” değildir. Farklı sorunları çözerler. Bir .env dosyası düz, yalnızca karakter dizisi içeren, yoruma elverişli ve ortam başına ayrı bir yapıdır; gizli bilgiler ve dağıtım zamanı geçersiz kılmaları için tasarlanmıştır. JSON ise iç içe, türlü ve yapılandırılmıştır ama yorumları yoktur ve yanlışlıkla işlenmesi kolaydır. İkisi arasında seçim yapmak, asıl env vs json config kararıdır.

.env’in yapamadıkları

Bir .env iç içe yapı kuramaz, dizi tutamaz ve gerçek türler taşıyamaz. Düz bir karakter dizileri listesidir. Yapılandırmanız doğası gereği gruplanmışsa, onu iç içe geçirmek yerine bir önek geleneğiyle düzleştirirsiniz: bir db nesnesi yerine DB_HOST ve DB_PORT. Anahtarlar düz kalır; gruplamayı kodda yeniden kurarsınız.

JSON’un daha iyi olduğu yerler

Yapı asıl mesele olduğunda JSON kazanır: iç içe nesneler, diziler ve gerçek sayılar, mantıksal değerler ve null. Bir şemaya göre doğruladığınız ve tür ürettiğiniz biçim de odur. Düz bir dosyanın ifade edemeyeceği bir hiyerarşiye ihtiyacınız varsa, doğru araç JSON ya da aşağıda ele alınan YAML’dir.

Karar matrisi

İhtiyaç	.env	JSON	Neden
Gizli bilgiler / kimlik bilgileri	✅	⚠️	.env gelenek gereği git tarafından yok sayılır; JSON yapılandırmasını yanlışlıkla işlemek kolaydır
Ortam başına geçersiz kılmalar	✅	⚠️	Ortam başına bir .env, standart dağıtım desenidir
İç içe yapı	❌	✅	.env düzdür; JSON doğal olarak iç içe geçer
Türlü değerler (sayı/mantıksal/null)	❌	✅	.env değerleri her zaman karakter dizisidir; JSON’un gerçek türleri vardır
Satır içi yorumlar	✅	❌	.env, #’i destekler; JSON’un yorum sözdizimi yoktur
Şema doğrulaması	⚠️	✅	.env→JSON dönüşümünden sonra doğrulayın; JSON doğrudan doğrulanır

.env’i JSON’a ve geri dönüştürmek

Kuralları bildikten sonra her iki yönde dönüştürme makinesel hale gelir. Eşleme üst düzeyde 1:1’dir; her KEY=VALUE satırı bir JSON özelliğine karşılık gelir. Tek incelik, türler ve iç içe yapıdır.

.env → JSON

Her KEY=VALUE çifti bir JSON özelliği olur. Varsayılan olarak her değer bir karakter dizisidir, dotenv’in çalışma zamanında yüklediğine sadıktır; isteğe bağlı bir tür çıkarımı düğmesi, tırnaksız sayıları, mantıksal değerleri ve null’u yükseltir. Sonuç düz bir nesnedir. Buna birkaç durumda ihtiyaç duyarsınız: yalnızca JSON kabul eden araçlara yapılandırma beslemek, toplu olarak bir gizli bilgi yöneticisine aktarmak, bir şemaya göre doğrulamak ya da yayılmış bir .env’i yapılandırılmış veri olarak okumak. .env’den JSON’a Dönüştürücü, yinelenen anahtarları gördüğünde bir uyarıyla birlikte tam olarak bunu tarayıcıda yapar.

JSON → .env

Tersi yalnızca bir nesneyi alır; üst düzey bir dizi ya da çıplak skaler değerin, değişkenlere eşlenecek anahtar adları yoktur. Sayılar ve mantıksal değerler çıplak yazılır (PORT=8080), null boş bir KEY=’e dönüşür ve boşluk, #, satır sonu veya tırnak içeren her karakter dizisi, güvenle gidip gelebilmesi için otomatik olarak çift tırnaklanıp kaçışlanır. İç içe nesneler ve diziler düz bir dosyada yaşayamaz; bu yüzden her biri bir JSON karakter dizisine seri hale getirilir ve bir uyarıyla işaretlenir. İsteğe bağlı anahtarlar, anahtarları UPPER_SNAKE_CASE’e normalleştirir ve bir export öneki ekler. JSON’dan ENV’e Dönüştürücü tüm bunları halleder.

Gidip gelme güvenliği ve iç içe yapı uyarısı

Otomatik tırnaklama, bir değerin .env → JSON → .env döngüsünden değişmeden sağ çıkması için vardır. Aşağıda dönüştürücülerin davranışıyla eşleşen, çalıştırılabilir kod halinde bir gidip gelme örneği var; PORT’un döngü boyunca, tam olarak dotenv’in yükleyeceği gibi bir karakter dizisi olarak kaldığına dikkat edin:

import { parse } from 'dotenv';

// 1. Start with a .env file as text
const envText = `DATABASE_URL=postgres://user:pass@localhost:5432/mydb
PORT=8080
GREETING="Hello, World"
NOTE="value with # hash"`;

// 2. .env -> JSON (dotenv.parse returns string values only)
const config = parse(envText);
console.log(JSON.stringify(config, null, 2));
// {
//   "DATABASE_URL": "postgres://user:pass@localhost:5432/mydb",
//   "PORT": "8080",
//   "GREETING": "Hello, World",
//   "NOTE": "value with # hash"
// }

// 3. JSON -> .env (quote only strings that need it)
const needsQuotes = (s) => /[\s#"'\n]/.test(s);
const env = Object.entries(config)
  .map(([key, value]) =>
    needsQuotes(value) ? `${key}=${JSON.stringify(value)}` : `${key}=${value}`
  )
  .join('\n');

console.log(env);
// DATABASE_URL=postgres://user:pass@localhost:5432/mydb
// PORT=8080
// GREETING="Hello, World"
// NOTE="value with # hash"

İşin püf noktası iç içe yapıdır. Gidip gelme, düz yapılandırma için kayıpsızdır ama derin biçimde iç içe bir yapı, .env’den ancak opak JSON karakter dizileri olarak geçebilir; yapıyı geri bekleyen hiçbir uygulama bunu okuyamaz. Yapılandırmanız gerçekten hiyerarşikse, bunun yerine YAML’a uzanın. YAML’dan JSON’a Dönüştürücü ve YAML Norway Sorunu kılavuzu bu yolu ve kendine özgü keskin kenarlarını kapsar.

Ortam yapılandırmasını doğrulama

Eksik ya da bozuk biçimli bir yapılandırma değişkeni, üretimde sabaha karşı 3’te bir undefined is not a function olarak yüzeye çıkmamalıdır. On İki Faktörlü yaklaşım hızlı başarısız olmaktır: yapılandırmayı dağıtımdan sonra değil, önce denetleyin. .env’i JSON’a dönüştürmek bunu pratik kılar, çünkü JSON’un, çıplak ortam değişkenlerinde olmayan olgun doğrulama araçları vardır.

CI’da şemayla doğrulama

.env → JSON dönüştürün, sonra JSON’u; gerekli anahtarları, izin verilen enum’ları ve değer biçimlerini bildiren bir şemaya göre doğrulayın. Yanlış yapılandırılmış bir ortam (eksik bir DATABASE_URL, geçersiz bir LOG_LEVEL, sayı olmayan bir port) dağıtım yerine CI denetiminde başarısız olur. JSON Schema doğrulama kılavuzu şemayı yazmayı adım adım anlatır ve JSON Schema Doğrulayıcı onu tarayıcıda çalıştırır.

Türlü yapılandırma

Varlık denetimlerinin ötesinde, process.env.PORT’un kod tabanına yayılmış, türsüz bir karakter dizisi olmaması için türlü bir yapılandırma nesnesi türetebilirsiniz. Zod gibi bir çalışma zamanı şema kitaplığıyla başlangıçta doğrulayıp dönüştürün ya da JSON’dan bir TypeScript arabirimi üretip yapılandırmayı onun üzerinden okuyun. JSON’dan TypeScript’e kılavuzu ve JSON’dan TypeScript’e Dönüştürücü üretim adımını kapsar. Yapısal bir sürprizin erken yüzeye çıkması için JSON’u önce JSON Biçimlendirici ile güzel biçimlendirin veya sağlamasını yapın.

Gizli bilgi hijyeni: bir .env’i güvenle ele almak

Bir .env, işlevsel olarak bir kimlik bilgileri listesidir. Ona öyle davranın.

.env’i asla işlemeyin. Onu .gitignore’a ekleyin. Her anahtarı boş veya yer tutucu değerlerle listeleyen bir .env.example işleyin; gerçek bağlantı dizesi yerine DATABASE_URL= yazın. O dosya ekibin sözleşmesidir: yeni bir kopyanın hangi değişkenlere ihtiyaç duyduğunu, hiçbirini sızdırmadan belgeler.

.env, yerel ve geliştirme içindir; üretim bir gizli bilgi yöneticisi kullanır. Vault, Doppler ve AWS Secrets Manager gibi araçlar, gizli bilgileri dağıtım zamanında ortama enjekte eder. Canlı gizli bilgilerle gerçek bir .env’i bir üretim ana makinesine göndermeyin; bunun yerine onları yöneticiden çekin ki sızdırılan bir dosya veya yanlış yapılandırılmış bir kapsayıcı anahtarlarınızı ele vermesin.

Gizli bilgileri yalnızca tarayıcı içinde çalışan bir araçta dönüştürün. Gerçek bir .env’i sunucu tarafında çalışan bir dönüştürücüye yapıştırmak, kimlik bilgilerinizi ağ üzerinden başkasının makinesine gönderir. Buradaki dönüştürücülerin ikisi de tamamen tarayıcınızda çalışır; DevTools Ağ sekmesini açın ve yapıştırmanın sıfır istek tetiklediğini doğrulayın. Sterilize edilmiş bir örnek yerine gerçek bir üretim .env’ini dönüştürmeyi güvenli kılan fark işte budur.

SSS

Bir .env dosyasını JSON’a nasıl dönüştürürüm?

Dosyayı .env’den JSON’a Dönüştürücü aracına yapıştırın; tarayıcınızda anında JSON’a ayrıştırılır. Her KEY=VALUE satırı bir özellik olur. Değerler varsayılan olarak karakter dizisidir (dotenv ile eşleşir); sayı ve mantıksal değer istiyorsanız tür çıkarımını açın. Hiçbir şey yüklenmez, dolayısıyla gerçek gizli bilgiler cihazınızda kalır.

.env değerleri sayı ve mantıksal değer mi, yoksa karakter dizisi mi?

Her zaman karakter dizisi. dotenv türleri asla dönüştürmez; çalışma zamanında her process.env değeri bir karakter dizisidir, dolayısıyla PORT=8080, "8080"’dir ve DEBUG=false, "false" karakter dizisidir (ki bu doğru/truthy’dir). Herhangi bir “türleri çıkarsa” seçeneği, standardın üzerine eklenen bir kolaylık katmanıdır, dotenv’in kendisinin parçası değil.

Bir .env dosyası ile bir JSON yapılandırma dosyası arasındaki fark nedir?

Bir .env düz, yalnızca karakter dizisi içeren, yoruma elverişlidir ve gizli bilgiler ile ortam başına geçersiz kılmalar için yapılmıştır. JSON ise iç içe ve türlüdür; gerçek sayılar, mantıksal değerler ve null içerir ve bir şemaya göre doğrulanır, ama yorumları yoktur ve yanlışlıkla işlenmesi kolaydır. Gizli bilgiler için .env’i, yapılandırılmış konfigürasyon için JSON’u kullanın.

Bir .env dosyası iç içe veya gruplanmış değerler içerebilir mi?

Hayır. Bir .env, iç içe yapı ve dizi içermeyen, düz bir KEY=VALUE çiftleri listesidir. Gruplamayı ifade etmek için onu bir önek geleneğiyle düzleştirin (bir db nesnesi yerine DB_HOST ve DB_PORT) ve yapıyı kodda yeniden kurun. Gerçekten hiyerarşiye ihtiyacınız varsa JSON veya YAML kullanın.

.env içinde tırnaklar, # ve çok satırlı değerler nasıl ele alınır?

Çift tırnaklar kaçış dizilerini işler (\n, \t, \\, \") ve kapatan tırnağa kadar birden çok satıra yayılabilir. Tek tırnaklar kaçış dizisi olmadan birebirdir. Tırnaksız değerler satır sonuna kadar uzanır, sondaki boşlukları kırpar ve bir boşluk artı #’i satır içi yorum olarak ele alır; bu yüzden meşru biçimde bir # içeren her değeri tırnaklayın.

.env dosyamı Git’e işlemeli miyim?

Hayır. .env’i .gitignore’a ekleyin ve bunun yerine anahtarları boş değerlerle listeleyen bir .env.example işleyin. Gerçek dosya veritabanı parolaları, API anahtarları ve token’lar barındırır; onu işlemek, kimlik bilgilerini geçmişinize sızdırır ve dosyayı silseniz bile orada kalmaya devam ederler.