Cloudflare Wrangler CLIでよく使う設定とコマンド

Wrangler CLIの概要

Wranglerは、Cloudflare Workers/Pagesを中心とした開発・ビルド・デプロイを支援する公式CLIです。ローカルでの反復開発から、エッジへの本番デプロイ、運用監視、リソースの管理までを扱えます。v3以降は Miniflare v3 と、Workersコアランタイムのオープンソース実装である workerd を基盤とし、ローカルと本番の実行環境の差を小さくする方向で設計されています。

この記事では、Wranglerの主要コマンド、設定ファイル（TOML/JSONC）と環境管理、Cloudflareサービス群との連携、デバッグ、CI/CD統合を、実務の手順に寄せて整理します。

---

Wranglerの主要コマンド

1.1 プロジェクトの初期化と開発

• wrangler init <name>: 対話的に新規Workersプロジェクトを作成します。雛形の選択、型設定、テスト構成など初期化一式が整います。
• wrangler generate <name> <template>: 既定テンプレートからプロジェクトを迅速に生成します。検証済みのテンプレート起点で実装を進めたい場合に有効です。
• wrangler dev: ローカル開発サーバーを起動し、ホットリロードで変更を即時反映します。Miniflare v3+workerdにより、本番と同一クラスのコンテナで挙動を再現します。
  • --env <environment_name>: 設定ファイルの特定環境（例：[env.staging]）を読み込んで実行。
  • --config <file_path>: 既定のwrangler.toml（またはwrangler.jsonc）以外の設定を指定。モノレポや複数ワーカーの切替に有効。
  • --remote: コードは手元で編集しつつ、リクエスト処理をCloudflareエッジ上で実行・検証します。

設計観点では、--envは単一設定ファイル内での多環境切替（開発／ステージング／本番）に、--configは設定ファイル自体を分離したマルチワーカー運用や厳密なCI設定に適します。両者の役割を使い分けることで、単純構成から高度なモノレポ運用まで無理なく拡張できます。

1.2 デプロイと運用管理

• wrangler deploy: コードと設定を一括アップロードし、即時に新バージョンへ切替える「オールアットワンス」モデルを採用します。--envで環境別デプロイが可能です。
• wrangler versions upload / wrangler versions deploy: 先にバージョンだけをアップロードし、後段でトラフィック配分を制御しながら段階的に切替える運用（例：カナリア）を実現します。大規模ワークロードやリスク分散に有効です。
• wrangler delete: ワーカーをCloudflareから削除します。
• wrangler whoami: 現在の認証情報とアカウントIDを確認します。
• wrangler tail: 公開中ワーカーのログ（console.logや例外）をストリーミング表示します。現場の観測に不可欠です。

1.3 コマンド一覧（抜粋）

• wrangler init / wrangler generate
• wrangler dev（--env/--config/--remote）
• wrangler deploy / wrangler versions {upload|deploy} / wrangler delete
• wrangler login / wrangler logout / wrangler whoami
• wrangler tail
• wrangler kv / wrangler r2 / wrangler d1 / wrangler secret / wrangler pages

---

設定ファイル wrangler.toml と wrangler.jsonc

2.1 役割とフォーマットの進化

設定ファイルは、ワーカー名、エントリーポイント、本番互換の互換性日付、各種サービスへのバインディングなど、ワーカー動作の「単一の信頼できる情報源（Source of Truth）」として機能します。従来のTOML（wrangler.toml）に加え、v3.91.0以降はJSONC（wrangler.jsonc/wrangler.json）も公式サポートされました。JSONCはエコシステム親和性とコメント可能性を兼ね、より広範な開発ツールチェーンと自然に統合できます。

2.2 基本項目と環境セクション

最低限の主要項目は以下の通りです。

• name: 公開名（ワーカー名）
• main: エントリースクリプトのパス
• compatibility_date: ランタイムの互換性日付
• workers_dev / route: *.workers.dev あるいは独自ドメインのルーティング定義
• バインディング: vars（非機密環境変数）、kv_namespaces、r2_buckets、d1_databases、durable_objects など

環境別の上書きは [env.<name>]（TOML）または "env": { "<name>": { ... } }（JSONC）で定義します。重要な注意点として、多くのバインディング（例：kv_namespaces/r2_buckets/vars）は環境間で自動継承されません。環境ごとの明示定義を促す設計により、誤ったリソース参照を未然に防ぎます。

2.3 設定例（TOML）

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-07-12"
workers_dev = true

[vars]
PUBLIC_FLAG = "on"

[[kv_namespaces]]
binding = "USERS_NOTIFICATION_CONFIG"
id = "<kv-namespace-id>"

[[r2_buckets]]
binding = "ASSETS"
bucket_name = "my-assets"

[env.staging]
name = "my-worker-staging"
workers_dev = true

  [[env.staging.kv_namespaces]]
  binding = "USERS_NOTIFICATION_CONFIG"
  id = "<kv-namespace-id-staging>"

  [[env.staging.r2_buckets]]
  binding = "ASSETS"
  bucket_name = "my-assets-staging"

2.4 設定例（JSONC）

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2024-07-12",
  "workers_dev": true,
  "vars": {
    "PUBLIC_FLAG": "on"
  },
  "kv_namespaces": [
    { "binding": "USERS_NOTIFICATION_CONFIG", "id": "<kv-namespace-id>" }
  ],
  "r2_buckets": [
    { "binding": "ASSETS", "bucket_name": "my-assets" }
  ],
  "env": {
    "staging": {
      "name": "my-worker-staging",
      "workers_dev": true,
      "kv_namespaces": [
        { "binding": "USERS_NOTIFICATION_CONFIG", "id": "<kv-namespace-id-staging>" }
      ],
      "r2_buckets": [
        { "binding": "ASSETS", "bucket_name": "my-assets-staging" }
      ]
    }
  }
}

---

第3章：Cloudflareエコシステムとの連携

3.1 データストアへのバインディング

CLIは、Workers KV / R2 / D1 / Durable Objects / AI / Vectorize 等と相互運用するためのコマンドを備えます。たとえば、KVでは次のように名前空間を生成し、設定に反映します。

wrangler kv namespace create USERS_NOTIFICATION_CONFIG

出力される id を設定ファイルの kv_namespaces に記述すると、コード側からは env.USERS_NOTIFICATION_CONFIG 経由でKVを操作できます。R2やD1も同様に、CLIで資源を作成→設定にバインド→env.<binding>で利用、という流れが定着しています。

3.2 シークレットと環境変数（スコープを明確化）

機密情報の取り扱いは、スコープ（どこで効くか）を明確に分けて運用します。混同しやすいポイントを先に整理します。

• wrangler secret（Cloudflare側に暗号化保存）

  • スコープ: 「ワーカー（script）× 環境（env）」単位です。環境間で自動継承されません。
  • 例: echo $API_KEY | wrangler secret put API_KEY --env production
  • 実行時アクセス: ワーカー内から env.API_KEY で参照します。
  • 補足: 同一ワーカーでも staging と production は別保管です。必要な環境すべてに投入してください。

• vars（設定ファイルに平文定義されバンドルへ埋め込み）

  • スコープ: 設定ファイル単位（[env]で環境別上書き可）。
  • 用途: ログレベルやフラグなど「非機密」のビルド時定数向け。秘密情報は置かないでください。

• .dev.vars / .env（ローカル専用）

  • スコープ: ローカル開発（wrangler dev / Miniflare）でのみ読み込まれます。本番にはアップロードされません。
  • 取り扱い: .gitignoreに含め、リポジトリへコミットしないでください。
  • 役割: 本番の secret に相当する値をローカルで模擬するための利便ファイルです（「Cloudflareのシークレット保管庫」ではありません）。

実務ガイド（How-to）:

1. ローカルでの開発

• 値は .dev.vars に書く（例: API_KEY=xxxx）。
• コードからは env.API_KEY を参照。wrangler dev が読み込みます。

2. 本番/ステージングへの登録

• 方式A（従来のワーカー単位）: CIから非対話で投入します。
  • 例: echo "$API_KEY" | wrangler secret put API_KEY --env production（ジョブのworking-directoryを対象ワーカーに合わせる）。
  • 差分確認や棚卸し: wrangler secret list --env production。
• 方式B（アカウント単位のSecrets Store／オープンベータ）: ダッシュボードまたはAPIでアカウントスコープにシークレットを登録し、対象ワーカーに割り当てて再利用します。利用可否（リージョン）や連携範囲、Wrangler統合の細部は随時更新されるため、最新ドキュメントを必ず参照してください。

3. モノレポ/複数ワーカーでの共有方針

• 共有・再利用が必要な場合は、以下のいずれかを選びます。
  • アカウントレベルの「Cloudflare Secrets Store（オープンベータ）」を利用し、中央管理下のシークレットを複数ワーカーで再利用する。
  • CIのSecretsマネージャ（例: GitHub Secrets）を「単一の真実の情報源」とし、各ワーカー環境へ都度 wrangler secret put で配布する。
  • 公開してよいメタデータであればKV/R2等へ格納し、アクセス制御を設計する。

Cloudflare Secrets Store はアカウントレベルで暗号化・冗長保存される集中管理型の保管庫で、現時点ではWorkersと互換があります（オープンベータ）。中国ネットワーク（JD Cloud運用）では未提供であり、今後他製品との連携が拡大予定です。導入時は、組織ポリシー（どこを単一の情報源にするか）、対象リージョン、運用チームの権限分離を考慮して選択してください。

この区別を守ると、「ローカルの便宜ファイル（.dev.vars）」と「Cloudflare側の本番用シークレット（wrangler secret）」、「非機密のvars」が混ざらず、安全かつ再現性の高い構成になります。

3.3 Pages Functionsとの協調

Pagesでも wrangler.toml を解釈可能で、静的アセットの出力ディレクトリを pages_build_output_dir で指定します。WorkersとPagesを単一のツールで束ねることで、静的配信とサーバーレス実行を組み合わせるハイブリッド構成を、自然な開発者体験で実現できます。

---

第4章：実践的なデバッグとトラブルシューティング

4.1 デバッグツールキット

• ローカルは wrangler dev が中核です。例外やログが即時に可視化され、初期段階での欠陥捕捉に寄与します。
• 本番の観測には wrangler tail が有効です。console.logの出力と例外をリアルタイムに収集し、リクエストコンテキストに即した診断が可能です。

4.2 よくあるエラーと対処

• 設定ファイル未検出（CIでのwrangler.toml/wrangler.jsonc不足）: ワークスペースルートやworking-directoryの誤りで発生します。モノレポでは各パッケージ直下に設定を保持し、CIの実行ディレクトリを明示します。
• 互換性日付／ランタイム依存の不一致: compatibility_dateの更新やWrangler/Miniflare/workerdのバージョン差で例外が起きる場合があります。ランタイムの更新時はローカル→ステージングの順に検証し、段階的に拡大します。
• 大規模構成でのAPIタイムアウト（多数のバインディングを伴うデプロイ）: versions upload→段階デプロイに切替え、再試行や分割デプロイを検討します。並行度の調整やリソース作成順序の見直しも有効です。

4.3 メジャーバージョン移行の勘所

v3では「ローカル・バイ・デフォルト」な開発体験が導入され、Miniflare v3+workerdが標準基盤になりました。既存プロジェクトの移行では、設定フォーマット（TOML→JSONCの選択肢拡大）とランタイム互換性の確認、開発・CIのフラグ運用（--env/--config）を改めて棚卸しすると安全です。

---

第5章：CI/CDパイプラインへの統合

5.1 GitHub Actionsによる自動デプロイ

Cloudflare公式の wrangler-action を利用すると、GitHubからの自動デプロイが容易です。インタラクティブなwrangler loginを使わず、APIトークンとアカウントIDをGitHub Secretsで管理します。

name: Deploy Worker
on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: ./packages/edge-app # モノレポ例
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - name: Publish with Wrangler
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CF_API_TOKEN }}
          accountId: ${{ secrets.CF_ACCOUNT_ID }}
          command: deploy --config wrangler.jsonc --env production

5.2 APIトークンの最小権限設計

トークンはWorkers編集に必要な権限へ最小化し、必要に応じてKV/R2/D1などの範囲を限定します。Secretsに保存し、ワークフローから参照するだけに留めれば、リポジトリに機密が漏れる経路を遮断できます。DevSecOpsの要諦として「最小権限＋秘匿の自動化」を徹底します。

5.3 多環境・モノレポ運用の型

• 多環境は --env による切替を基本としつつ、設定分離が望ましい場合は --config でファイルを分けます。
• モノレポではパッケージ毎に設定とSecretsスコープを分け、CIのworking-directoryで明示的に対象を限定します。
• 段階リリースは versions upload→versions deploy で配分制御を組み込み、ロールバック手順も対で整備します。

---

結論：Wrangler CLIの今後の展望

Wranglerは、単なるデプロイツールを越えて「本番互換の開発実行環境」と「Cloudflare Developer Platformの制御面」を兼ね備えた中核的基盤へ成熟しました。ローカルと本番の同一性、JSONCサポート、公式アクションによるCI/CD親和性は、利便性・性能・安全性を同時に押し上げています。今後もAI/Vectorize等の新サービス連携が深化し、より大規模で複雑なワークロードを無理なく扱える方向へ進むでしょう。開発者は、--env/--config/versions系コマンドを起点に、設計段階で運用要件（段階リリース、最小権限、観測性）を織り込むことで、堅牢な継続デリバリーを確立できます。

---

参考文献

• Cloudflare Docs: Wrangler（CLIリファレンス）
  • https://developers.cloudflare.com/workers/wrangler/
• Cloudflare Docs: Configuration（wrangler.toml / wrangler.jsonc）
  • https://developers.cloudflare.com/workers/wrangler/configuration/
• Miniflare v3（ローカルWorkersエミュレーター）
  • https://github.com/cloudflare/miniflare
• workerd（WorkersランタイムのOSS）
  • https://github.com/cloudflare/workerd
• wrangler-action（公式GitHub Actions）
  • https://github.com/cloudflare/wrangler-action
• Cloudflare Docs: tail（ログストリーミング）
  • https://developers.cloudflare.com/workers/wrangler/commands/#tail
• Cloudflare Docs: versions（段階リリース）
  • https://developers.cloudflare.com/workers/wrangler/commands/#versions
• Cloudflare Docs: Secretsと環境変数
  • https://developers.cloudflare.com/workers/wrangler/secrets/