| name | env-config |
| description | 環境設定管理の設計ガイド（フレームワーク非依存）。環境分離の原則、環境変数の設計パターン、設定ファイル構成、シークレットとの分離、ローカル開発設定、Feature Flag、バージョン管理方針をカバー。環境変数設計、設定管理方針の決定時に使用。 |
環境設定管理ガイド
環境設定管理のフレームワーク非依存な設計ガイド。
環境分離の原則
環境の種類
| 環境 | 目的 | 特徴 |
|---|
| development | ローカル開発 | デバッグ有効、モック/ローカル DB |
| test | テスト実行 | テスト用 DB、外部サービスのモック |
| staging | 本番前検証 | 本番に近い構成、テストデータ |
| production | 本番運用 | 最適化済み、実データ |
設定の階層
デフォルト値（コード内）
↓ 上書き
環境別設定ファイル
↓ 上書き
環境変数
↓ 上書き
コマンドライン引数（あれば）
→ 環境変数が最も優先度が高い
環境変数の設計
命名規則
{APP_PREFIX}_{CATEGORY}_{NAME}
例:
MYAPP_DB_HOST
MYAPP_DB_PORT
MYAPP_REDIS_URL
MYAPP_AUTH_JWT_SECRET
MYAPP_FEATURE_DARK_MODE
原則:
- UPPER_SNAKE_CASE
- アプリケーションプレフィックスを付ける（衝突防止）
- カテゴリでグルーピング
- 意味が明確な名前
型安全性とバリデーション
原則:
- アプリケーション起動時にすべての必須変数を検証する
- 型変換を明示的に行う（文字列 → 数値、真偽値）
- 不足している場合は即座にエラーで停止する（サイレント失敗しない）
- デフォルト値は開発環境用のみ設定
バリデーション対象:
- 必須変数の存在確認
- 型の妥当性（ポート番号が数値か、URL が有効か）
- 値の範囲（ポート番号が 1-65535 か）
- 形式の妥当性（メールアドレス、URL の形式）
よくある環境変数
アプリケーション:
NODE_ENV / APP_ENV : 環境名
PORT : リッスンポート
LOG_LEVEL : ログレベル
データベース:
DATABASE_URL : 接続文字列
DB_HOST / DB_PORT : 個別指定
DB_POOL_SIZE : コネクションプール
認証:
JWT_SECRET : JWT 署名キー
SESSION_SECRET : セッション秘密鍵
OAUTH_CLIENT_ID : OAuth クライアント ID
外部サービス:
API_BASE_URL : バックエンド API の URL
REDIS_URL : Redis 接続先
S3_BUCKET : ストレージバケット
設定ファイルの構成
パターン 1: 環境別設定ファイル
config/
├── default.ts # 共通デフォルト値
├── development.ts # 開発環境
├── test.ts # テスト環境
├── staging.ts # ステージング環境
└── production.ts # 本番環境
→ APP_ENV に基づいて読み込むファイルを選択
パターン 2: 単一設定ファイル + 環境変数
config.ts
export const config = {
port: env("PORT", 3000),
db: {
host: env("DB_HOST", "localhost"),
port: env("DB_PORT", 5432),
},
};
→ 環境変数で上書き可能なデフォルト値を定義
設定のグルーピング
config = {
app: { port, env, logLevel },
db: { host, port, name, poolSize },
auth: { jwtSecret, sessionTtl },
external: { apiBaseUrl, redisUrl },
features: { darkMode, betaFeatures },
}
→ カテゴリごとにグループ化して可読性を向上
シークレットとの分離
環境変数として管理するもの（非機密）:
- ポート番号
- ログレベル
- 環境名
- Feature Flag
シークレットとして管理するもの（機密）:
- API キー
- DB パスワード
- JWT シークレット
- OAuth クライアントシークレット
- 暗号化キー
シークレットの管理方法:
- 開発環境: .env ファイル（git 管理外）
- 本番環境: シークレットマネージャー or CI/CD の変数
- ❌ ソースコードにハードコード
- ❌ git にコミット
ローカル開発環境の設定
.env ファイルの管理
.env → git 管理外（.gitignore に追加）
.env.example → git 管理対象（テンプレート）
.env.test → テスト用（git 管理対象可）
.env.local → 個人設定（git 管理外）
.env.example の記載方法:
DB_HOST=localhost
DB_PORT=5432
DB_NAME=myapp_dev
JWT_SECRET= # ← 空にして「要設定」を示す
API_KEY= # ← 空にして「要設定」を示す
セットアップスクリプト
原則:
- 新しい開発者が最小限の手順で環境構築できる
- .env.example → .env のコピーを自動化
- 必要な外部サービス（DB等）の起動を自動化
- セットアップ手順を README に明記
Feature Flag
設計パターン
基本: 環境変数で管理
FEATURE_DARK_MODE=true
FEATURE_NEW_CHECKOUT=false
判断基準:
- シンプルなフラグ → 環境変数
- ユーザーごとの出し分け → Feature Flag サービス
- A/B テスト → 専用サービス
原則:
- フラグ名は機能を明確に表す
- デフォルトは無効（false）
- 使い終わったフラグは速やかに削除
- フラグの一覧を管理する
ライフサイクル
1. フラグ作成（新機能開発開始）
2. 開発環境で有効化
3. ステージングで検証
4. 本番で段階的にロールアウト
5. 全ユーザーに展開完了
6. フラグとコード分岐を削除
バージョン管理方針
コミットすべきもの
✅ コミット対象:
- 設定ファイルのテンプレート（.env.example）
- 環境別設定ファイル（非機密）
- ロックファイル（package-lock.json 等）
- CI/CD 設定ファイル
- Docker / docker-compose 設定
❌ コミットしてはいけないもの:
- .env ファイル（シークレット含む）
- 個人の IDE 設定
- ローカル用の設定上書きファイル
- ビルド成果物
.gitignore の設定
# 環境設定
.env
.env.local
.env.*.local
# コミットすべきテンプレート（gitignore しない）
# .env.example
# .env.test（テスト用、機密情報なし）
レビューチェックリスト
リファレンス
