--- type: Reference title: "環境変数管理ガイド" description: "このドキュメントでは、プロジェクトで使用する環境変数について説明します。" tags: [reference] status: stable generated: { by: human:kakimomokuri, at: 2026-04-06T03:31:33Z } stale_after: 2027-02-23T00:00:00Z --- # 環境変数管理ガイド このドキュメントでは、プロジェクトで使用する環境変数について説明します。 ## dotenv とは ### 概要 **dotenv** は、環境変数を `.env` ファイルから読み込むためのライブラリです。アプリケーションの設定値をソースコードから分離し、環境ごとに異なる設定を簡単に管理できます。 ### なぜ dotenv を使うのか 1. **セキュリティ**: パスワードや API キーをソースコードにハードコーディングせず、Git 管理外のファイルで管理 2. **環境の分離**: 開発・ステージング・本番環境で異なる設定を簡単に切り替え 3. **チーム開発**: 各開発者が自分の環境に合わせた設定を使用可能 4. **12-Factor App**: [The Twelve-Factor App](https://12factor.net/ja/config) の設定管理ベストプラクティスに準拠 ### 仕組み ```plantuml @startuml title dotenv による環境変数読み込みの流れ skinparam rectangle { BackgroundColor #f5f5f5 BorderColor #333333 } rectangle ".env ファイル" as env rectangle "process.env (Node.js)" as process rectangle "アプリケーションコード" as app env -down-> process : dotenv が読み込み process -down-> app : アプリケーションで使用 note right of env MKDOCS_PORT=8000 DOCKER_HOST=npipe:////./pipe/docker_engine end note note right of process process.env.MKDOCS_PORT process.env.DOCKER_HOST end note note right of app const port = process.env.MKDOCS_PORT; end note @enduml ``` ## セットアップ方法 ### 1. パッケージのインストール ```bash npm install dotenv ``` ### 2. .env ファイルの作成 ```bash # テンプレートからコピー cp .env.example .env # または新規作成 touch .env ``` ### 3. .env ファイルの編集 ```bash # プロジェクトルート/.env MKDOCS_PORT=8000 ``` ### 4. アプリケーションでの読み込み ```javascript // 方法1: エントリーポイントの先頭でインポート（推奨） import 'dotenv/config'; // 方法2: 明示的に config() を呼び出し import * as dotenv from 'dotenv'; dotenv.config(); // 環境変数を使用 const port = process.env.MKDOCS_PORT || 8000; ``` ### 5. .gitignore に追加 ```gitignore # .gitignore .env .env.local .env.*.local ``` ## 環境変数ファイル一覧 | ファイル | 用途 | Git 管理 | |---------|------|----------| | `.env` | ローカル開発用設定 | ✗ | | `.env.example` | 設定テンプレート | ✓ | ## プロジェクト環境変数 ### Docker 設定 | 変数名 | 説明 | デフォルト値 | |--------|------|-------------| | `DOCKER_HOST` | Docker デーモンへの接続先 | (システム依存) | ### MkDocs 設定 | 変数名 | 説明 | デフォルト値 | |--------|------|-------------| | `MKDOCS_PORT` | MkDocs サーバーのポート番号 | `8000` | ## 重要な注意事項 ### DOCKER_HOST 環境変数について Docker Desktop 使用時に `DOCKER_HOST` 環境変数が不正に設定されていると接続エラーが発生します。 ``` ERROR: error during connect: Head "http://.%2Fpipe%2Fdocker_engine/_ping": open ./pipe/docker_engine: The system cannot find the path specified. ``` **Windows 環境での正しい設定:** ```bash # 正しい形式 DOCKER_HOST=npipe:////./pipe/docker_engine # 誤った形式（エラーになる） DOCKER_HOST=npipe://./pipe/docker_engine ``` **解決方法:** ```bash # 環境変数を削除（Docker Desktop が自動設定する） unset DOCKER_HOST ``` > **注意**: 本プロジェクトの gulp タスクは Windows 環境で自動的に `DOCKER_HOST` を正規化します。 ### セキュリティに関する注意 - `.env` ファイルは Git にコミットしないでください - 機密情報（API キー、パスワード等）は `.env` ファイルで管理してください - 本番環境では環境変数を直接設定することを推奨します ## .env ファイルの読み込み優先順位 ```plantuml @startuml title Node.js (dotenv) 読み込み優先順位 skinparam defaultTextAlignment center rectangle "1. シェル環境変数\n(最優先)" as shell #ff9999 rectangle "2. .env.local\n(Git 管理外)" as local #ffcc99 rectangle "3. .env\n(ローカル設定)" as env #99ff99 shell -[hidden]down-> local local -[hidden]down-> env note right of shell : 既存の環境変数は上書きされない note right of local : ローカル固有の設定 note right of env : デフォルト値 @enduml ``` ## .env ファイルの書き方 ```bash # コメントは # で始める # 基本的な書き方 KEY=value # 値にスペースを含む場合はクォートで囲む MESSAGE="Hello World" # 変数の展開（dotenv-expand が必要） BASE_URL=http://localhost API_URL=${BASE_URL}/api ``` ## ベストプラクティス | Do | Don't | |----|-------| | `.env.example` をテンプレートとして Git 管理 | `.env` を Git にコミット | | 本番環境では環境変数を直接設定 | 本番環境で `.env` ファイルを使用 | | 変数名は `SCREAMING_SNAKE_CASE` を使用 | 小文字や camelCase を使用 | | デフォルト値をコードで設定 | `.env` ファイルのみに依存 | ```javascript // デフォルト値の設定例 const port = process.env.MKDOCS_PORT || 8000; const nodeEnv = process.env.NODE_ENV || 'development'; ``` ## Vault（暗号化・復号化） ### 概要 Vault は `.env` ファイルを安全に暗号化・復号化するためのツールです。暗号化されたファイル（`.env.vault`）は Git にコミットでき、チームメンバー間で安全に環境変数を共有できます。 ### なぜ Vault を使うのか 1. **チーム間での秘密情報共有**: `.env` を直接共有せず、暗号化して Git 管理 2. **環境の再現性**: 新しいメンバーがすぐに開発環境を構築可能 3. **セキュリティ**: AES-256-GCM による強力な暗号化 4. **シンプルさ**: 外部サービス不要、パスワードのみで運用 ### 暗号化仕様 ```plantuml @startuml title Vault 暗号化の仕組み skinparam rectangle { BackgroundColor #f5f5f5 BorderColor #333333 } rectangle "パスワード" as password rectangle "ソルト\n(32バイト乱数)" as salt rectangle "PBKDF2\n(SHA-512, 100,000回)" as pbkdf2 rectangle "暗号化キー\n(256ビット)" as key rectangle "IV\n(16バイト乱数)" as iv rectangle "AES-256-GCM" as aes rectangle ".env\n(平文)" as plaintext rectangle ".env.vault\n(暗号文)" as ciphertext password -down-> pbkdf2 salt -down-> pbkdf2 pbkdf2 -down-> key key -down-> aes iv -down-> aes plaintext -right-> aes aes -down-> ciphertext note right of pbkdf2 100,000回のイテレーションで ブルートフォース攻撃を困難に end note note right of aes 認証付き暗号（AEAD） 改ざん検知機能付き end note @enduml ``` | 項目 | 値 | |------|-----| | 暗号化アルゴリズム | AES-256-GCM（認証付き暗号） | | 鍵導出関数 | PBKDF2-SHA512 | | イテレーション回数 | 100,000 回 | | ソルト長 | 32 バイト（毎回ランダム生成） | | IV（初期化ベクトル）長 | 16 バイト（毎回ランダム生成） | | 認証タグ長 | 16 バイト | ### .env.vault ファイル形式 暗号化されたファイルはバイナリ形式で、以下の構造を持ちます： ``` +------------------+ | Salt (32 bytes) | +------------------+ | IV (16 bytes) | +------------------+ | AuthTag (16 bytes)| +------------------+ | Ciphertext | | (可変長) | +------------------+ ``` ### コマンド詳細 #### vault:encrypt `.env` ファイルを暗号化して `.env.vault` を作成します。 ```bash npm run vault:encrypt ``` **動作フロー:** ```plantuml @startuml title vault:encrypt の動作フロー start :.env ファイルの存在確認; if (.env が存在する?) then (yes) :パスワード入力を要求; :パスワード確認入力を要求; if (パスワードが一致?) then (yes) if (8文字以上?) then (yes) :ソルトを生成（32バイト乱数）; :PBKDF2で暗号化キーを導出; :IVを生成（16バイト乱数）; :AES-256-GCMで暗号化; :.env.vault を出力; :成功メッセージを表示; else (no) :エラー: パスワードが短すぎる; stop endif else (no) :エラー: パスワードが一致しない; stop endif else (no) :エラー: .env が見つからない; stop endif stop @enduml ``` **オプション:** | 環境変数 | 説明 | |---------|------| | `VAULT_PASSWORD` | パスワードを事前に指定（対話入力をスキップ） | **例:** ```bash # 対話的にパスワードを入力 npm run vault:encrypt # 環境変数でパスワードを指定（CI/CD 用） VAULT_PASSWORD=my-secret-password npm run vault:encrypt ``` --- #### vault:decrypt `.env.vault` ファイルを復号化して `.env` を復元します。 ```bash npm run vault:decrypt ``` **動作フロー:** ```plantuml @startuml title vault:decrypt の動作フロー start :.env.vault ファイルの存在確認; if (.env.vault が存在する?) then (yes) if (.env が既に存在する?) then (yes) :上書き確認を表示; if (上書きを許可?) then (yes) else (no) :処理を中止; stop endif endif :パスワード入力を要求; :暗号化ファイルを読み込み; :ソルト・IV・認証タグを抽出; :PBKDF2で暗号化キーを導出; if (復号化成功?) then (yes) :.env を出力; :成功メッセージを表示; else (no) :エラー: パスワードが正しくない; stop endif else (no) :エラー: .env.vault が見つからない; stop endif stop @enduml ``` **例:** ```bash # 対話的にパスワードを入力 npm run vault:decrypt # 環境変数でパスワードを指定 VAULT_PASSWORD=my-secret-password npm run vault:decrypt ``` --- #### vault:view `.env.vault` の内容を復号化して表示します。ファイルは作成されません。 ```bash npm run vault:view ``` **用途:** - 暗号化された内容を確認したいが、`.env` ファイルを作成したくない場合 - CI/CD パイプラインでのデバッグ - 復号化前の内容確認 **例:** ```bash # 内容を確認 npm run vault:view # 出力例: # --- .env.vault contents --- # # DATABASE_URL=mysql://user:pass@localhost:3306/mydb # API_KEY=sk-xxxxxxxxxxxx # # --- end --- ``` --- #### vault:rekey 現在のパスワードで復号化し、新しいパスワードで再暗号化します。 ```bash npm run vault:rekey ``` **動作フロー:** ```plantuml @startuml title vault:rekey の動作フロー start :.env.vault ファイルの存在確認; if (.env.vault が存在する?) then (yes) :現在のパスワード入力を要求; if (復号化成功?) then (yes) :新しいパスワード入力を要求; :新しいパスワード確認入力を要求; if (パスワードが一致 & 8文字以上?) then (yes) :新しいソルト・IVを生成; :新しいパスワードで再暗号化; :.env.vault を上書き; :成功メッセージを表示; else (no) :エラー: パスワード要件を満たさない; stop endif else (no) :エラー: 現在のパスワードが正しくない; stop endif else (no) :エラー: .env.vault が見つからない; stop endif stop @enduml ``` **用途:** - 定期的なパスワードローテーション - チームメンバーの退職時 - パスワード漏洩の疑いがある場合 ### 使い方 #### 初回セットアップ（暗号化） ```bash # 1. .env ファイルを作成・編集 cp .env.example .env vim .env # 2. 暗号化（パスワード入力を求められる） npm run vault:encrypt # New vault password: ******** # Confirm vault password: ******** # Encrypted .env -> .env.vault # 3. 暗号化ファイルをコミット git add .env.vault git commit -m "Add encrypted environment file" ``` #### 別の環境での復元（復号化） ```bash # 1. リポジトリをクローン git clone cd # 2. 依存関係をインストール npm install # 3. 暗号化ファイルを復号化（パスワード入力を求められる） npm run vault:decrypt # Vault password: ******** # Decrypted .env.vault -> .env ``` #### CI/CD での使用 ```yaml # GitHub Actions の例 jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' - run: npm install - run: npm run vault:decrypt env: VAULT_PASSWORD: ${{ secrets.VAULT_PASSWORD }} - run: npm run deploy ``` #### パスワードの変更 ```bash # 現在のパスワードと新しいパスワードを入力 npm run vault:rekey # Enter current password: # Current vault password: ******** # # Enter new password: # New vault password: ******** # Confirm vault password: ******** # Re-encrypted .env.vault with new password. ``` ### ワークフロー ```plantuml @startuml title Vault ワークフロー actor 開発者A as devA actor 開発者B as devB database Git as git devA -> devA: .env を編集 devA -> devA: npm run vault:encrypt devA -> git: .env.vault をコミット git -> devB: git pull devB -> devB: npm run vault:decrypt devB -> devB: .env が復元される note right of devA パスワードは安全な方法で チームに共有 end note @enduml ``` ### セキュリティのベストプラクティス | Do | Don't | |----|-------| | 8 文字以上の強力なパスワードを使用 | 短い・推測しやすいパスワードを使用 | | パスワードを安全な方法で共有（1Password など） | パスワードを Slack やメールで送信 | | `.env.vault` を Git にコミット | `.env` を Git にコミット | | 定期的にパスワードを変更（vault:rekey） | 同じパスワードを長期間使用 | | CI/CD では Secrets 機能を使用 | CI/CD ログにパスワードを出力 | ### 注意事項 - パスワードを忘れると復号化できなくなります（復旧不可） - `.env.vault` を Git に追加しても `.env` は `.gitignore` で除外されています - CI/CD 環境では `VAULT_PASSWORD` 環境変数を使用してください - 同じ内容でも暗号化するたびに異なる出力になります（ソルトとIVがランダム） ### Vault トラブルシューティング #### 復号化に失敗する ``` Error: Invalid password ``` **原因:** パスワードが正しくない **解決策:** 1. パスワードを再確認 2. Caps Lock がオフになっているか確認 3. パスワードマネージャーから正しいパスワードをコピー #### .env.vault が見つからない ``` Error: .env.vault not found ``` **原因:** 暗号化ファイルが存在しない **解決策:** 1. `git pull` で最新を取得 2. `.env.vault` がコミットされているか確認 3. まだ暗号化されていない場合は `vault:encrypt` を実行 #### パスワードが短すぎる ``` Error: Password must be at least 8 characters ``` **原因:** 8 文字未満のパスワードを入力 **解決策:** 8 文字以上のパスワードを使用してください。推奨は 12 文字以上。 ## トラブルシューティング ### 環境変数が読み込まれない 1. `.env` ファイルがプロジェクトルートにあるか確認 2. `dotenv/config` がエントリーポイントの先頭でインポートされているか確認 3. 変数名にタイポがないか確認 ### Docker 接続エラー 1. Docker Desktop が起動しているか確認 2. `DOCKER_HOST` 環境変数が正しく設定されているか確認 3. 必要に応じて `unset DOCKER_HOST` を実行