--- title: "dotenvxとは｜.envを暗号化してGitで安全に管理する仕組み・使い方・移行手順" url: "https://www.issoh.co.jp/tech/details/12633/" published: 2026-06-18 updated: 2026-10-19 categories: ["GitHub"] publisher: "株式会社一創" --- # 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の環境変数管理](https://www.issoh.co.jp/tech/details/3573/)など）は、平文の`.env`を読み込んでアプリの環境変数に展開することが役割でした。値の保護はスコープ外で、`.env`は各自がローカルに持つ前提です。これに対しdotenvxは「暗号化してGitで共有する」ことを設計の中心に据えており、出発点となる思想が根本的に異なります。 ### .envをGit管理できなかった従来課題と暗号化コミットによる解決 従来は機密を含む`.env`をコミットできないため、設定変更が「いつの間にか変わって動かない」「誰が変えたか分からない」状態になりがちでした。平文の認証情報を誤ってコミットして漏洩する事故も後を絶たず、実際に[GitHubでの認証情報漏洩による不正アクセス事案](https://www.issoh.co.jp/tech/details/11988/)のような被害も報告されています。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によるインフラ管理](https://www.issoh.co.jp/tech/details/1467/)のような仕組みと合わせ、これらは管理基盤をクラウド側へ寄せるアプローチです。これに対しdotenvxはリポジトリ内で完結し鍵管理が手元で済む手軽さが強みで、両者は責務が異なります。大まかな比較は以下のとおりです。 | 観点 | dotenvx | クラウドSecrets Manager（例: AWS Secrets Manager） | SOPS | | --------- | -------------- | ------------------------------------------- | ---------------- | | 保管場所 | Gitリポジトリ内（暗号文） | クラウド上で中央管理 | Gitリポジトリ内（暗号文） | | 対象 | 主に.envファイル | 任意のキー/バリュー | .env・JSON・YAMLなど | | アクセス制御・監査 | 鍵の配布で制御（手動寄り） | IAM等で細粒度に制御・監査ログ | KMS等の鍵管理に依存 | | ローテーション | 手動 | 自動ローテーション対応 | 手動寄り | | 導入の手軽さ | 高い（CLIのみ） | 中（基盤設定が必要） | 中 | 個人〜中規模やリポジトリ完結を重視するなら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の基本的な書き方](https://www.issoh.co.jp/tech/details/3315/)と合わせて、`.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のシークレットスキャン](https://www.issoh.co.jp/tech/details/5211/)のような仕組みを併用すると安心です。暗号化（予防）と検知（発見）を組み合わせる多層防御の発想が、実運用での安全性を底上げします。 ## 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とは何か：概要と基本機能について](https://www.issoh.co.jp/tech/details/3573/)：dotenvxの基礎にあたる従来のdotenv系ツールを、Railsでの環境変数管理を例に詳しく解説しています。 - [miseとは：Rust製の高速ツールバージョン管理システム](/tech/details/2765/)：環境変数管理やdirenv連携も担うmiseは、dotenvxと併用できる関連ツールです。 - [PATとGitHub Appsトークンの違いと使い分け](https://www.issoh.co.jp/tech/details/7545/)：dotenvxで守るべき代表的なシークレットであるアクセストークンの管理を掘り下げています。 - [Dockerfileとは何か：基本的な役割と重要性](https://www.issoh.co.jp/tech/details/3315/)：dotenvxをコンテナで使う前提となる、Dockerfileの基礎を確認できます。 --- 出典: [dotenvxとは｜.envを暗号化してGitで安全に管理する仕組み・使い方・移行手順]()（株式会社一創）