コンテンツにスキップ
個人開発者のための Cloudflare CLI 完全攻略ガイド

第10章: マルチ環境設計（dev/staging/prod）（実践チュートリアル）

個人開発でよくある悲劇に「開発用データを消すつもりが、本番データベースに接続していて本番ユーザーデータを吹き飛ばした」という事故があります。 Cloudflare Workersでは、wrangler.jsonc（または wrangler.toml）に env ディレクティブを定義することで、同一コードベースのまま ローカル（dev）/ ステージング（staging）/ 本番（production） のDB・KV・環境変数を完全に切り離すことができます。

本チュートリアルのゴール

  • dev、staging、production それぞれに個別のD1データベースとKVを作成
  • wrangler.jsonc での完全分離設定テンプレートの記述
  • CLIフラグ（--env）によるステージング・本番への安全なデプロイ
  • 環境ごとに異なるシークレット（Stripeキー等）の管理
【環境分離の全体像】
[ コード (Git main) ]
      ├── (デフォルト / dev)   --> DB: my-db-dev      / ENV: "development"
      ├── (--env staging)     --> DB: my-db-staging  / ENV: "staging"
      └── (--env production)  --> DB: my-db-prod     / ENV: "production"

Step 1: 各環境用のD1データベースを作成

まずはCLIから、ステージング用と本番用のDBを別々に作成します。

Terminal window
# 1. ステージング用DB作成
npx wrangler d1 create my-service-staging


# 2. 本番用DB作成
npx wrangler d1 create my-service-production

それぞれ出力される database_id をメモしておきます。

Step 2: wrangler.jsonc の環境分離定義

プロジェクトの wrangler.jsonc を以下のように設定します。

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-service",
  "main": "src/index.ts",
  "compatibility_date": "2024-09-01",
  "compatibility_flags": [
    "nodejs_compat"
  ],


  // 1. デフォルト設定（ローカル開発 / wrangler dev 時に適用）
  "vars": {
    "APP_ENV": "development",
    "API_URL": "http://localhost:8787"
  },
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "my-service-staging",
      "database_id": "xxxxxxxx-staging-id"
    }
  ],


  // 2. 環境別のオーバーライド設定
  "env": {
    // ステージング環境
    "staging": {
      "name": "my-service-staging",
      "vars": {
        "APP_ENV": "staging",
        "API_URL": "https://staging-api.my-domain.com"
      },
      "d1_databases": [
        {
          "binding": "DB",
          "database_name": "my-service-staging",
          "database_id": "xxxxxxxx-staging-id"
        }
      ]
    },


    // 本番環境
    "production": {
      "name": "my-service-production",
      "routes": [
        { "pattern": "api.my-domain.com/*", "zone_name": "my-domain.com" }
      ],
      "vars": {
        "APP_ENV": "production",
        "API_URL": "https://api.my-domain.com"
      },
      "d1_databases": [
        {
          "binding": "DB",
          "database_name": "my-service-production",
          "database_id": "yyyyyyyy-production-id"
        }
      ]
    }
  }
}

Step 3: 各環境へのシークレット登録

Stripeや決済サービスのAPIキーは、テスト用キー（sk_test_...）と本番用キー（sk_live_...）を厳格に分ける必要があります。

Terminal window
# ステージング環境にテスト用APIキーを登録
npx wrangler secret put STRIPE_SECRET_KEY --env staging
# (プロンプトで sk_test_... を入力)


# 本番環境に本番用APIキーを登録
npx wrangler secret put STRIPE_SECRET_KEY --env production
# (プロンプトで sk_live_... を入力)

登録されているか確認します（値自体は暗号化されているためキー名のみ表示されます）。

Terminal window
npx wrangler secret list --env staging
npx wrangler secret list --env production

Step 4: マイグレーション適用の安全運用

新しいテーブルやカラムを追加した際、適用する対象を --env で明示します。

Terminal window
# 1. まずはローカルでテスト
npx wrangler d1 migrations apply DB --local


# 2. ステージング環境へ適用して動作確認
npx wrangler d1 migrations apply DB --remote --env staging


# 3. 最後に本番環境へ適用
npx wrangler d1 migrations apply DB --remote --env production

[!IMPORTANT] DBバインディング名（DB）を指定する
--env を指定することで、Wranglerが自動的にその環境に定義された database_id を読み取って適用します。間違えて本番IDに開発SQLを投げてしまうリスクがゼロになります。

Step 5: 環境別デプロイコマンド

Terminal window
# ステージングへのデプロイ（https://my-service-staging.workers.dev 等）
npx wrangler deploy --env staging


# 本番へのデプロイ（https://api.my-domain.com）
npx wrangler deploy --env production

まとめ

  1. wrangler.jsonc の env: ステージングと本番で別のWorker名・別のDB ID・別の環境変数を割り当てる。
  2. --env フラグ: シークレット登録、マイグレーション、デプロイのすべてで一貫して指定する。
  3. 安全第一: この設定を行うだけで、個人開発でもエンタープライズ並みの堅牢なリリース運用が実現できます。

次章（第11章）では、このCloudflareリソース全体をコードで宣言・自動管理する Terraform（IaC） のハンズオンに進みます。

💡 用語解説コラム

[!NOTE] 環境分離 (Environment Isolation)
開発中（dev）、動作確認用（staging）、一般公開（production）でDBやAPIキーを完全に切り離す設計。テストデータ削除スクリプトが本番DBに直撃するなどの大惨事を防止します。