wrangler

Wrangler CLI

Wrangler CLI のフラグ、設定フィールド、サブコマンドに関する知識は古くなっている可能性があります。Wrangler に関する作業では、事前学習よりも情報の取得を優先してください。

情報の取得元

Wrangler のコマンドや設定を作成または確認する前に、必ず最新の情報を取得してください。CLI のフラグ、設定フィールド、バインディングの形式について、学習済みの知識に頼らないでください。

情報源	取得方法	用途
Wrangler のドキュメント	https://developers.cloudflare.com/workers/wrangler/	CLI コマンド、フラグ、設定リファレンス
Wrangler の設定スキーマ	node_modules/wrangler/config-schema.json	設定フィールド、バインディングの形式、許可される値
Cloudflare のドキュメント	検索ツールまたは https://developers.cloudflare.com/workers/	API リファレンス、互換性の日付／フラグ

最初に：Wrangler のインストールを確認する

wrangler --version  # Requires v4.x+

インストールされていない場合：

npm install -D wrangler@latest

主なガイドライン

• wrangler.jsonc を使用する：TOML より JSON の設定を優先してください。新しい機能は JSON でのみ利用できます。
• compatibility_date を設定する：最近の日付（30 日以内）を使用してください。https://developers.cloudflare.com/workers/configuration/compatibility-dates/ を確認してください。
• 設定を変更したら型を生成する：wrangler types を実行して TypeScript のバインディングを更新してください。
• ローカル開発ではデフォルトでローカルストレージを使用する：remote: true を設定しない限り、バインディングにはローカルのシミュレーションが使用されます。
• デプロイ前に設定を検証する：wrangler check を実行して、早い段階でエラーを検出してください。
• ステージング／本番環境には環境を使用する：設定ファイルで env.staging と env.production を定義してください。

クイックスタート：新しい Worker

# Initialize new project
npx wrangler init my-worker

# Or with a framework
npx create-cloudflare@latest my-app

クイックリファレンス：主なコマンド

タスク	コマンド
ローカル開発サーバーを起動する	wrangler dev
Cloudflare にデプロイする	wrangler deploy
デプロイのドライラン	wrangler deploy --dry-run
TypeScript の型を生成する	wrangler types
設定を検証する	wrangler check
ライブログを表示する	wrangler tail
Worker を削除する	wrangler delete
認証状態を確認する	wrangler whoami

---

設定（wrangler.jsonc）

最小限の設定

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-01",
}

バインディングを含む完全な設定

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-01",
  "compatibility_flags": ["nodejs_compat_v2"],

  // Environment variables
  "vars": {
    "ENVIRONMENT": "production",
  },

  // KV Namespace
  "kv_namespaces": [{ "binding": "KV", "id": "<KV_NAMESPACE_ID>" }],

  // R2 Bucket
  "r2_buckets": [{ "binding": "BUCKET", "bucket_name": "my-bucket" }],

  // D1 Database
  "d1_databases": [{ "binding": "DB", "database_name": "my-db", "database_id": "<DB_ID>" }],

  // Workers AI (always remote)
  "ai": { "binding": "AI" },

  // Vectorize
  "vectorize": [{ "binding": "VECTOR_INDEX", "index_name": "my-index" }],

  // Hyperdrive
  "hyperdrive": [{ "binding": "HYPERDRIVE", "id": "<HYPERDRIVE_ID>" }],

  // Durable Objects
  "durable_objects": {
    "bindings": [{ "name": "COUNTER", "class_name": "Counter" }],
  },

  // Cron triggers
  "triggers": {
    "crons": ["0 * * * *"],
  },

  // Environments
  "env": {
    "staging": {
      "name": "my-worker-staging",
      "vars": { "ENVIRONMENT": "staging" },
    },
  },
}

設定から型を生成する

# Generate worker-configuration.d.ts
wrangler types

# Custom output path
wrangler types ./src/env.d.ts

# Check types are up to date (CI)
wrangler types --check

---

ローカル開発

開発サーバーを起動する

# Local mode (default) - uses local storage simulation
wrangler dev

# With specific environment
wrangler dev --env staging

# Force local-only (disable remote bindings)
wrangler dev --local

# Remote mode - runs on Cloudflare edge (legacy)
wrangler dev --remote

# Custom port
wrangler dev --port 8787

# Live reload for HTML changes
wrangler dev --live-reload

# Test scheduled/cron handlers
wrangler dev --test-scheduled
# Then visit: http://localhost:8787/__scheduled

ローカル開発でリモートバインディングを使用する

バインディングの設定で remote: true を使用すると、ローカルで実行しながら実際のリソースに接続できます。

{
  "r2_buckets": [{ "binding": "BUCKET", "bucket_name": "my-bucket", "remote": true }],
  "ai": { "binding": "AI", "remote": true },
  "vectorize": [{ "binding": "INDEX", "index_name": "my-index", "remote": true }],
}

リモートバインディングの推奨項目：AI（必須）、Vectorize、Browser Rendering、mTLS、Images。

ローカルシークレット

ローカル開発用のシークレットとして .dev.vars を作成します。

API_KEY=local-dev-key
DATABASE_URL=postgres://localhost:5432/dev

---

デプロイ

Worker をデプロイする

# Deploy to production
wrangler deploy

# Deploy specific environment
wrangler deploy --env staging

# Dry run (validate without deploying)
wrangler deploy --dry-run

# Keep dashboard-set variables
wrangler deploy --keep-vars

# Minify code
wrangler deploy --minify

シークレットを管理する

# Set secret interactively
wrangler secret put API_KEY

# Set from stdin
echo "secret-value" | wrangler secret put API_KEY

# List secrets
wrangler secret list

# Delete secret
wrangler secret delete API_KEY

# Bulk secrets from JSON file
wrangler secret bulk secrets.json

バージョンとロールバック

# List recent versions
wrangler versions list

# View specific version
wrangler versions view <VERSION_ID>

# Rollback to previous version
wrangler rollback

# Rollback to specific version
wrangler rollback <VERSION_ID>

---

KV（Key-Value Store）

ネームスペースを管理する

# Create namespace
wrangler kv namespace create MY_KV

# List namespaces
wrangler kv namespace list

# Delete namespace
wrangler kv namespace delete --namespace-id <ID>

キーを管理する

# Put value
wrangler kv key put --namespace-id <ID> "key" "value"

# Put with expiration (seconds)
wrangler kv key put --namespace-id <ID> "key" "value" --expiration-ttl 3600

# Get value
wrangler kv key get --namespace-id <ID> "key"

# List keys
wrangler kv key list --namespace-id <ID>

# Delete key
wrangler kv key delete --namespace-id <ID> "key"

# Bulk put from JSON
wrangler kv bulk put --namespace-id <ID> data.json

設定のバインディング

{
  "kv_namespaces": [{ "binding": "CACHE", "id": "<NAMESPACE_ID>" }],
}

---

R2（Object Storage）

バケットを管理する

# Create bucket
wrangler r2 bucket create my-bucket

# Create with location hint
wrangler r2 bucket create my-bucket --location wnam

# List buckets
wrangler r2 bucket list

# Get bucket info
wrangler r2 bucket info my-bucket

# Delete bucket
wrangler r2 bucket delete my-bucket

オブジェクトを管理する

# Upload object
wrangler r2 object put my-bucket/path/file.txt --file ./local-file.txt

# Download object
wrangler r2 object get my-bucket/path/file.txt

# Delete object
wrangler r2 object delete my-bucket/path/file.txt

設定のバインディング

{
  "r2_buckets": [{ "binding": "ASSETS", "bucket_name": "my-bucket" }],
}

---

D1（SQL Database）

データベースを管理する

# Create database
wrangler d1 create my-database

# Create with location
wrangler d1 create my-database --location wnam

# List databases
wrangler d1 list

# Get database info
wrangler d1 info my-database

# Delete database
wrangler d1 delete my-database

SQL を実行する

# Execute SQL command (remote)
wrangler d1 execute my-database --remote --command "SELECT * FROM users"

# Execute SQL file (remote)
wrangler d1 execute my-database --remote --file ./schema.sql

# Execute locally
wrangler d1 execute my-database --local --command "SELECT * FROM users"

マイグレーション

# Create migration
wrangler d1 migrations create my-database create_users_table

# List pending migrations
wrangler d1 migrations list my-database --local

# Apply migrations locally
wrangler d1 migrations apply my-database --local

# Apply migrations to remote
wrangler d1 migrations apply my-database --remote

エクスポート／バックアップ

# Export schema and data
wrangler d1 export my-database --remote --output backup.sql

# Export schema only
wrangler d1 export my-database --remote --output schema.sql --no-data

設定のバインディング

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "my-database",
      "database_id": "<DATABASE_ID>",
      "migrations_dir": "./migrations",
    },
  ],
}

---

Vectorize（Vector Database）

インデックスを管理する

# Create index with dimensions
wrangler vectorize create my-index --dimensions 768 --metric cosine

# Create with preset (auto-configures dimensions/metric)
wrangler vectorize create my-index --preset @cf/baai/bge-base-en-v1.5

# List indexes
wrangler vectorize list

# Get index info
wrangler vectorize get my-index

# Delete index
wrangler vectorize delete my-index

ベクトルを管理する

# Insert vectors from NDJSON file
wrangler vectorize insert my-index --file vectors.ndjson

# Query vectors
wrangler vectorize query my-index --vector "[0.1, 0.2, ...]" --top-k 10

設定のバインディング

{
  "vectorize": [{ "binding": "SEARCH_INDEX", "index_name": "my-index" }],
}

---

Hyperdrive（Database Accelerator）

設定を管理する

# Create config
wrangler hyperdrive create my-hyperdrive \
  --connection-string "postgres://user:pass@host:5432/database"

# List configs
wrangler hyperdrive list

# Get config details
wrangler hyperdrive get <HYPERDRIVE_ID>

# Update config
wrangler hyperdrive update <HYPERDRIVE_ID> --origin-password "new-password"

# Delete config
wrangler hyperdrive delete <HYPERDRIVE_ID>

設定のバインディング

{
  "compatibility_flags": ["nodejs_compat_v2"],
  "hyperdrive": [{ "binding": "HYPERDRIVE", "id": "<HYPERDRIVE_ID>" }],
}

---

Workers AI

モデルを一覧表示する

# List available models
wrangler ai models

# List finetunes
wrangler ai finetune list

設定のバインディング

{
  "ai": { "binding": "AI" },
}

注：Workers AI は常にリモートで実行されるため、ローカル開発中も使用量に応じた料金が発生します。

---

キュー

キューを管理する

# Create queue
wrangler queues create my-queue

# List queues
wrangler queues list

# Delete queue
wrangler queues delete my-queue

# Add consumer to queue
wrangler queues consumer add my-queue my-worker

# Remove consumer
wrangler queues consumer remove my-queue my-worker

設定のバインディング

{
  "queues": {
    "producers": [{ "binding": "MY_QUEUE", "queue": "my-queue" }],
    "consumers": [
      {
        "queue": "my-queue",
        "max_batch_size": 10,
        "max_batch_timeout": 30,
      },
    ],
  },
}

---

コンテナー

イメージのビルドとプッシュ

# Build container image
wrangler containers build -t my-app:latest .

# Build and push in one command
wrangler containers build -t my-app:latest . --push

# Push existing image to Cloudflare registry
wrangler containers push my-app:latest

コンテナの管理

# List containers
wrangler containers list

# Get container info
wrangler containers info <CONTAINER_ID>

# Delete container
wrangler containers delete <CONTAINER_ID>

イメージの管理

# List images in registry
wrangler containers images list

# Delete image
wrangler containers images delete my-app:latest

外部レジストリの管理

# List configured registries
wrangler containers registries list

# Configure external registry (e.g., ECR)
wrangler containers registries configure <DOMAIN> \
  --public-credential <AWS_ACCESS_KEY_ID>

# Delete registry configuration
wrangler containers registries delete <DOMAIN>

---

ワークフロー

ワークフローの管理

# List workflows
wrangler workflows list

# Describe workflow
wrangler workflows describe my-workflow

# Trigger workflow instance
wrangler workflows trigger my-workflow

# Trigger with parameters
wrangler workflows trigger my-workflow --params '{"key": "value"}'

# Delete workflow
wrangler workflows delete my-workflow

ワークフローインスタンスの管理

# List instances
wrangler workflows instances list my-workflow

# Describe instance
wrangler workflows instances describe my-workflow <INSTANCE_ID>

# Terminate instance
wrangler workflows instances terminate my-workflow <INSTANCE_ID>

設定のバインド

{
  "workflows": [
    {
      "binding": "MY_WORKFLOW",
      "name": "my-workflow",
      "class_name": "MyWorkflow",
    },
  ],
}

---

パイプライン

パイプラインの管理

# Create pipeline
wrangler pipelines create my-pipeline --r2 my-bucket

# List pipelines
wrangler pipelines list

# Show pipeline details
wrangler pipelines show my-pipeline

# Update pipeline
wrangler pipelines update my-pipeline --batch-max-mb 100

# Delete pipeline
wrangler pipelines delete my-pipeline

設定のバインド

{
  "pipelines": [{ "binding": "MY_PIPELINE", "pipeline": "my-pipeline" }],
}

---

シークレットストア

ストアの管理

# Create store
wrangler secrets-store store create my-store

# List stores
wrangler secrets-store store list

# Delete store
wrangler secrets-store store delete <STORE_ID>

ストア内のシークレットの管理

# Add secret to store
wrangler secrets-store secret put <STORE_ID> my-secret

# List secrets in store
wrangler secrets-store secret list <STORE_ID>

# Get secret
wrangler secrets-store secret get <STORE_ID> my-secret

# Delete secret from store
wrangler secrets-store secret delete <STORE_ID> my-secret

設定のバインド

{
  "secrets_store_secrets": [
    {
      "binding": "MY_SECRET",
      "store_id": "<STORE_ID>",
      "secret_name": "my-secret",
    },
  ],
}

---

Pages（フロントエンドのデプロイ）

# Create Pages project
wrangler pages project create my-site

# Deploy directory to Pages
wrangler pages deploy ./dist

# Deploy with specific branch
wrangler pages deploy ./dist --branch main

# List deployments
wrangler pages deployment list --project-name my-site

---

可観測性

ログの末尾を表示

# Stream live logs
wrangler tail

# Tail specific Worker
wrangler tail my-worker

# Filter by status
wrangler tail --status error

# Filter by search term
wrangler tail --search "error"

# JSON output
wrangler tail --format json

ロギングの設定

{
  "observability": {
    "enabled": true,
    "head_sampling_rate": 1,
  },
}

---

テスト

Vitest を使用したローカルテスト

npm install -D @cloudflare/vitest-pool-workers vitest

vitest.config.ts：

import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";

export default defineWorkersConfig({
  test: {
    poolOptions: {
      workers: {
        wrangler: { configPath: "./wrangler.jsonc" },
      },
    },
  },
});

スケジュールイベントのテスト

# Enable in dev
wrangler dev --test-scheduled

# Trigger via HTTP
curl http://localhost:8787/__scheduled

---

トラブルシューティング

よくある問題

問題	解決方法
command not found: wrangler	インストールします：npm install -D wrangler
認証エラー	wrangler login を実行します
設定の検証エラー	wrangler check を実行します
設定変更後の型エラー	wrangler types を実行します
ローカルストレージが保持されない	.wrangler/state ディレクトリを確認します
Worker でバインドが未定義	バインド名が設定と完全に一致していることを確認します

デバッグコマンド

# Check auth status
wrangler whoami

# Validate config
wrangler check

# View config schema
wrangler docs configuration

---

ベストプラクティス

1. wrangler.jsonc をバージョン管理する：Worker 設定の信頼できる情報源として扱います。
2. 自動プロビジョニングを使用する：デプロイ時に自動作成するには、リソース ID を省略します。
3. CI で wrangler types を実行する：バインドの不一致を検出するため、ビルド手順に追加します。
4. 環境を使用する：env.staging と env.production でステージング環境と本番環境を分離します。
5. compatibility_date を設定する：新しいランタイム機能を利用できるよう、四半期ごとに更新します。
6. ローカルシークレットには .dev.vars を使用する：シークレットを設定ファイルにコミットしないでください。
7. まずローカルでテストする：デプロイ前にローカルバインドを使って wrangler dev を実行します。
8. 大規模なデプロイの前に --dry-run を使用する：デプロイせずに変更を検証します。