🔑

【脱・.env管理】dotenvxで環境変数を安全かつスマートに管理しよう！

2025/03/31に公開

Git

Webアプリケーション開発において、APIキーやデータベースの接続情報などの機密情報を扱うことは避けられません。これらの情報は、ハードコーディングせずに環境変数として管理するのが一般的です。

従来、.envファイルを使って環境変数を管理する方法が広く使われてきました。しかし、.envファイルには以下のような課題がありました。

誤ってリポジトリにコミットしてしまうリスク: 機密情報が漏洩する可能性があります。
チームでの安全な共有が難しい: どうやってメンバーに.envファイルの内容を渡すか？
環境ごとの管理が煩雑: 開発環境、ステージング環境、本番環境で異なる設定をどう管理するか？

これらの課題を解決するために登場したのが dotenvx です！

dotenvxは、従来のdotenvのシンプルな使い勝手はそのままに、セキュリティとチーム開発のための機能を大幅に強化したツールです。

この記事では、dotenvxの基本的な使い方から、チーム開発で役立つ便利な機能までを解説します。

dotenvxとは？

dotenvx は、一言で言うと「進化したdotenv」です。主な特徴は以下の通りです。

クロスプラットフォーム・言語非依存: Node.jsだけでなく、Python, Ruby, Go, Rustなど様々な言語やフレームワークで利用可能。
.envファイルの暗号化: .envファイルを暗号化し、安全にリポジトリにコミットできる.env.vaultファイルを生成。
環境ごとの管理: .env.development, .env.production のように環境別のファイル管理をサポート。
バリデーション: .env.exampleファイルと比較し、必要な環境変数が定義されているかチェック。
dotenvからの簡単な移行: 既存の.envファイルもそのまま利用可能。

dotenvxのインストール

dotenvxは様々な方法でインストールできます。

1. npm/yarn/pnpm (Node.jsプロジェクト):

# npm
npm install --save-dev @dotenvx/dotenvx

# yarn
yarn add --dev @dotenvx/dotenvx

# pnpm
pnpm add -D @dotenvx/dotenvx

2. curl (グローバルインストール):

macOS, Linux, WSLなどでは、以下のコマンドでシステム全体にインストールできます。

curl -sfS https://dotenvx.com/install.sh | sh

3. Homebrew (macOS):

brew install dotenvx/brew/dotenvx

どの方法でインストールしても基本的な使い方は同じですが、プロジェクトごとに管理したい場合はnpm/yarn/pnpm、システム全体で使いたい場合はcurlやHomebrewが便利です。この記事では、コマンドラインで直接 dotenvx コマンドを実行する前提で解説します（npm等でインストールした場合は npx dotenvx ... のように実行してください）。

基本的な使い方: `dotenvx run`

dotenvxの最も基本的な使い方は、dotenvx runコマンドです。これは、.envファイルを読み込んでから指定したコマンドを実行するものです。

1. .envファイルの作成:

まず、プロジェクトのルートディレクトリに.envファイルを作成し、環境変数を記述します。

# .env
DATABASE_URL="postgresql://user:password@host:port/db"
API_KEY="YOUR_SUPER_SECRET_API_KEY"
NODE_ENV="development"

2. dotenvx runでコマンドを実行:

アプリケーションの起動コマンドの前に dotenvx run -- を付けます。

# 例: Node.jsアプリを実行する場合
dotenvx run -- node index.js

# 例: Pythonスクリプトを実行する場合
dotenvx run -- python main.py

これで、index.jsやmain.pyからは、process.env.DATABASE_URL (Node.js) や os.environ.get('API_KEY') (Python) のようにして、.envファイルに定義した環境変数を読み込むことができます。

注意: .envファイルは機密情報を含むため、必ず.gitignoreに追加して、リポジトリにコミットしないようにしましょう！

# .gitignore
.env

dotenvxの主要機能

ここからは、dotenvxをより強力にする主要な機能を見ていきましょう。

1. `.env.vault`による暗号化と安全なコミット

dotenvxの最大の特徴の一つが、.envファイルを暗号化して.env.vaultというファイルに保存する機能です。これにより、機密情報を含まない形で環境設定をリポジトリにコミットできます。

a. 暗号化の実行:

dotenvx encryptコマンドを実行します。

dotenvx encrypt

実行すると、以下が行われます。

.envファイルの内容が暗号化され、.env.vaultファイルが生成されます。
復号化に必要なキー情報を含む.env.keysファイルが生成されます。この.env.keysファイルは絶対にリポジトリにコミットしないでください！
.envファイル自体は変更されません（引き続きローカルでの開発に使用できます）。

.env.vaultファイルの中身は、どの環境変数（例: DATABASE_URL）がどの環境（例: development, production）で使われるか、そしてその暗号化された値が含まれます。

# .env.vault (例)
# Comment explaining the vault format
DOTENV_VAULT_DEVELOPMENT="..." # 暗号化された開発環境の値
DOTENV_VAULT_PRODUCTION="..." # 暗号化された本番環境の値
# ... 他の環境 ...

b. .gitignoreの設定:

.env.keysと、ローカル用の.envファイルはコミットしないように設定します。一方、.env.vaultはコミットします。

# .gitignore
.env
.env.*.local # ローカルオーバーライド用ファイル
.env.keys

c. 復号化と実行:

dotenvx runは、実行時に.env.vaultを自動的に認識し、復号化を試みます。復号化には**DOTENV_KEY**という環境変数が必要です。

DOTENV_KEYは、.env.keysファイルに記載されています。通常、以下のような形式です。

# .env.keys
DOTENV_KEY_DEVELOPMENT="dotenv://:key_1234@dotenvx.com/vault/.env.vault?environment=development"
DOTENV_KEY_PRODUCTION="dotenv://:key_5678@dotenvx.com/vault/.env.vault?environment=production"

実行したい環境に対応するDOTENV_KEYを環境変数として設定してからdotenvx runを実行します。

# 開発環境のキーを設定して実行
export DOTENV_KEY="dotenv://:key_1234@dotenvx.com/vault/.env.vault?environment=development"
dotenvx run -- node index.js

# または、コマンドの前に直接指定
DOTENV_KEY="dotenv://:key_1234@dotenvx.com/vault/.env.vault?environment=development" dotenvx run -- node index.js

CI/CD環境や本番環境では、このDOTENV_KEYをシステムの環境変数やSecrets Managerなどで安全に設定します。

2. 環境ごとの管理 (`.env.[environment]`)

開発、テスト、本番など、環境ごとに異なる設定を使いたい場合があります。dotenvxはこれを簡単に実現します。

.env.development: 開発環境用の設定
.env.production: 本番環境用の設定
.env.test: テスト環境用の設定

これらのファイルを作成し、それぞれの環境に応じた値を記述します。

# .env.development
DATABASE_URL="postgresql://dev_user:dev_pass@localhost:5432/dev_db"
API_KEY="DEV_API_KEY"

# .env.production
DATABASE_URL="postgresql://prod_user:prod_pass@prod_host:5432/prod_db"
API_KEY="PROD_API_KEY"

dotenvx runは、デフォルトで.envと.env.developmentを読み込みます（NODE_ENV=developmentの場合）。他の環境ファイルを明示的に読み込むには-fオプションを使います。

# 本番環境の設定で実行 (-f オプション)
dotenvx run -f .env.production -f .env -- node index.js

# NODE_ENV を設定して実行 (NODE_ENV=production であれば .env.production が優先される)
NODE_ENV=production dotenvx run -- node index.js

環境変数の読み込み優先順位は以下のようになります（後から読み込まれたものが優先されます）。

.env
.env.[environment] (例: .env.development)
.env.local (ローカル環境でのみ上書きしたい場合。.gitignore推奨)
.env.[environment].local (特定の環境のローカル上書き。.gitignore推奨)

3. チームでの共有

.env.vaultを使うことで、環境設定自体は安全にGitリポジトリ経由で共有できます。問題は復号化キーであるDOTENV_KEYをどうやって安全に共有するかです。

パスワードマネージャー: 1PasswordやBitwardenなどで安全に共有。
社内Wikiやセキュアなチャット: アクセス制御が適切に行われているツールで共有。
インフラのSecrets Management: AWS Secrets Manager, Google Secret Manager, HashiCorp Vault などを使用。
dotenvx Hub (有料): dotenvxが提供するクラウドサービスを利用して、キー管理とメンバー間の共有をより簡単に行う方法もあります。

重要なのは、DOTENV_KEYをメールやSlackのパブリックチャンネル、Gitリポジトリなどで平文で共有しないことです。

4. バリデーション (`.env.example`)

チーム開発では、「新しいメンバーが必要な環境変数を設定し忘れた」「環境変数名が間違っていた」といった問題が起こりがちです。dotenvxは.env.exampleファイルを使ってこれを防ぎます。

プロジェクトルートに.env.exampleファイルを作成し、必要な環境変数名をリストアップします（値は空でもダミーでもOK）。

# .env.example
DATABASE_URL=
API_KEY=
SECRET_KEY=

dotenvx runを実行すると、dotenvxはロードされた環境変数と.env.exampleを比較し、不足している変数や.env.exampleに記載されていない余分な変数があると警告を出してくれます。

$ dotenvx run -- node index.js
info: ✅ loaded env from .env.development,.env
info: 🚨 missing keys (.env.example) [SECRET_KEY] # SECRET_KEYが不足しているという警告

これにより、設定漏れやタイポに早く気づくことができます。

dotenvxを使うメリットまとめ

セキュリティ向上: .env.vaultによる暗号化で、機密情報を含む設定ファイルを安全にバージョン管理できる。
チーム開発の効率化: 設定ファイルの共有が安全かつ容易になり、環境ごとの管理もシンプルに。
設定ミス・漏れの防止: .env.exampleによるバリデーションで、ヒューマンエラーを減らせる。
簡単な導入: 既存のdotenvワークフローからスムーズに移行可能。
多言語対応: 特定の言語やフレームワークに縛られずに利用できる。

まとめ

dotenvxは、現代の開発プロジェクトにおける環境変数管理の課題を解決するための強力なツールです。特に、セキュリティを重視する場合や、チームで開発を進める場合には、その恩恵を大きく受けられるでしょう。

これまで.envファイルの扱いに悩んでいた方は、ぜひdotenvxの導入を検討してみてください。より安全で効率的な開発体験が得られるはずです。

より詳しい情報や高度な使い方については、dotenvxの公式サイトを参照してください。

免責事項: 上記記事内のコマンドや設定は、一般的な使用例に基づいています。ご利用の環境や特定の要件に合わせて適宜調整してください。特にキー（DOTENV_KEY）の管理方法については、所属する組織のセキュリティポリシーに従ってください。

Discussion

ログインするとコメントできます