Node.js dotenv：安全地管理環境變數與敏感設定

在開發真實專案時，有些敏感資訊（如資料庫密碼、API 金鑰、Token）絕對不能直接放進程式碼中。環境變數 (Environment Variables) 讓我們能將「程式邏輯」與「環境配置」完全分離，這也是雲端原生應用（12-Factor App）的核心規範。

現代 Node.js 的新選擇：原生 --env-file

Node.js 20.6.0+ 版本起，已內建支援 .env 檔案解析，你不再需要安裝第三方套件！

如果你使用的是較新版本的 Node.js，建立 .env 後，只需在啟動時加上旗標：

node --env-file=.env index.js

程式中即可直接存取 process.env.MY_SECRET。

傳統主流：使用 dotenv 套件

對於 Node.js 20 以前的版本或需要更靈活配置的場景，dotenv 依然是社群標準。

npm install dotenv

1. 建立 .env 檔案 (專案根目錄)

PORT=3000
DATABASE_URL=mongodb://localhost:27017/shop
STRIPE_API_KEY=sk_test_51MzI...

2. 在程式載入配置

建議放在入口檔案（如 index.js 或 app.js）的最頂端：

// 儘早加載，確保後續執行的模組也能讀到環境變數
require('dotenv').config();

const port = process.env.PORT || 8080;
console.log(`伺服器將在埠口 ${port} 啟動`);
console.log(`連線字串：${process.env.DATABASE_URL}`);

進階：環境變數的驗證

讀取的環境變數一定是 字串。為了確保程式不會因為缺少關鍵變數而崩潰，推薦進行基本的驗證：

require('dotenv').config();

const config = {
  port: Number(process.env.PORT) || 3000,
  dbUrl: process.env.DATABASE_URL,
};

if (!config.dbUrl) {
  throw new Error('嚴重錯誤：未偵測到 DATABASE_URL 環境變數！');
}

專業開發規範與最佳實務

1. 嚴防洩漏：務必將 .env 加入 .gitignore。一旦上傳至 GitHub，請立即撤換所有金鑰。
2. 範本檔 (.env.example)：建立一個不帶真實數值的範本，讓團隊成員知道需要配置哪些變數。
3. 區分環境：使用 NODE_ENV 變數來切換邏輯。
   • NODE_ENV=development (開發)
   • NODE_ENV=production (正式)
4. 型別留意：記住 process.env.ENABLE_FEATURE = "false" 在布林判斷中會被視為 true (非空字串)，請務必落實字串比對或型別轉換。

總結

1. 安全性：環境變數是守護原始碼安全的最後一道防線。
2. 原生支援：Node.js 20.6+ 版本優先考慮使用 --env-file。
3. 維護性：透過 .env.example 建立團隊共識。