Masayan tech blog .

dotenvx完全ガイド|環境変数を暗号化してGitコミットする方法

公開日
最終更新日

要約

dotenvxは、広く使われている環境変数管理ツール「dotenv」の正式な後継ツールである。.envファイルを暗号化してGitにコミット可能にし、チーム開発での環境変数共有を劇的に改善する。NASA、PayPal、AWSなど多くの企業が採用しており、本番環境での利用に十分な実績と安定性を持っている。

対象読者: Node.js/Python/Ruby等を使う開発者、チーム開発で環境変数管理に課題を感じている方

検証環境: Node.js 20以降、dotenvx v1.51.1(2024年11月時点)

この記事を読むことで得られるメリット

Webアプリケーション開発において、APIキーやデータベース接続情報などの機密情報を環境変数で管理することは一般的だが、従来の.envファイル管理には多くの課題があった。本記事では、その課題を解決する次世代ツール「dotenvx」の導入方法を詳しく解説する。

この記事を読むことで以下のことが分かる:

  • dotenvxの信頼性と本番環境での採用実績
  • 新規プロジェクトでの暗号化を前提としたセットアップ方法
  • 既存プロジェクトへの移行手順(3ステップで完了)
  • チーム開発での秘密鍵の安全な共有方法
  • GitHub Actions/DockerでのCI/CD設定例
  • dotenvxのデメリットと注意点

この記事を読むのにかかる時間

約18分

環境

  • MacOS Apple M4 Max Sequoia 15.1
  • Node.js 20以降
  • dotenvx v1.51.1

dotenvxとは

dotenvxは、広く使われている環境変数管理ツール「dotenv」の次世代版である。作者はオリジナルのdotenvを作成したScott Motte(通称Mot)氏であり、正式な後継ツールとなる。

主な特徴は以下の通りである。

  • クロスプラットフォーム・言語非依存: Node.jsだけでなく、Python、Ruby、Go、Rustなど様々な言語で利用可能
  • .envファイルの暗号化: 機密情報を暗号化し、安全にリポジトリにコミット可能
  • 環境ごとの管理: .env.development.env.productionのように環境別のファイル管理をサポート
  • バリデーション: .env.exampleファイルと比較し、必要な環境変数が定義されているかチェック

dotenvxは本番環境で使えるのか

新しいツールを本番環境に導入する際、最も気になるのは「本当に信頼できるのか」という点である。結論から言うと、dotenvxは本番環境での利用に十分な実績と安定性を持っている。

提供元と信頼性

dotenvxはScott Motte(Mot)氏が開発・提供している。彼はオリジナルのdotenv(年間数十億回インストールされる)の作者であり、開発者ツールとセキュリティの専門家である。

本番環境での採用実績

dotenvxは週に100万回以上インストールされており、以下のような企業・組織が採用している。

  • 大企業: PayPal、NASA、AWS、Facebook、Supabase、Socket
  • 政府機関: 英国、フランス、カナダ、フィンランドの政府機関

AWSはAWS Amplifyでの使用を推奨し、NASAはEarthdata Searchで使用、Supabaseはブランチング機能で必須としている。

バージョンと安定性

  • 現在のバージョン: v1.51.1(2024年11月時点)
  • リリース履歴: 274回のリリース
  • GitHubスター: 4,600以上
  • ライセンス: BSD-3-Clause(商用利用可)

これはプレビュー版ではなく、安定した本番対応版である。

暗号化方式

dotenvxはECIES(楕円曲線統合暗号化方式)を採用している。

  • AES-256: 各シークレットを固有の一時キーで暗号化
  • Secp256k1: 楕円曲線暗号(Bitcoinでも使用されている技術)

この暗号化を破るには、AES-256と楕円曲線暗号の両方をブルートフォースで突破する必要があり、現在の技術では計算上不可能である。

dotenvとdotenvxの違い

従来のdotenvとdotenvxの主な違いを以下にまとめる。

dotenv

  • 動作環境: 各言語の専用ライブラリが必要
  • 複数環境: サポートなし
  • 暗号化: サポートなし

dotenvx

  • 動作環境: 依存せずdotenvx単体でOK
  • 複数環境: ファイル指定可能(併用も可能)
  • 暗号化: サポート

特に暗号化サポートは大きな進化である。dotenv単体では秘匿情報が含まれた.envファイル自体の管理に困ることや、デプロイする際にどうやって環境変数を提供するかが課題であった。dotenvxでは.envファイル自体が暗号化され、Gitでバージョン管理でき、そのままデプロイして環境変数を適用できる。

インストール方法

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

# npm(Node.jsプロジェクト)
npm install @dotenvx/dotenvx --save

# yarn
yarn add @dotenvx/dotenvx

# pnpm
pnpm add @dotenvx/dotenvx

# curl(グローバルインストール)
curl -sfS https://dotenvx.sh | sh

# Homebrew(macOS)
brew install dotenvx/brew/dotenvx

プロジェクトごとに管理したい場合はnpm/yarn/pnpm、システム全体で使いたい場合はcurlやHomebrewが便利である。

新規プロジェクトでの導入

新しくプロジェクトを始める場合は、最初から暗号化を前提とした運用がおすすめである。

基本的なセットアップ

# プロジェクトを作成
mkdir my-project && cd my-project
npm init -y

# dotenvxをインストール
npm install @dotenvx/dotenvx --save

環境変数を暗号化しながらセット

dotenvx setコマンドを使うと、最初から暗号化された状態で環境変数をセットできる。

# 開発環境用
dotenvx set DATABASE_URL "postgres://dev:pass@localhost/dev_db" -f .env.development
dotenvx set API_KEY "dev_api_key_123" -f .env.development

# 本番環境用
dotenvx set DATABASE_URL "postgres://prod:pass@prod-host/prod_db" -f .env.production
dotenvx set API_KEY "prod_api_key_456" -f .env.production

これにより、以下のようなファイルが生成される。

.env.development(暗号化済み)

#/-------------------[DOTENV_PUBLIC_KEY]--------------------/
#/            public-key encryption for .env files          /
#/       [how it works](https://dotenvx.com/encryption)     /
#/----------------------------------------------------------/
DOTENV_PUBLIC_KEY_DEVELOPMENT="03f8b376234c4f2f..."

DATABASE_URL="encrypted:BD9paBaun2284Wcqd..."
API_KEY="encrypted:BJ0KapPiuE/ruoLY7r..."

.env.keys(復号用の秘密鍵)

#/------------------!DOTENV_PRIVATE_KEYS!-------------------/
#/ private decryption keys. DO NOT commit to source control /
#/     [how it works](https://dotenvx.com/encryption)       /
#/----------------------------------------------------------/

# .env.development
DOTENV_PRIVATE_KEY_DEVELOPMENT="bd7c50b352ce23973ec9db355d70212305a0baaade92f0165f02915b213bfbe2"

# .env.production
DOTENV_PRIVATE_KEY_PRODUCTION="a4547dcd9d3429615a3649bb79e87edb62ee6a74b007075e9141ae44f5fb412c"

.gitignoreの設定

# 秘密鍵は絶対にコミットしない
.env.keys

# ローカルオーバーライド用
.env.local
.env.*.local

重要: 暗号化された.env.development.env.productionはGitにコミットしてOKである。秘密鍵(.env.keys)だけは絶対にコミットしてはならない。

アプリケーションの実行

# 開発環境で実行
dotenvx run -f .env.development -- node index.js

# 本番環境で実行(秘密鍵を環境変数で渡す)
DOTENV_PRIVATE_KEY_PRODUCTION="bd7c50b352ce..." dotenvx run -f .env.production -- node index.js

package.jsonの設定例

{
  "scripts": {
    "dev": "dotenvx run -f .env.development -- next dev",
    "dev:stg": "dotenvx run -f .env.staging -- next dev",
    "dev:prod": "dotenvx run -f .env.production -- next dev",
    "build": "dotenvx run -f .env.production -- next build",
    "build:dev": "dotenvx run -f .env.development -- next build",
    "build:stg": "dotenvx run -f .env.staging -- next build",
    "setenv:dev": "dotenvx set -f .env.development",
    "setenv:stg": "dotenvx set -f .env.staging",
    "setenv:prod": "dotenvx set -f .env.production"
  }
}

既存プロジェクトへの導入

すでにdotenvを使っているプロジェクトでも、dotenvxへの移行は非常に簡単である。

ステップ1: dotenvxのインストール

npm install @dotenvx/dotenvx --save

既存のdotenvパッケージはそのまま残しておいても、アンインストールしても構わない。dotenvxは独立して動作する。

ステップ2: 既存の.envファイルを暗号化

# ローカルの.envを暗号化
npx dotenvx encrypt -f .env.local

---

# 本番環境用も暗号化
npx dotenvx encrypt -f .env.production

ファイル名が.envの場合は-fは不要

npx dotenvx encrypt

これだけで、既存の.envファイルが暗号化される。元のファイル内容は暗号化された形式に置き換わり、復号用の.env.keysファイルが生成される。

.env.local

DOTENV_PUBLIC_KEY_LOCAL="0xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

NEXT_PUBLIC_FIREBASE_API_KEY=encrypted:BKH・・・
...

.env.production

DOTENV_PUBLIC_KEY_PRODUCTION="1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

NEXT_PUBLIC_FIREBASE_API_KEY=encrypted:BKo・・・
...

.env.keys

dotenvxで.env.localファイルを暗号化した際に生成される秘密鍵(環境ごとに設定することができ、復号時も環境ごとに指定して実行できる

DOTENV_PRIVATE_KEY_LOCAL=axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
DOTENV_PRIVATE_KEY_PRODUCTION=bxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

公開鍵 = 南京錠(誰でも鍵をかけられる)
秘密鍵 = 南京錠の鍵(持っている人だけが開けられる)
南京錠を見せても、鍵がなければ開けられない

ステップ3: .gitignoreの更新

# 既存の設定に追加
.env.keys

ステップ4: package.jsonの更新

既存のスクリプトにdotenvx run --を追加する。

変更前:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

変更後:

{
  "scripts": {
    "dev": "dotenvx run -- next dev",
    "build": "dotenvx run -- next build",
    "start": "dotenvx run -- next start"
  }
}

ステップ5: コード内のdotenv読み込みを削除(任意)

dotenvxを使う場合、コード内でrequire('dotenv').config()を呼び出す必要はなくなる。ただし、残しておいても動作に影響はない。

// これはもう不要(削除しても、残しておいてもOK)
// require('dotenv').config()

console.log(process.env.DATABASE_URL) // 正常に読み込める

複数環境の管理

dotenvxの大きな強みの一つが、複数環境の柔軟な管理である。

環境ごとのファイル作成

.env.development    # 開発環境
.env.staging        # ステージング環境
.env.production     # 本番環境
.env.test           # テスト環境

秘密鍵が不正な場合(環境間違いとか値がおかしいとか)はサーバー自体は起動するが、警告が出る。(環境変数の読み込みに失敗しているはずなので、サーバー起動するがアプリケーション自体はまともに動かないはず)

[INVALID_PRIVATE_KEY] could not decrypt DOTENV_PRIVATE_KEY_LOCAL="axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

ファイル名と環境変数名の対応

環境変数として指定した秘密鍵から、複合する値が書かれた環境変数ファイルを検出する仕組み

ファイル名

探す環境変数名

.env

DOTENV_PRIVATE_KEY

.env.production

DOTENV_PRIVATE_KEY_PRODUCTION

.env.staging

DOTENV_PRIVATE_KEY_STAGING

.env.development

DOTENV_PRIVATE_KEY_DEVELOPMENT

.env.local

DOTENV_PRIVATE_KEY_LOCAL

実行時に環境を指定

# 開発環境
dotenvx run -f .env.development -- npm start

# ステージング環境
dotenvx run -f .env.staging -- npm start

# 本番環境
dotenvx run -f .env.production -- npm start

複数ファイルのマージ

共通の設定と環境固有の設定を分けて管理することもできる。

# .envと.env.productionをマージ(先に指定したファイルが優先)
dotenvx run -f .env -f .env.production -- npm start

# --overloadオプションで後に指定したファイルを優先
dotenvx run -f .env -f .env.production --overload -- npm start

衝突しないキーはそのままマージされるため、どの環境でも値が変わらないキーは共通の.envファイルに定義しておくことで共通化できる。

読み込み優先順位

環境変数の読み込み優先順位は以下の通りである(後から読み込まれたものが優先、--overloadなしの場合は先が優先)。

  1. .env
  2. .env.[environment](例: .env.development
  3. .env.local(ローカル環境でのみ上書きしたい場合)
  4. .env.[environment].local(特定の環境のローカル上書き)

暗号化の2つのアプローチ

dotenvxには暗号化の方法が2つある。

アプローチ1: ファイル全体を暗号化

dotenvx encrypt
dotenvx encrypt -f .env.production

すべての環境変数が暗号化される。最もシンプルで安全な方法である。

アプローチ2: 変数ごとに暗号化

# 暗号化して追加
dotenvx set SECRET_KEY "super_secret_value"
dotenvx set DATABASE_URL "postgres://..." -f .env.production

# 平文で追加(機密でない情報)
echo "APP_NAME=MyApp" >> .env
echo "LOG_LEVEL=debug" >> .env

この方法では、機密情報は暗号化し、公開情報(アプリ名やログレベルなど)は平文のまま残すことができる。平文のほうが確認がすぐできるので便利な場合がある。

注意: 途中でdotenvx encryptを実行すると全部暗号化されてしまうので、混在させる場合は注意が必要である。

暗号化された値の確認

暗号化された環境変数の中身を確認するには、dotenvx getコマンドを使う。

# 特定のキーの値を確認
dotenvx get API_KEY -f .env.development

# すべてのキーと値を確認
dotenvx get -f .env.development

チーム開発での運用

dotenvxを使うことで、チーム開発での環境変数管理が劇的に改善する。

従来の課題

  • 新しいメンバーへの.envファイルの受け渡しが面倒
  • 環境変数の変更をSlackやメールで通知する必要がある
  • どの環境変数が最新かわからない
  • 機密情報をどうやって安全に共有するか

dotenvxを使った運用フロー

  1. 暗号化された.envファイル: Gitリポジトリにコミット
  2. 秘密鍵(.env.keys): 1PasswordやAWS Secrets Managerなどで安全に管理・共有

これにより、新しいメンバーはgit pullするだけで必要な環境変数がすべて手に入る。秘密鍵さえ適切に共有すれば、.envファイルの受け渡しで悩むことはなくなる。

秘密鍵の共有方法

  • パスワードマネージャー: 1Password、Bitwarden、LastPassなど
  • クラウドのSecrets Manager: AWS Secrets Manager、Google Secret Manager、HashiCorp Vault
  • セキュアなチャット: アクセス制御が適切に行われているツール

重要: 秘密鍵をメールやSlackのパブリックチャンネル、Gitリポジトリなどで平文共有してはならない。

CI/CD設定例

Vercel

DOTENV_PRIVATE_KEY_PRODUCTIONなど環境の数だけキーと値を環境変数に設定し、環境ごとのビルドコマンドをダッシュボードで登録しておく(npm run build:encrypted:production

  • Settings → Build and Deployment
  • Settings → Environment Variables

GitHub Actions

name: Build and Deploy

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Install dotenvx
        run: curl -sfS https://dotenvx.sh | sh

      - name: Build (production)
        run: DOTENV_PRIVATE_KEY_PRODUCTION=${{ secrets.DOTENV_PRIVATE_KEY_PRODUCTION }} dotenvx run -f .env.production -- npm run build

      - name: Deploy
        run: # デプロイコマンド

Docker

FROM node:20-alpine

WORKDIR /app

# dotenvxをインストール
RUN curl -sfS https://dotenvx.sh | sh

COPY package*.json ./
RUN npm ci

COPY . .

# ビルド時に環境変数を注入
ARG DOTENV_PRIVATE_KEY_PRODUCTION
RUN DOTENV_PRIVATE_KEY_PRODUCTION=$DOTENV_PRIVATE_KEY_PRODUCTION dotenvx run -f .env.production -- npm run build

CMD ["dotenvx", "run", "-f", ".env.production", "--", "node", "dist/index.js"]

バリデーション機能

dotenvxは.env.exampleファイルを使って、必要な環境変数が定義されているかチェックできる。

.env.example

DATABASE_URL=
API_KEY=
SECRET_KEY=
$ dotenvx run -- node index.js
info: ✅ loaded env from .env
info: 🚨 missing keys (.env.example) [SECRET_KEY]

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

デメリット・注意点

dotenvxは非常に便利なツールだが、いくつかの注意点もある。

パッと見で何が入っているかわからない

暗号化されているため、.envファイルを開いても中身がわからない。

API_ENDPOINT="encrypted:BD9paBaun2284WcqdFQZUlDK..."

確認するにはdotenvx get API_ENDPOINTを実行する必要がある。

CIで復号処理が必要

GitHub Actionsなどでビルドする際も、Secretsに秘密鍵を登録してコマンドで渡す必要がある。環境の数だけその設定が必要になる。

秘密鍵の紛失=復号不可

.env.keysファイルを紛失すると、暗号化された環境変数を復号できなくなる。必ずバックアップを取っておくこと。

Node.js 20以降の--env-fileとの競合

Node.js 20以降では--env-fileフラグがあり、dotenvxと競合することがある。.envファイルが見つからない場合にエラーが出る場合は、--env-file-fに置き換える。

# これがエラーになる場合
dotenvx run --env-file .env -- node index.js

# こちらに変更
dotenvx run -f .env -- node index.js

よくある質問(FAQ)

Q1: dotenvxは無料で使えるか?

A: はい、dotenvxはBSD-3-Clauseライセンスで提供されており、商用利用を含め無料で使用できる。

Q2: 既存のdotenvパッケージと併用できるか?

A: できる。dotenvxは独立して動作するため、既存のdotenvパッケージを残したまま導入可能である。

Q3: 秘密鍵を紛失した場合どうなるか?

A: 暗号化された環境変数を復号できなくなる。秘密鍵は必ずパスワードマネージャーやSecrets Managerでバックアップを取っておくこと。

Q4: 複数人で同じ環境変数を更新した場合、コンフリクトは起きるか?

A: Gitの通常のマージコンフリクトと同様に発生する。チームでの更新ルールを決めておくとよい。

Q5: dotenvxはNode.js以外でも使えるか?

A: はい、Python、Ruby、Go、Rustなど様々な言語で利用可能である。CLIツールとして動作するため、言語に依存しない。

まとめ

dotenvxは、従来の.envファイル管理の課題を解決する強力なツールである。

  • 安心して使える: NASA、PayPal、AWS、政府機関など多くの組織が採用
  • 本番対応済み: v1.51.1、274リリース、4,600+ GitHubスター
  • 既存プロジェクトにも簡単導入: dotenvx encrypt一発で暗号化
  • チーム開発が快適に: git pullで全環境変数が揃う

「環境変数周りで煩わされるのって非生産的すぎてほんとに萎える」という経験は多くの開発者が持っているはずである。dotenvxを導入することで、その悩みから解放される。

プロジェクトの最初からdotenvxを設定しておくのがベストだが、途中からの導入も非常に簡単である。ぜひお手元のプロジェクトで試してみてほしい。