Berkas Environment dengan --env-file

Chapter Manajemen Secret telah memperkenalkan flag --env-file sebagai cara menjauhkan nilai penting dari kode — kini saatnya membedahnya sebagai alat konfigurasi yang utuh. Aplikasi nyata jarang hidup dalam satu lingkungan saja: nilai pengembangan berbeda dari produksi, dan mengetik export satu per satu di terminal adalah undangan untuk salah. Berkas environment menyelesaikan keduanya sekaligus: konfigurasi tertulis, mudah diganti per lingkungan, dan dimuat oleh satu flag tanpa library. Pada chapter ini kita membaca aturan penulisannya baris demi baris — tanda kutip, nilai kosong, awalan export, nilai multibaris — lalu melihat perilakunya ketika berkas tidak ditemukan.

Dua Lingkungan, Dua Berkas #

Bahan kita satu aplikasi kecil yang membaca dua variabel: MODE dan NAMA_APLIKASI:

console.log('MODE         :', process.env.MODE ?? '(tidak diatur)');
console.log('NAMA_APLIKASI:', process.env.NAMA_APLIKASI ?? '(tidak diatur)');

Tanpa berkas apa pun, keduanya kosong. Sekarang dua berkas konfigurasi — satu untuk pengembangan, satu untuk produksi:

# Nilai lingkungan pengembangan
MODE=pengembangan
NAMA_APLIKASI=Toko Latihan (dev)

# Nilai lingkungan produksi
MODE=produksi

Jalankan aplikasi yang sama dengan berkas yang berbeda:

node --env-file=pengembangan.txt lingkungan.mjs

Output yang Dihasilkan:

MODE         : pengembangan
NAMA_APLIKASI: Toko Latihan (dev)

node --env-file=produksi.txt lingkungan.mjs

Output yang Dihasilkan:

MODE         : produksi
NAMA_APLIKASI: (tidak diatur)

Kode tidak berubah sedikit pun; yang berubah hanya berkas yang disodorkan. Perhatikan pula bahwa NAMA_APLIKASI pada produksi.txt tidak dideklarasikan sama sekali — variabel yang tidak disebut berkas tidak dihapus ataupun diisi, melainkan dibiarkan apa adanya, sehingga nilai dari environment tetap berlaku untuknya. Pola ini persis yang dipakai platform deployment: berkas berisi nilai pengembangan sebagai bawaan, nilai rahasia produksi disuntikkan lewat environment, dan keduanya berdamai tanpa saling menimpa — aturan prioritasnya sudah kita buktikan pada Chapter Manajemen Secret.

Tata Cara Penulisan Berkas #

Format berkas environment terlihat bebas namun punya aturan yang tepat. Berkas latihan berikut sengaja memuat seluruh bentuk yang membingungkan:

# Konfigurasi latihan - seluruh nilai adalah placeholder
NAMA_APLIKASI=Toko Latihan
PESAN_SAMBUTAN="Selamat datang di toko kami"
PENANDA=`penanda aktif`
KOSONG=
export PENYEDIA=lokal
MULTIBARIS="baris pertama
baris kedua"

Pembacanya menampilkan nilai mentah setiap kunci setelah diproses Node:

const kunci = ['NAMA_APLIKASI', 'PESAN_SAMBUTAN', 'PENANDA', 'KOSONG', 'PENYEDIA', 'MULTIBARIS'];

for (const k of kunci) {
  const nilai = process.env[k];
  console.log(k.padEnd(15), ':', nilai === undefined ? '(undefined)' : JSON.stringify(nilai));
}

node --env-file=konfigurasi-latihan.txt baca-env.mjs

Output yang Dihasilkan:

NAMA_APLIKASI   : "Toko Latihan"
PESAN_SAMBUTAN  : "Selamat datang di toko kami"
PENANDA         : "penanda aktif"
KOSONG          : ""
PENYEDIA        : "lokal"
MULTIBARIS      : "baris pertama\nbaris kedua"

Mari kita petakan aturannya:

1. NAMA_APLIKASI=Toko Latihan: bentuk paling sederhana — seluruh teks setelah = menjadi nilai, spasi ikut dihitung.
2. PESAN_SAMBUTAN="...": nilai yang dibungkus kutip ganda kehilangan tanda kutipnya — pembungkus, bukan bagian nilai. Kutip tunggal '...' diperlakukan sama.
3. PENANDA=`penanda aktif` : backtick juga dikenali sebagai pembungkus — tiga jenis kutip sama kedudukannya.
4. KOSONG=: kunci tanpa nilai menjadi string kosong, bukan undefined — beda halnya dengan kunci yang tidak disebut sama sekali. JSON.stringify('') mencetak "", itulah yang terlihat pada keluaran.
5. export PENYEDIA=lokal: awalan export diterima dan dibuang — sehingga berkas .env hasil salin-tempel dari catatan export tetap bekerja.
6. MULTIBARIS="...": nilai dapat menjangkau beberapa baris selama pembungkusnya tidak ditutup — baris baru di dalamnya dipertahankan sebagai \n.
7. Baris # ...: komentar diabaikan.

Aturan lengkap — termasuk varian --env-file-if-exists yang memaafkan berkas yang hilang — terdokumentasi di referensi CLI Node.js .

Ketika Berkas Tidak Ada #

Kesalahan paling umum: nama berkas salah ketik, atau rekan tim belum menyalin .env contoh. Node memperlakukan ini sebagai galat serius, bukan peringatan:

node --env-file=tidak-ada.txt lingkungan.mjs
echo "kode keluar: $?"

Output yang Dihasilkan:

node: tidak-ada.txt: not found
kode keluar: 9

Proses menolak menyala dengan exit code 9 — kode yang oleh pipeline dari Section Deployment dan Operations langsung dibaca sebagai kegagalan. Sikap tegas ini disengaja: aplikasi yang diam-diam berjalan tanpa konfigurasinya lebih berbahaya daripada aplikasi yang menolak menyala, karena gejalanya baru muncul jauh di dalam sesi pengguna. Bila berkas memang opsional — misalnya berkas preferensi lokal yang tidak semua orang punya — barulah --env-file-if-exists menjadi pilihan yang tepat.

Ringkasan Perilaku #

Satu pengecualian pada baris terakhir patut dicatat bersama watch mode dari chapter sebelumnya: --watch memantau module graph, sedangkan berkas .env dibaca sekali saat proses menyala — mengubahnya tidak memicu restart. Menjalankan ulang tetap tugas kita. Berikutnya: satu flag modern lain yang mengubah cara kita memandang kepercayaan — Permission Model, penjaga yang membatasi apa saja yang boleh disentuh sebuah proses Node.js.