HN 日本語サマリー

← 一覧へ戻る
プログラミング

.env ファイルの問題点

Where .env Went Wrong (secretspec.dev)

79 pointsby domenkozar58 コメント

要約

この記事は、ソフトウェア開発で広く使われている`.env`ファイル形式が、環境変数を扱う上で多くの問題を抱えていると指摘しています。`.env`ファイルは、環境変数をプロセスに渡すという単一の機能を便利に拡張しましたが、設定スキーマの定義、機密情報の管理、環境モデルの表現といった、より複雑な要件を満たすには不十分であり、結果としてコードやドキュメントの不整合、セキュリティリスク、管理の複雑化を招いていると論じています。

全文翻訳

なぜ .env はうまくいかなかったのか

2026年7月30日

.env はソフトウェアにおける最も成功した事故の一つです。

それは3つの export コマンドのショートカットとして始まります。そして、プロジェクトの設定スキーマ、シークレットストア、環境モデル、オンボーディングガイド、CIインターフェース、デプロイメントフォーマットへと進化します。

環境変数は一つの仕事をうまくこなします:文字列をプロセスに渡すこと。.env はその配信メカニズムを「真実の情報源」に変えてしまいました。

利便性がアーキテクチャになったのです。そこに .env がうまくいかなかった理由があります。

環境変数は値を提供するだけ

「環境変数は値を提供するだけ」というセクション

環境変数は、実行中のプロセスに値を取り込むという小さな問題を解決します。アプリケーションは、開発者、CIシステム、あるいはシークレットマネージャーが供給したかに関わらず、DATABASE_URL を読み取ることができます。

.env ファイルは、それらの値を保存し再ロードすることを容易にします。これは便利です。しかし、チームはアプリケーションが必要とするものを記述するためにもこのファイルを使用します。KEY=value という形式では、値が必須なのか、オプションなのか、コミットしても安全なのか、本番環境でのみ利用可能か、あるいは特定のサービスに限定されているのかを伝えることができません。

これらの要件は、どのプロセスや開発者のラップトップよりも長く存続します。それらは永続的なプロジェクト宣言に属するべきです。.env は配信のために値を保存しますが、アプリケーションのシークレットモデルを定義することはできません。

文字列はスキーマではない

「文字列はスキーマではない」というセクション

典型的な例を見てみましょう:

DATABASE_URL=REDIS_URL=redis://localhost:6379STRIPE_API_KEY=DEBUG=false

このファイルは、答えるよりも多くの疑問を投げかけます。空の値は必須またはオプションを意味するのでしょうか? REDIS_URL は開発用のデフォルト値でしょうか? STRIPE_API_KEY は本番環境限定でしょうか? DEBUG はブール値でしょうか?

Dotenv はそれらの答えをエンコードできません。Node.js はすべての値が文字列になると文書化しています。ブール値に関するdotenv の issue(2015年にオープン)は、"false" が truthy であることに驚く開発者からのリアクションを集め続けています。

チームは不足している情報を他の場所に置きます:バリデーションコード、README、.env.example、あるいはチームメイトの記憶。これらのソースは乖離していきます。

また、このファイルは DEBUG と STRIPE_API_KEY を同等に見せてしまいます。一方は Git に含めるべき通常のセッティングですが、もう一方は権限を付与し、アクセス制御とローテーションが必要です。これらを混在させると、ファイル全体が機密性の高いものになります。

明示的な宣言がない場合、欠落した値は遅延して失敗します:コードがそれらを使用しようとしたときに初めてアプリケーションがそれらを発見します。

そしてファイルは増殖し始める

「そしてファイルは増殖し始める」というセクション

新しい要件は通常、別のファイルを作成します:

.env.env.local.env.development.env.development.local.env.test.env.production

ファイル名が環境モデルになります。接尾辞はスコープを定義し、ロード順序は継承を定義し、ファイルをコピーすることがデプロイメントになります。

これはTwelve-Factor App の指針を逆転させます。その意図は、環境変数が独立した制御であるべきだということでした。なぜなら、デプロイメントが増えるにつれて名前付き環境は脆くなるからです。.env.production は、ファイル名でそのグループ化を再作成します。

今や、新しい値はすべて .env.example に追加し、README に文書化し、コードで検証し、適切な実際のファイルにコピーする必要があります。一つでも漏らすと、環境は乖離します。

.env の仕様は存在しない

「.env の仕様は存在しない」というセクション

.env は標準化されているように見えますが、各パーサーは独自のフォーマットを定義しています。Node.js は正式な仕様の欠如を文書化しており、python-dotenv も同様です。各ローダーは独自の選択をします。

python-dotenv は ${NAME} を展開しますが、$NAME は展開しません。Node dotenv は変数展開を別のツールに委譲します。Docker Compose は独自のシェル風演算子をサポートします。Vite は逆順の参照もサポートし、その後、同じ式がシェルや Docker Compose では機能しないと警告します。

コメントや引用符も異なります。Node dotenv はバージョン15で、引用符なしの値における # の意味を破壊的変更として変更しました。ある devenv ユーザーは、引用符がエクスポートされたキーの一部になったと発見しました(devenv の issue #1333)。

どの値が優先されるか?

「どの値が優先されるか?」というセクション

パーサーは優先順位についても意見が一致しません。Node dotenv は通常、最初のファイルが優先されます。Docker Compose は最後の env_file を優先し、その後 environment セクションがそれを上書きします。Vite は、既存のプロセス変数をファイルよりも優先します。

Docker Compose は、2つの似た名前のオプションに異なる動作を与えます。env_file: はコンテナに変数を供給しますが、compose.yaml の補間には使用しません。docker compose --env-file は補間に影響します。設計通りとしてクローズされた issue で、メンテナーはそのオプションの名前が不運にも選ばれたと説明しました。

.env を最初にロードしたのは誰か?

「.env を最初にロードしたのは誰か?」というセクション

優先順位はタイミングにも依存します。Node dotenv のES モジュールに関するガイダンスは、インポートされたモジュールが初期化中に環境を読み取る場合に特別な処理が必要です。Vite は、Bun の自動 .env ロードがVite 自身のロード順序に干渉する可能性があると警告します。VITE_* 値はビルド時に置き換えられ、クライアントバンドルの一部になります。

同じ行が、実行時シークレット、ビルド時定数、または公開ブラウザ値になる可能性があります。ローダーはタイミングとコンテキストに基づいて決定します。

その時点で .env は、ファイル名、フラグ、作業ディレクトリ、親プロセス、ライブラリバージョンにまたがる制御フローを持つ、小さなプログラムのように動作します。

無視されたファイルもファイルである

「無視されたファイルもファイルである」というセクション

dotenv プロジェクトは、.env をコミットしないようにと述べています。.gitignore は一つの事故を防ぎます。しかし、暗号化、アクセス制御、監査、失効を追加するわけではありません。

ファイルはエディタのバックアップ、チャットメッセージ、アーカイブ、サポートバンドル、コンテナビルドコンテキスト、古いラップトップに紛れ込む可能性があります。ある devenv 統合は、.env の内容を Nix ストアにコピーすると報告されました(devenv の issue #1694)。そこではパスは機密ではありません。開発者が退職する際、ファイルのアクセス権限を revocation する方法がありません。彼らが受け取った各認証情報は、個別のコピーになります。

1Password、Vault、クラウドシークレットマネージャー、またはシステムキーリングに保存されたシークレットでさえ、dotenv ベースのアプリケーションが使用できるようにするには、プレーンテキストにコピーする必要があります。ローカルコピーは、元のものよりも管理機能が劣ります。

環境変数配信にも限界があります。Docker は管理されたシークレットをファイルとしてマウントします。なぜなら、環境変数はコンテナ間で漏洩する可能性があるからです。また、プロセスは一つのグローバルマップを取得するため、フロントエンドビルド、ワーカー、マイグレーション、Web サービスは、それぞれが数個のシークレットしか必要としない場合でも、同じシークレットを受け取ることがよくあります。Dotenv にはそのスコープを表現する方法がありません。

.env を再び小さくする

「.env を再び小さくする」というセクション

.env の有用な部分は、「このアプリケーションは値が必要だ」から「アプリケーションは実行できる」までの短いパスです。

KEY=value を期待するツールのためのアダプターとして、あるいは通常のローカル設定に使用してください。プロジェクトの要件を定義したり、シークレットの永続的なコピーを保存したり、ファイル名で環境をエンコードしたり、どのサービスがどの値を受け取るかを決定したりするために使用しないでください。

堅牢な設計は3つのジョブを分離します:

  • コミットされた宣言は、アプリケーションが必要とするシークレットを記述します。
  • 保護されたストレージは、誰がその値にアクセスできるかを制御します。
  • 明示的な配信は、各プロセスに必要な値のみを提供します。

これにより、各部分が独立して変更できるようになります。チームは、アプリケーションを書き直すことなくストレージを変更したり、起動前に要件を検証したり、各コンポーネントを独自のシークレットに限定したりできます。

SecretSpec はこれをどのように適用するか

「How SecretSpec applies this」というセクション

SecretSpec は、コミットしても安全なファイルに宣言を配置します:

[project]name = "payments"revision = "1.0"[profiles.default]DATABASE_URL = { description = "Postgres connection string" }REDIS_URL = { description = "Redis connection string", required = false }STRIPE_API_KEY = { description = "Stripe API key" }[profiles.development]REDIS_URL = { default = "redis://localhost:6379" }

このファイルは、シークレット値を含まずに、要件、デフォルト、説明を記録します。プロバイダーは値の保存場所を選択し、プロファイルは要件の実際の違いを記述します。

既存のプログラムは、コード変更なしで SecretSpec を採用できます:

$ secretspec run -- ./server

このコマンドは、解決されたシークレットを子プロセスの環境に注入します。これは移行中に役立ちますが、推奨される統合はSecretSpec SDKです。

SDK を使用すると、アプリケーションは宣言を直接解決します。これにより、secretspec run が使用する環境変数による引き渡しがなくなります。キーリング、パスワードマネージャー、または Vault に保存された値は、グローバルプロセス環境に入ることはありません。ファイルベースの配信を必要とするアプリケーションは、代わりに一時ファイルを受け取ることができます。スコープ (0.17+)により、各コンポーネントは宣言したシークレットのみを解決できます。

移行は段階的に行うことができます。SecretSpec は既存のファイルから宣言を初期化します:

$ secretspec init --from dotenv:.env

これは値をコピーせずに名前をコピーします。現在のファイルは、移行期間中プロバイダーとして残すことができます:

$ secretspec check --provider dotenv:.env
$ secretspec run --provider dotenv:.env -- ./server

その後、アプリケーションが読み取る名前を変更せずに、値をシステムキーリング、パスワードマネージャー、Vault、または別のプロバイダーに移動できます。

.env は、通常のローカル設定のためにそのまま使用できます。既存のアプリケーションは、移行中に環境変数配信を維持できます。SDK またはファイルベースの配信を使用するアプリケーションは、プロセス環境からシークレットを削除できます。

SecretSpec は、シークレットのための環境変数を完全に排除することを目指しています。