cloudflare-deploy

Cloudflare のデプロイ

Cloudflare の操作には cf を使用します。以下の判断ツリーから製品を選び、その実行環境／API リファレンスと最新の cf CLI ガイドを参照してください。

前提条件

• Node.js 24 以降と pnpm が必要です。npm パッケージの cf をインストールしてください。@cloudflare/cf ではありません。
• cf をプロジェクトの devDependencies に含め、ロックファイルをコミットしてください。確認済みの例では [email protected] と @cloudflare/vite-plugin@beta を使用しています。アップグレード時は、ヘルプと型を再確認してください。
• Workers では cloudflare.config.ts を使用します。既存の Wrangler プロジェクトでは、cf migrate --dry-run を実行してから cf migrate を実行し、プロジェクトコマンドを使う前に、移行後の対応項目を解決してください。自動設定では以前のバインディングはインポートされません。

認証（デプロイ前に必須）

公開またはアカウントリソースを変更する前に、認証を確認してください。

pnpm exec cf auth whoami

認証を参照してください。ローカルでは pnpm exec cf auth login を使用します。cf は独自のログイン認証情報を使用します。CI では CLOUDFLARE_API_TOKEN と CLOUDFLARE_ACCOUNT_ID を設定してください。デプロイのドライランには認証情報は不要です。

実行前にコマンドを確認する

pnpm exec cf cli search "create a D1 database"
pnpm exec cf schema d1 create
pnpm exec cf d1 create --help

検索クエリには、操作とリソースの種類だけを記述してください。名前と ID は検索ではなく、見つかったコマンドに渡してください。API コマンドは stdout に JSON を、stderr に進捗を出力します。リソースコマンドでは通常、ID とリモートデータを使用します。Wrangler の --remote、--env、--json、--yes フラグをコピーするのではなく、--local に対応しているか確認してください。

references/ を読むタイミング

最新の CLI、移行、設定、ビルドに関するガイダンスは references/cf/ にあります。製品リファレンスには SDK と実行環境に関する情報が残されています。legacy と記されたファイルは、移行元としてのみ、古い CLI／設定の例を保存しています。そこにある Wrangler の例を実行したり、そこから新しい Wrangler 設定を生成したりしないでください。意図する操作を cf の検索／スキーマと型付きバインディングを使って実現してください。

目安：

• 製品を選ぶ場合：以下の判断ツリーを使い、references/<picked-product>/ を読み込みます。
• cloudflare.config.ts を作成する場合：最初に設定を読んでください。
• CI/CD を設定する場合：GitHub Actionsを読んでください。
• デプロイに失敗した場合：cf の注意事項を読んでから、製品の実行環境に関する注意事項を確認してください。
• 以下の最小例で扱うのは Workers + KV + シークレットです。それ以上の内容については、リファレンスを参照してください。

Worker の最小例（コピーして開始）

この Worker、KV バインディング 1 つ、シークレット 1 つから始めます。型チェックの前に、設定リファレンスに記載された TypeScript のセットアップを適用してください。

// cloudflare.config.ts
import { bindings, defineConfig } from "cf/config";
import * as entrypoint from "./src/index.ts" with { type: "cf-worker" };

export default defineConfig({
  worker: {
    name: "my-worker",
    entrypoint,
    compatibilityDate: "2026-09-30", // Today's date for a new Worker
    observability: { enabled: true },
    env: {
      CACHE: bindings.kv({ id: "REPLACE_WITH_KV_ID" }),
      API_SECRET: bindings.secret(),
    },
  },
});

// vite.config.ts
import { cloudflare } from "@cloudflare/vite-plugin";
import { defineConfig } from "vite";
export default defineConfig({ plugins: [cloudflare()] });

// src/index.ts
export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    const hit = await env.CACHE.get("greeting");
    return new Response(hit ?? "hello");
  }
} satisfies ExportedHandler<Env>;

初期設定コマンド：

pnpm add -D cf @cloudflare/vite-plugin@beta vite typescript
pnpm exec cf kv namespaces create --title CACHE # Copy the returned ID into config
pnpm exec cf workers types                      # Generates .cloudflare/types/index.d.ts
pnpm exec cf dev                                # Vite reports the local URL
pnpm exec cf deploy --dry-run --secrets-file .env.production
pnpm exec cf deploy --secrets-file .env.production

デプロイ用の無視対象 .env.production と、ローカル開発用の .dev.vars に API_SECRET を設定してください。bindings.secret() を宣言すると、デプロイ時の検証でその値が必須になります。CLI プロセス内の dotenvx の値が Worker のシークレットとして自動的に設定されることはありません。tsconfig.json に .cloudflare/types を含めてください。TypeScript のセットアップ全体については、設定リファレンスを参照してください。既存の Worker の互換性の日付を変更する際は、慎重に行ってください。

確認済みの cf ベータ版では、コマンドが検索／ヘルプに表示される場合でも、ライブログのストリーミングと従来の Pages アセットのデプロイには対応していません。確認にはダッシュボードの Workers Logs を使用し、新しい Web プロジェクトでは Workers の静的アセットを使用してください。従来の Pages プロジェクトでは、移行を計画しながらデプロイが機能する状態を維持してください。cf pages deploy に相当する機能を推測して作らないでください。制限事項を参照してください。

Pages／D1／Durable Objects／複数環境／CI については、references/ を参照してください。

クイック判断ツリー

「コードを実行したい」

Need to run code?
├─ Serverless functions at the edge → workers/
├─ Full-stack web app with Git deploys → workers/ (framework) + static-assets/
├─ Maintain or migrate an existing Pages app → pages/ (legacy reference)
├─ Stateful coordination/real-time → durable-objects/
├─ Long-running multi-step jobs → workflows/
├─ Run containers → containers/
├─ Multi-tenant (customers deploy code) → workers-for-platforms/
├─ Scheduled tasks (cron) → cron-triggers/
├─ Lightweight edge logic (modify HTTP) → snippets/
├─ Process Worker execution events (logs/observability) → tail-workers/
└─ Optimize latency to backend infrastructure → smart-placement/

「データを保存したい」

Need storage?
├─ Key-value (config, sessions, cache) → kv/
├─ Relational SQL → d1/ (SQLite) or hyperdrive/ (existing Postgres/MySQL)
├─ Object/file storage (S3-compatible) → r2/
├─ Message queue (async processing) → queues/
├─ Vector embeddings (AI/semantic search) → vectorize/
├─ Strongly-consistent per-entity state → durable-objects/ (DO storage)
├─ Secrets management → secrets-store/
├─ Streaming ETL to R2 → pipelines/
└─ Persistent cache (long-term retention) → cache-reserve/

「AI／ML を使いたい」

Need AI?
├─ Run inference (LLMs, embeddings, images) → workers-ai/
├─ Vector database for RAG/search → vectorize/
├─ Build stateful AI agents → agents-sdk/
├─ Gateway for any AI provider (caching, routing) → ai-gateway/
└─ AI-powered search widget → ai-search/

「ネットワーク／接続機能を使いたい」

Need networking?
├─ Expose local service to internet → tunnel/
├─ TCP/UDP proxy (non-HTTP) → spectrum/
├─ WebRTC TURN server → turn/
├─ Private network connectivity → network-interconnect/
├─ Optimize routing → argo-smart-routing/
├─ Optimize latency to backend (not user) → smart-placement/
└─ Real-time video/audio → realtimekit/ or realtime-sfu/

「セキュリティを確保したい」

Need security?
├─ Web Application Firewall → waf/
├─ DDoS protection → ddos/
├─ Bot detection/management → bot-management/
├─ API protection → api-shield/
├─ CAPTCHA alternative → turnstile/
└─ Credential leak detection → waf/ (managed ruleset)

「メディア／コンテンツを扱いたい」

Need media?
├─ Image optimization/transformation → images/
├─ Video streaming/encoding → stream/
├─ Browser automation/screenshots → browser-rendering/
└─ Third-party script management → zaraz/

「Infrastructure as Code を使いたい」

Need IaC? → pulumi/ (Pulumi), terraform/ (Terraform), or api/ (REST API)

製品インデックス

コンピューティングとランタイム

製品	リファレンス
Workers	references/workers/
Pages	references/pages/
Pages Functions	references/pages-functions/
Durable Objects	references/durable-objects/
Workflows	references/workflows/
Containers	references/containers/
Workers for Platforms	references/workers-for-platforms/
Cron Triggers	references/cron-triggers/
Tail Workers	references/tail-workers/
Snippets	references/snippets/
Smart Placement	references/smart-placement/

ストレージとデータ

製品	リファレンス
KV	references/kv/
D1	references/d1/
R2	references/r2/
Queues	references/queues/
Hyperdrive	references/hyperdrive/
DO Storage	references/do-storage/
Secrets Store	references/secrets-store/
Pipelines	references/pipelines/
R2 Data Catalog	references/r2-data-catalog/
R2 SQL	references/r2-sql/

AIと機械学習

製品	リファレンス
Workers AI	references/workers-ai/
Vectorize	references/vectorize/
Agents SDK	references/agents-sdk/
AI Gateway	references/ai-gateway/
AI Search	references/ai-search/

ネットワークと接続

製品	リファレンス
Tunnel	references/tunnel/
Spectrum	references/spectrum/
TURN	references/turn/
Network Interconnect	references/network-interconnect/
Argo Smart Routing	references/argo-smart-routing/
Workers VPC	references/workers-vpc/

セキュリティ

製品	リファレンス
WAF	references/waf/
DDoS Protection	references/ddos/
Bot Management	references/bot-management/
API Shield	references/api-shield/
Turnstile	references/turnstile/

メディアとコンテンツ

製品	リファレンス
Images	references/images/
Stream	references/stream/
Browser Rendering	references/browser-rendering/
Zaraz	references/zaraz/

リアルタイム通信

製品	リファレンス
RealtimeKit	references/realtimekit/
Realtime SFU	references/realtime-sfu/

開発者ツール

製品	リファレンス
cf CLI	references/cf/
Miniflare	references/miniflare/
C3	references/c3/
Observability	references/observability/
Analytics Engine	references/analytics-engine/
Web Analytics	references/web-analytics/
Sandbox	references/sandbox/
Workerd	references/workerd/
Workers Playground	references/workers-playground/

Infrastructure as Code

製品	リファレンス
Pulumi	references/pulumi/
Terraform	references/terraform/
API	references/api/

その他のサービス

製品	リファレンス
Email Routing	references/email-routing/
Email Workers	references/email-workers/
Static Assets	references/static-assets/
Bindings	references/bindings/
Cache Reserve	references/cache-reserve/

トラブルシューティング

ネットワークアクセスの権限昇格

タイムアウト、DNS エラー、接続リセットなどのネットワークの問題でデプロイに失敗した場合は、権限を昇格してデプロイを再実行してください（sandbox_permissions=require_escalated を使用します）。サンドボックスのネットワーク設定によって外向きのリクエストがブロックされる場合、デプロイにはネットワークアクセスの権限昇格が必要です。

ユーザーへの案内例：

The deploy needs escalated network access to deploy to Cloudflare. I can rerun the command with escalated permissions—want me to proceed?