SOURCE GUIDE / DOTENVX

dotenvx

.env の値を読み込み、必要なら復号して、コマンドや Node.js のプロセスへ渡す。

1 — 何を担うか

ENV FILE → PROCESS ENV

dotenvx は、`.env` の変数をアプリに渡す CLI と Node.js ライブラリ。環境別ファイルの選択、暗号化された値の復号、コマンド実行をひとつのワークフローにまとめる。値を暗号化した `.env` はコードと共に管理できるが、復号に使う秘密鍵は別に保持する。

Source: v2.30.0CLI: dotenvx / dxLibrary: config()License: BSD-3-Clause

根拠: README.md「Usage」「Design」、package.json

2 — `run` の実行フロー

01 / SELECT

.env を選ぶ

-f、環境規約、またはデフォルトのファイルを解決する。

02 / RESOLVE

値を読む

ファイルを解析し、暗号化された値は利用可能な鍵で復号する。

03 / INJECT

環境を組み立てる

既存のプロセス環境と読み込んだ変数を優先規則に沿って統合する。

04 / EXECUTE

子コマンドを実行

-- より後のコマンドに環境変数を渡す。

echo 'HELLO=World' > .env
dotenvx run -- node index.js

区切りの --: オプションと実行コマンドを明確に分ける。コマンドがない場合、run はエラーを返す。

根拠: README.md「Run Anywhere」、src/cli/actions/run.js、src/lib/services/validate.js

3 — 複数環境の読み込み順

-f でファイルを指定できる。複数のファイルはカンマ区切りで並べる。通常は先に解決された値と既存の環境変数が優先される。--overload を付けると、後から読み込む値で上書きする。

指定	読み込み結果	用途
`-f .env.production`	指定したファイルを読む	環境を明示する
`-f .env.local,.env`	通常は先の `.env.local` が優先	ローカル設定を共通設定に重ねる
`-f .env.local,.env --overload`	後の `.env` が上書き	上書き順を切り替える
`--convention=nextjs`	`DOTENV_ENV`（なければ `NODE_ENV`）に応じ、`.env.<環境>.local` → `.env.local` → `.env.<環境>` → `.env` の順。test では `.env.local` を除く	フレームワークの慣習に合わせる

根拠: README.md「Multiple Environments」、src/lib/main.js

4 — 暗号化と鍵の分離

REPOSITORY

暗号化した .env

dotenvx encrypt は値を暗号文に変換する。公開鍵と暗号化した値は `.env` に置ける。

RUNTIME

復号用の秘密鍵

実行環境に秘密鍵を別経路で渡す。run は実行時に復号し、アプリへ変数を渡す。

dotenvx encrypt -f .env.production
DOTENV_PRIVATE_KEY_PRODUCTION="<private key>" dotenvx run -- node index.js

鍵の扱い: 暗号化した `.env` と秘密鍵を同じ公開範囲へ置かない。`.env.production` の鍵は DOTENV_PRIVATE_KEY_PRODUCTION で渡せる。鍵ファイルの初期値は .env.keys。

根拠: README.md「Encryption」、src/cli/actions/encrypt.js

5 — CLI と Node.js から使う

CLI

dotenvx run -- <command> は言語を問わず子プロセスへ変数を渡す。encrypt は `.env` の値を暗号化する。

Node.js API

require('@dotenvx/dotenvx').config() はアプリのプロセス環境へ値を読み込む。ESM 向けに @dotenvx/dotenvx/config も公開されている。

// Node.js のエントリポイント
require('@dotenvx/dotenvx').config()
console.log(process.env.HELLO)

run --redact は子コマンドの標準出力・標準エラーに現れる機密値を伏せるオプション。値の加工・変換後など、元の値と一致しない文字列は対象外なので、出力を転送・保存するときは表示結果を確認する。

根拠: README.md「Quickstart」、package.json、src/lib/main.js、src/cli/actions/run.js

6 — 参照先

dotenvx / dotenvx — このページで参照したソース（v2.30.0）

run.js — コマンド実行と変数注入

main.js — Node.js の config()

encrypt.js — 暗号化コマンド