dotenvxとは｜.envを暗号化してGitで安全に管理する仕組み・使い方・移行手順

dotenvxは、環境変数を記述した.envファイルを暗号化したままGitにコミットできる、dotenvの後継ツールです。従来のdotenvやpython-dotenvが「.envを読み込むだけ」だったのに対し、dotenvxは公開鍵暗号で値を保護し、秘密鍵を持つメンバーだけが復号できる仕組みを標準で備えます。この記事では、dotenvxの暗号化の仕組み（公開鍵・秘密鍵とsecp256k1）、encryptやrunといった基本的な使い方、複数環境の運用、AWS Secrets ManagerやSOPSとの使い分け、既存プロジェクトからの移行手順までを実務目線で解説します。あわせて、2024〜2025年前半の記事に残る旧.env.vault方式と現行仕様の違いも整理します。

まとめ：dotenvxが解決する.env管理の課題と導入判断のポイント

dotenvxを使う最大の理由は、これまでGit管理できなかった.envを「暗号化した状態でコミットできる」ようになる点にあります。秘密鍵DOTENV_PRIVATE_KEYを一度共有すれば、以降は変数が増えてもgit pullするだけで全員に反映され、Slackやチャットでの.env再配布が不要になります。新規プロジェクトであれば最初から導入する価値が高く、既存プロジェクトでもload_dotenv()を残したまま段階的に移行できます。

一方で、dotenvxはクラウドのSecrets Managerを完全に置き換えるものではありません。秘密鍵の管理という新たな責任が発生するため、チーム規模や監査要件によってはAWS Secrets Managerなどとの併用が現実的です。導入判断の軸は「.envをGitで一元管理したいか」「鍵の配布・保管を運用に組み込めるか」の2点に集約されます。詳細な根拠・手順は以降の各章で示します。

dotenvxの全体像｜dotenvの後継が備える暗号化・多言語対応・多環境管理

まずdotenvxがどのようなツールで、従来のdotenvと何が違うのかを俯瞰します。公式が掲げる「a secure dotenv」という位置づけと、3つの中核機能（暗号化・言語非依存・多環境）を押さえると、後続の仕組みや運用の話が理解しやすくなります。

dotenv作者が開発した「a secure dotenv」としての位置づけとv1.0登場の経緯

dotenvxは、広く使われている環境変数管理ライブラリdotenvの作者自身が開発した正式な後継ツールです。公式サイトのキャッチコピーは「a secure dotenv（安全なdotenv）」で、2024年6月24日にv1.0.0が公開されました。従来のdotenvが抱えていた弱点、特に.envファイルそのものの管理とデプロイ時の受け渡しを克服することを狙っており、単なる派生ライブラリではなく機能を大きく拡張した世代交代版という性格を持ちます。

コマンド一つで環境変数を注入するRun Anywhereの言語非依存設計

dotenvxは特定の言語ライブラリではなくCLIツールとして動作するため、dotenvx run -- の形でアプリの起動コマンドの前に付けるだけで環境変数を注入できます。これはNode.jsだけでなく、Python・Ruby・Go・Rust・PHPなど言語やフレームワークを問わず同じ操作で扱えることを意味します。公式が「Run Anywhere」と呼ぶこの設計により、言語ごとに異なる読み込みライブラリを覚える必要がなくなります。

.envを暗号化したままGitにコミットできる中核機能と.env.keysの鍵分離

dotenvx最大の特徴は、.envの各値を暗号化し、暗号文のままGitリポジトリにコミットできる点です。dotenvx encryptを実行すると.env内の値がencrypted:...という形式に置き換わり、復号に必要な秘密鍵だけが別ファイル.env.keysに切り出されます。つまり「設定の中身（暗号文）」と「復号する鍵」を物理的に分離し、前者だけをバージョン管理に乗せる、という発想です。

.env.developmentと.env.productionで実現する複数環境の出し分け

dotenvxは.env.developmentや.env.productionのように環境別ファイルを前提とした運用をサポートします。dotenvx run -f .env.production -- node index.jsのように-fで対象ファイルを指定すれば、開発・ステージング・本番の値を1つのリポジトリ内で安全に出し分けられます。環境ごとに鍵も分かれるため、本番の秘密鍵を開発メンバーに渡さずに運用するといった権限分離も可能です。

BSD-3-Clauseライセンスと活発な更新（最新v1.73.1）という採用判断の材料

採用を検討する際は、ライセンスとメンテナンス状況の確認が欠かせません。dotenvx（npmパッケージ名@dotenvx/dotenvx）のライセンスはBSD-3-Clauseで、商用利用しやすい寛容なライセンスです。更新も活発で、本稿執筆時点の最新版はv1.73.1（2026年6月更新）です。ライセンス種別はMITと誤記されることがあるため、導入時は公式リポジトリやnpmで実際のライセンス表記を確認することをおすすめします。

dotenvxの暗号化の仕組み｜公開鍵・秘密鍵とsecp256k1による安全性の根拠

「暗号化した.envをコミットして本当に大丈夫なのか」という不安は、仕組みを理解すれば解消できます。ここではdotenvxが採用する公開鍵暗号の流れと、その安全性がどこから来るのかを設計レベルで掘り下げます。

DOTENV_PUBLIC_KEYで暗号化しDOTENV_PRIVATE_KEYで復号する公開鍵方式

dotenvxは公開鍵暗号方式を採用しています。dotenvx encryptを実行すると暗号化用のDOTENV_PUBLIC_KEY（公開鍵）と復号用のDOTENV_PRIVATE_KEY（秘密鍵）のペアが生成されます。値の暗号化には公開鍵を使い、復号には秘密鍵を使うため、暗号化はチーム全員ができても復号は秘密鍵を持つ人だけ、という非対称な運用が成立します。

secp256k1とECIES方式が支える暗号化の解読耐性という安全性の根拠

鍵ペアの生成にはsecp256k1という楕円曲線が使われています。これはBitcoinの署名にも採用されている、十分に検証された曲線です。暗号化は楕円曲線暗号と共通鍵暗号を組み合わせたECIES方式で行われ、秘密鍵なしに暗号文だけから値を復元することは現実的な時間では不可能とされています。「暗号文がリポジトリに残っても、鍵がなければ意味を成さない」という前提が、コミット可能とする安全性の根拠です。

.envに同梱する公開鍵と.env.keysに保管する秘密鍵の役割分担

暗号化後、公開鍵DOTENV_PUBLIC_KEYは.envファイルの先頭に書き込まれます。公開鍵は名前のとおり公開しても問題がないため、暗号化済みの.envごとGitにコミットできます。一方、秘密鍵DOTENV_PRIVATE_KEYは.env.keysに保管され、こちらは絶対にコミットしてはいけません。役割を一言でまとめると、.env＝暗号文と公開鍵、.env.keys＝復号鍵、という分担です。

暗号化済みの.envをコミットしても安全な理由と.env.keys流出時のリスク

暗号化された.envを誤ってコミットしても、秘密鍵がなければ復号できないため実害は小さく、むしろ暗号化状態でコミットすることがdotenvxの正しい使い方です。逆に最も危険なのは.env.keysの流出で、これが漏れるとすべてのシークレットが復号可能になります。.env.keysは必ず.gitignoreに追加し、1Passwordなどの安全な場所で管理してください。

旧.env.vault方式からの仕様変更と古い解説記事との食い違いへの注意

注意したいのが、解説記事ごとに暗号化の説明が食い違う点です。2024年〜2025年前半の一部記事は、DOTENV_VAULT_DEVELOPMENTのような変数を持つ.env.vaultファイルに暗号文を書き出す旧方式を解説しています。しかし現行のdotenvxは、.envをその場で暗号化し.env.keysに秘密鍵を分離する方式が基本です。同様に「dotenvx decryptは未提供」という古い記述も現在は誤りで、復号コマンドは提供済みです。導入時は公式ドキュメントの現行仕様を基準に判断してください。

従来のdotenv・python-dotenvとの違い｜限界とdotenvxが解決する課題

dotenvxの価値は、従来ツールの限界と対比すると明確になります。ここではpython-dotenvやdotenv-railsといった既存ライブラリとの設計思想・運用コストの違いを整理します。

読み込むだけのpython-dotenvと暗号化前提のdotenvxの設計思想の差

従来のdotenv系ライブラリ（Node.jsのdotenv、python-dotenv、dotenv-railsによるRailsの環境変数管理など）は、平文の.envを読み込んでアプリの環境変数に展開することが役割でした。値の保護はスコープ外で、.envは各自がローカルに持つ前提です。これに対しdotenvxは「暗号化してGitで共有する」ことを設計の中心に据えており、出発点となる思想が根本的に異なります。

.envをGit管理できなかった従来課題と暗号化コミットによる解決

従来は機密を含む.envをコミットできないため、設定変更が「いつの間にか変わって動かない」「誰が変えたか分からない」状態になりがちでした。平文の認証情報を誤ってコミットして漏洩する事故も後を絶たず、実際にGitHubでの認証情報漏洩による不正アクセス事案のような被害も報告されています。dotenvxは暗号化した状態でコミットできるため、変更履歴をGitに残しつつ漏洩リスクを抑えられます。

言語ごとにライブラリを使い分ける運用とCLI一本で統一する違い

従来はNode.jsならdotenv、Pythonならpython-dotenv、RailsならRails向けgemと、言語ごとに別のライブラリと作法を覚える必要がありました。dotenvxはCLIツールであるため、どの言語のプロジェクトでもdotenvx run -- という同じ入口で扱えます。マイクロサービスのように複数言語が混在する環境ほど、この統一性の効果が大きくなります。

環境変数の追加・共有コストを下げる.env.keys共有モデルの効果

従来モデルでは、変数が1つ増えるたびに全員へ新しい.envを配り直す手間がありました。dotenvxでは一度.env.keysを共有してしまえば、その後に変数が追加・変更されてもメンバーはgit pullするだけで反映されます。鍵自体は変わらないため再配布が不要で、新規メンバーのオンボーディングコストも下がります。配るものが「都度の.env」から「最初の一度の鍵」に変わる点が本質的な違いです。

既存のload_dotenv運用から乗り換える際の互換性と平文運用の継続可否

移行のハードルは高くありません。dotenvx encrypt後も.envファイル自体は引き続きローカル開発に使えますし、Pythonのload_dotenv()を残したまま、起動をdotenvx run経由に変えるだけでも導入できます。またdotenvx setで特定の変数だけ平文のまま管理することも可能なため、公開して問題ない設定値は暗号化せずに運用するといった柔軟な使い分けができます。

dotenvxの導入と基本操作｜インストールからencrypt・run・多環境運用まで

ここからは実際の操作です。インストール、暗号化、実行、変数の追加、複数環境の切り替えという一連の流れを、具体的なコマンドとともに解説します。

npm・Homebrew・curlによるインストール手順と@dotenvx/dotenvxパッケージ

dotenvxは複数の方法でインストールできます。プロジェクトローカルに入れる場合はnpmでnpm install --save-dev @dotenvx/dotenvx、macOSならbrew install dotenvx/brew/dotenvx、グローバルにすばやく試すならcurl -sfS https://dotenvx.sh | shが使えます。npmで導入した場合はnpx dotenvx ...の形で呼び出します。

dotenvx encryptによる暗号化と生成される.env.keysのgitignore設定

暗号化はプロジェクトルートでdotenvx encryptを実行するだけです。実行すると.env内の値が暗号化され、公開鍵が.envに追記されると同時に、秘密鍵を含む.env.keysが生成されます。続けてecho ".env.keys" >> .gitignoreを実行し、秘密鍵をGit管理から確実に外してください。特定ファイルだけ暗号化したい場合はdotenvx encrypt -f .env.productionのように指定します。

dotenvx run — でアプリへ環境変数を注入する基本コマンドの形

暗号化した値をアプリに渡すにはdotenvx run -- を使います。たとえばNode.jsならdotenvx run -- node index.js、動作確認ならdotenvx run --quiet -- sh -c 'echo Hello $HELLO'のように書きます。dotenvxが自動的に.env.keysを見つけて暗号文を復号し、環境変数として注入してくれるため、アプリ側のコードを変更する必要はありません。

dotenvx setで個別変数を暗号化追加する操作と平文のまま残す使い分け

新しい変数を追加するときはdotenvx set が便利です。手動で.envに平文追記してから再度encryptしても結果は同じですが、setなら暗号化された状態で直接追加できます。逆に「環境ごとに変わるが公開しても問題ない値」は平文のまま残すこともできます。ただし、その後にdotenvx encryptを実行すると平文の変数まで一括で暗号化される点には注意が必要です。

-fオプションと_PRODUCTION・_CIサフィックスによる複数環境の切り替え

複数環境は-fと秘密鍵の命名規則で切り替えます。.env.productionを読み込むにはDOTENV_PRIVATE_KEY_PRODUCTION="<秘密鍵>" dotenvx run -- node index.jsのように、末尾を_PRODUCTIONとした環境変数を渡します。CI用なら_CIを使い、複数の鍵はカンマ区切りで同時に渡せます。サフィックスがdotenvxに「どのファイルを読むか」を指示する仕組みです。

他のシークレット管理手法との比較｜Secrets Manager・SOPS・direnvとの使い分け

dotenvxは万能ではなく、目的に応じて他の手法と使い分けるのが現実的です。クラウドのSecrets Manager、SOPS、direnv、パスワードマネージャーとの違いと、選定の判断軸を整理します。

AWSのSecrets Manager・Systems Managerとの責務の違い

AWSのSecrets Managerは、シークレットをクラウド側で中央管理し、アクセス制御や監査ログに加え、認証情報の自動ローテーションまで提供します。同じくAWS上で運用を一元化するSystems ManagerのSSM Agentによるインフラ管理のような仕組みと合わせ、これらは管理基盤をクラウド側へ寄せるアプローチです。これに対しdotenvxはリポジトリ内で完結し鍵管理が手元で済む手軽さが強みで、両者は責務が異なります。大まかな比較は以下のとおりです。

個人〜中規模やリポジトリ完結を重視するならdotenvx、監査・ローテーション要件が厳しいならクラウド側、という整理が出発点になります。

JSON/YAMLも暗号化できるSOPSとの適材適所の判断

SOPS（Secrets OPerationS）は.envに限らずJSONやYAMLも暗号化できる汎用ツールで、KubernetesのマニフェストやTerraform変数を暗号化したい場面に向きます。一方でdotenvxは.env＋CLI実行に特化しており、アプリの起動に環境変数を注入する用途では導入が簡単です。「.env中心ならdotenvx、設定ファイル全般の暗号化が必要ならSOPS」という棲み分けが判断基準になります。

ディレクトリ単位で環境を切り替えるdirenv・miseとの併用

direnvやmiseは、ディレクトリに入った際に環境変数を自動でロード・アンロードするツールで、暗号化が主目的ではありません。dotenvxで復号した値をdirenvの.envrc経由で読み込ませる、といった併用も実際に行われています。役割が競合しないため、「鍵で守るのはdotenvx、ディレクトリ単位の自動切り替えはdirenv/mise」と組み合わせると運用が安定します。

1Passwordなどパスワードマネージャーによる秘密鍵共有との組み合わせ

dotenvxで生成した.env.keysの秘密鍵をどう共有するかは運用上の要です。1PasswordやBitwardenのようなパスワードマネージャーで共有すれば、アクセス制御を効かせつつ安全に渡せます。メールやSlackのパブリックチャンネルでの平文共有は避けるべきで、dotenvx自体の暗号化と鍵の安全な共有はセットで考える必要があります。

チーム規模・対象ファイル・既存基盤から整理する選定の判断基準

最終的な選定は3つの軸で整理できます。1つ目はチーム規模と監査要件で、厳格ならクラウド側を主役にします。2つ目は対象ファイルで、.env中心ならdotenvx、設定全般ならSOPSです。3つ目は既存基盤で、すでにAWSを使い込んでいるならSystems ManagerやSecrets Managerとの統合が自然です。dotenvxはこれらと排他ではなく、開発時はdotenvx・本番はクラウド側、という併用構成も有効です。

本番・CI/CD・Dockerでの鍵管理と移行の実務｜運用上の注意点と多層防御

最後に、本番運用やCI/CD、Dockerでdotenvxを使う際の鍵の渡し方と、既存プロジェクトの移行手順を実務目線でまとめます。暗号化を過信しないための多層防御にも触れます。

本番デプロイでDOTENV_PRIVATE_KEYを環境変数として渡す方法

本番環境では、暗号化済みの.envをデプロイし、復号鍵DOTENV_PRIVATE_KEYを実行環境の環境変数として注入します。具体的にはDOTENV_PRIVATE_KEY="<秘密鍵>" dotenvx run -- node index.jsのように起動します。秘密鍵だけをサーバーの環境変数やシークレットストアに置けばよいため、本番サーバーに平文の.envを配置せずに済みます。

GitHub ActionsなどCIでの秘密鍵の保管とdotenvx runの組み込み

CI/CDでは、秘密鍵をGitHub ActionsのRepository Secretsなどに保存し、ジョブ実行時に環境変数として読み出します。ワークフロー内のビルドやテストのコマンドをdotenvx run -- npm testのように包めば、CI上でも暗号文を安全に復号して実行できます。CI専用に.env.ciとDOTENV_PRIVATE_KEY_CIを用意し、本番鍵と分離しておくと権限管理が明確になります。

Dockerコンテナでdotenvxを使う際の鍵の受け渡しと注意点

Dockerで使う場合は、イメージに秘密鍵を焼き込まず、コンテナ起動時に-e DOTENV_PRIVATE_KEY=...で渡すのが原則です。暗号化済み.envはイメージに含めても問題ありませんが、.env.keysはビルドコンテキストから除外します。Dockerfileの基本的な書き方と合わせて、.dockerignoreに.env.keysを追加する設定を忘れないようにしてください。

既存プロジェクトの移行手順｜暗号化から.env.keys退避・run切替の順序

既存プロジェクトの移行は順序が重要です。手順は次のとおりです。

1. 現在の.envをバックアップし、dotenvx encryptで暗号化する
2. 生成された.env.keysを.gitignoreに追加し、安全な場所へ退避する
3. アプリの起動をdotenvx run -- 経由に切り替える
4. 暗号化済み.envをコミットし、チームへ秘密鍵を共有する

この順序を守ることで、平文を履歴に残さず安全に移行できます。

暗号化に頼り切らない多層防御とシークレットスキャンとの併用

dotenvxは強力ですが、運用ミスはゼロにできません。.env.keysの誤コミットや平文での一時保存を検知するため、GitHub Advanced Securityのシークレットスキャンのような仕組みを併用すると安心です。暗号化（予防）と検知（発見）を組み合わせる多層防御の発想が、実運用での安全性を底上げします。

dotenvxに関するよくある質問

dotenvxの導入を検討する際によく挙がる疑問を、判断に役立つ形でまとめます。

dotenvxとdotenvはどちらを使うべきですか？

新規プロジェクトや、.envをGitで安全に共有したいチーム開発ではdotenvxが有力です。dotenvxはdotenvの後継として暗号化・多言語対応・多環境管理を備え、既存のdotenv系ライブラリからの移行も簡単だからです。一方、暗号化やGit共有が不要で、単に.envを読み込めればよい小規模な個人開発であれば、従来のdotenvでも十分です。「機密を含む.envを共有・バージョン管理したいか」を基準に選ぶとよいでしょう。

暗号化した.envはGitHubにコミットしても本当に安全ですか？

秘密鍵.env.keysを適切に管理している限り、暗号化済みの.envをコミットしても安全です。暗号化にはsecp256k1ベースの公開鍵暗号が使われており、秘密鍵がなければ暗号文から値を復元することは現実的にできません。むしろ暗号化した状態でコミットするのがdotenvxの正しい使い方です。ただし安全性は秘密鍵の管理に完全に依存するため、.env.keysは必ず.gitignoreに入れ、別の安全な場所で保管してください。

.env.keysを誤ってコミットしてしまった場合はどうすればよいですか？

速やかな対応が必要です。まずGitの履歴から該当ファイルを削除し（BFG Repo-Cleanerやfilter-repoなどを使用）、リモートにも反映します。さらに重要なのは、流出した可能性のある秘密鍵と、それで復号できるすべてのシークレット（APIキーやパスワード等）をローテーション（再発行）することです。履歴から消しても一度公開された鍵は漏洩したものとして扱うのが安全で、鍵の無効化と再生成までをセットで行ってください。

dotenvxはPythonやGoなどNode.js以外でも使えますか？

使えます。dotenvxはCLIツールとして動作し、言語に依存しない「Run Anywhere」設計を採用しているため、Python・Ruby・Go・Rust・PHPなど幅広い言語で利用できます。たとえばPythonでも、python-dotenvを使わずにdotenvx run -- python main.pyのようにCLI経由で環境変数を注入できます。既存のload_dotenv()を残したまま起動方法だけ変える、という段階的な移行も可能です。

dotenvxの導入は無料ですか？

dotenvx本体はオープンソース（BSD-3-Clauseライセンス）で、無料で利用できます。暗号化・復号・複数環境の管理といった主要機能はすべてCLIだけで完結します。なお、チームでの鍵管理や共有をより簡単にするための有料の商用拡張も別途提供されていますが、その利用は必須ではありません。まずは無料のCLIだけで導入し、運用が固まってから有料サービスの要否を検討すれば十分です。

関連記事

• dotenv-railsとは何か：概要と基本機能について：dotenvxの基礎にあたる従来のdotenv系ツールを、Railsでの環境変数管理を例に詳しく解説しています。
• miseとは：Rust製の高速ツールバージョン管理システム：環境変数管理やdirenv連携も担うmiseは、dotenvxと併用できる関連ツールです。
• PATとGitHub Appsトークンの違いと使い分け：dotenvxで守るべき代表的なシークレットであるアクセストークンの管理を掘り下げています。
• Dockerfileとは何か：基本的な役割と重要性：dotenvxをコンテナで使う前提となる、Dockerfileの基礎を確認できます。