Workers 基礎 — 初めてのサーバーレス関数

Workers の実行モデル — V8 isolate とコールドスタート

Cloudflare Workers のランタイムは、Chromium や Node.js と同じ V8 エンジンの上に構築されています。ただしコードが動く場所が根本的に異なります。あなたの Worker は 1 台のサーバーではなく、数百拠点・数千台のマシンからなる Cloudflare のグローバルネットワーク全体に配布され、リクエストを受け取ったデータセンターがそのまま実行します。「どのリージョンにデプロイするか」を選ぶ設定は存在しません。

従来のサーバーレス（コンテナ型）との最大の違いが isolate（アイソレート） です。isolate は V8 が管理する軽量な実行コンテキストで、コードごとにメモリが完全に分離されたサンドボックスとして働きます。関数ごとに仮想マシンやコンテナを起動する代わりに、すでに起動済みのランタイム内へ isolate を作るため、仮想マシンモデルで発生していたコールドスタートが排除されます。ドキュメントによれば、isolate の起動はコンテナ上の Node プロセスより約 100 倍高速で、起動時のメモリ消費は 1 桁少なくなります。

リクエストが処理される流れは次のとおりです。

1. ユーザーが *.workers.dev または Cloudflare 管理下のドメインへ HTTP リクエストを送る
2. Cloudflare のいずれかのデータセンターがリクエストを受け取る
3. そのマシン上のランタイムが isolate 内であなたの Worker の fetch() ハンドラを呼び出す
4. ハンドラが返した Response がユーザーへ返る

注意すべき性質もあります。isolate はマシンのリソース逼迫などで破棄（evict）されることがあり、また同じ 2 つのリクエストが同じインスタンスに届く保証もありません。したがってグローバル変数に可変状態を保存しないことが公式に推奨されています。またセキュリティ上の理由で eval() や new Function は使えません。

fetch ハンドラと Request / Response / URL

Worker のコードは ES Modules 形式で書きます。オブジェクトを export default し、処理したいイベントに対応するハンドラをプロパティとして持たせます。HTTP リクエストを処理するのが fetch() ハンドラです。

export default {
	async fetch(request, env, ctx): Promise<Response> {
		return new Response("Hello World!");
	},
} satisfies ExportedHandler<Env>;

fetch ハンドラには常に 3 つの引数が渡されます。

Request と Response は Fetch API 標準のインターフェースです。押さえておくべき Workers 固有のポイントは次の 3 点です。

• 受信 Request は不変（immutable）。プロパティを変更したいときは new Request(url, request) で新しいオブジェクトを作ります。
• request.cf オブジェクトに Cloudflare ネットワークが付与した情報が入ります。データセンターの IATA コード colo、国コード country、都市 city、タイムゾーン timezone などが読み取れます（ダッシュボードのプレビューや Playground では利用不可）。
• ボディの読み取りは request.json() / request.text() / request.formData() / request.arrayBuffer() の Promise ベース API で行います。

ルーティングの基本は、標準の URL API で request.url を分解することです。new URL(request.url) の pathname や searchParams で分岐します。パターンマッチには URLPattern API も利用できます。なお、Worker 内から外部へ HTTP リクエストを送る fetch() API（サブリクエスト）はハンドラの内側（Request コンテキスト）でしか呼べません。グローバルスコープで呼ぶと例外になります。

デプロイした Worker を公開する経路（Routes and domains）は 3 種類あります。本章では最も手軽な workers.dev を使います。

• workers.dev — Worker 作成時に自動で割り当てられる <Worker 名>.<アカウントのサブドメイン>.workers.dev という URL。個人・ホビー用途向けで、すぐ試せる
• Custom Domains — 自分のドメインを Worker をオリジンとして接続する。本番運用の推奨
• Routes — Cloudflare ゾーン内の URL パターンに Worker を割り当てる。既存オリジンサーバーの前段に置く用途

TypeScript での開発

TypeScript は Workers の第一級言語です。全 API の型定義は、オープンソースのランタイム workerd から直接生成されています。正しい型はあなたの Worker の compatibility date・compatibility flags・バインディング構成に依存するため、公式の推奨は wrangler types コマンドでプロジェクトの設定に合わせて型を動的生成することです。

npx wrangler types

既定で worker-configuration.d.ts が生成され、バインディングに基づく Env 型とランタイム型の両方が含まれます。生成したファイルは tsconfig.json の compilerOptions.types に追加します。

{
	"compilerOptions": {
		"types": ["./worker-configuration.d.ts"]
	}
}

設定ファイルを変更したら wrangler types を再実行します。CI では npx wrangler types --check でコミット済みの型が最新かを検証できます。ハンドラ本体には satisfies ExportedHandler<Env> を付けると、引数と戻り値の型が推論されつつ検査されます。

ハンズオン

以降の 3 本はいずれも「編集 → wrangler dev → wrangler deploy → wrangler tail」という同じ一周をなぞります。どの操作が自分のマシンで完結し、どこで Cloudflare 側へ出ていくのかを先に押さえておきます。

つまずきポイント

理解度チェック

まとめと次章へ

• Workers は V8 isolate で動き、グローバルネットワーク全体にデプロイされる。リージョン選択は存在せず、コールドスタートもほぼ無い
• コードは ES Modules 形式で fetch(request, env, ctx) ハンドラを書き、Request を受けて Response を返す。受信 Request は不変で、request.cf に地理情報などが入る
• ルーティングは new URL(request.url) の pathname 分岐が基本。外部への fetch() サブリクエストや HTMLRewriter がストリーミングで使える
• 開発サイクルは wrangler dev（localhost:8787）→ wrangler deploy → workers.dev URL 確認 → wrangler tail でログ観測
• TypeScript では wrangler types で設定に合った型を生成し、satisfies ExportedHandler<Env> で型検査する

次章では、この章で素通りした第 2 引数 env の中身 — wrangler.jsonc の設定、環境変数とシークレット、KV や R2 につながるバインディング、Cron Triggers による定期実行 — を扱い、Worker を「本物のアプリケーション」に近づけます。

参考リンク:

• Get started - CLI
• How Workers works
• Fetch Handler
• Request / Response / Fetch
• HTMLRewriter
• TypeScript
• Real-time logs
• workers.dev