Node.js --env-fileでdotenvなしに.envファイルを読み込む方法

問題

Node.jsプロジェクトでは毎回dotenvパッケージをインストールし、エントリーポイントにrequire('dotenv').config()を書くのが定番でした。しかしこれは結局、ランタイムでファイルを読み込んでパースする依存関係が一つ増えるということです。

解決方法

Node.js 20.6以降、--env-fileフラグが組み込まれています。

# 基本的な使い方
node --env-file=.env app.js

# 複数ファイルも可能
node --env-file=.env --env-file=.env.local app.js

.envファイルの形式は従来と同じです。

DATABASE_URL=postgresql://localhost:5432/mydb
API_KEY=sk-1234567890
NODE_ENV=development

コードではprocess.envでそのままアクセスできます。require('dotenv')のようなコードは不要です。

// dotenvのインポートなしでそのまま使用
const dbUrl = process.env.DATABASE_URL;
console.log(dbUrl); // postgresql://localhost:5432/mydb

Node.js 20.12以降はプログラム的な読み込みも対応しています。

// ランタイムで動的に読み込み
process.loadEnvFile('.env');

// 文字列から直接パース
const { parseEnv } = require('node:util');
const vars = parseEnv('KEY=value\nFOO=bar');
console.log(vars.KEY); // "value"

package.jsonのスクリプトもすっきりします。

{
  "scripts": {
    "dev": "node --env-file=.env --watch app.js",
    "prod": "node --env-file=.env.production app.js"
  }
}

ポイント

• Node.js 20.6+の--env-fileフラグで.envをネイティブに読み込めます
• dotenvパッケージのインストールもrequireコードも不要です
• 20.12+ではprocess.loadEnvFile()で動的読み込みも可能です
• 複数のenvファイルを順番に読み込め、後のファイルが前のファイルを上書きします
• Node.js 20未満のバージョンでは引き続きdotenvが必要です