Gadget 35：Workers 基礎

Cloudflare Workers のランタイム・バインディング・デプロイの基本を深掘り

Workers 基礎

Cloudflare OS を含む「Workers アプリ」を理解するための土台です。

目的

  • Workers の実行モデル（エッジ・Isolate・イベント駆動）を理解する
  • バインディング（KV/D1/R2/AI など）の概念を掴む
  • 最小の Worker をデプロイできる

前提条件

  • 公式ドキュメント: https://developers.cloudflare.com/workers/
  • Cloudflare アカウント（無料枠で可）

手順

1. 最小の Worker を作る

npm create cloudflare@latest hello-cf -- --template hello-world
cd hello-cf
npx wrangler dev        # ローカル実行
npx wrangler deploy     # 公開

2. 実行モデルを理解する

  • エッジ実行: 東京・大阪など最寄りのエッジで動作
  • Isolate: V8 の分離領域。コールドスタートがある
  • イベント駆動: リクエストごとに handler が走る（常駐サーバーではない）
export default {
  async fetch(request, env, ctx) {
    return new Response("Hello from Workers!", {
      headers: { "content-type": "text/plain" },
    });
  },
};

3. バインディングを知る

バインディング 用途 主要 Doc
env.KV_NAMESPACE 高速読み書きキャッシュ 40
env.DB SQLite データベース 38
env.R2 オブジェクトストレージ 39
env.AI AI 推論（Workers AI） 37
env.VECTORIZE ベクトル検索 43
env.CF_OBJECT 永続状態（DO） 36

wrangler.toml で宣言:

name = "hello-cf"
main = "src/index.js"
compatibility_date = "2024-11-01"

[[kv_namespaces]]
binding = "KV_NAMESPACE"
id = "<namespace-id>"

4. ローカル開発とデプロイの流れ

npx wrangler dev      # http://localhost:8787（CFOS と同じポートの偶然の一致に注意）
npx wrangler deploy   # 本番公開
npx wrangler tail     # 本番ログを見る

よくある失敗

症状 原因 対処
コールドスタートで遅い 初回実行のオーバーヘッド コードを軽く・事前に warm
バインディングが null 未宣言 or 環境不一致 wrangler.toml とローカル設定を確認
デプロイに失敗 アカウント/課金設定 wrangler login と whoami を確認
ローカル 8787 と競合 CFOS の run-local どちらかをポート変更

確認

次に読む