スタンドアロン Workers

Pages とは独立した Workers のデプロイ

使用する場面

スタンドアロン Workers は以下に最適：

• 検索ワーカー -- 独自のデータと依存関係を持つ検索 API

• AI チャットワーカー -- API キーバインディングを持つ LLM エンドポイント

• Webhook ハンドラー -- 外部サービスからのコールバック受信

• プロキシワーカー -- リクエストのルーティングや変換

プロジェクト構造

典型的なスタンドアロン Worker プロジェクト：

packages/my-worker/
├── src/
│   └── index.ts
├── wrangler.toml
├── package.json
└── tsconfig.json

Worker エントリーポイント

// src/index.ts
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname === "/api/search") {
      return handleSearch(request, env);
    }

    return new Response("Not Found", { status: 404 });
  },
};

ExecutionContext とバックグラウンド処理

fetch の第3引数は ExecutionContext で、レスポンス送信後に非同期処理を実行する waitUntil() を提供する：

export default {
  async fetch(
    request: Request,
    env: Env,
    ctx: ExecutionContext,
  ): Promise<Response> {
    // Return response immediately
    const response = buildResponse(request, env);

    // Run non-critical work in the background
    ctx.waitUntil(logAnalytics(request, env));
    ctx.waitUntil(updateCache(request, env));

    return response;
  },
};

これが重要な場面：

• Webhook ハンドラー -- Slack、GitHub 等は 3 秒以内のレスポンスを要求する。レスポンス後に Webhook ペイロードを処理する。

• ロギングとアナリティクス -- 重要でない書き込みでユーザーのレスポンスをブロックしない。

• キャッシュウォーミング -- レスポンス後にキャッシュを更新する。

:::warning[waitUntil は CPU 時間を延長しない] ctx.waitUntil() はレスポンス送信後も Worker を生存させるが、CPU 時間制限は増えない。長時間の処理は終了される可能性がある。 :::

## デプロイ

`wrangler deploy`（`wrangler pages deploy` ではなく）でデプロイ：

```bash

npx wrangler@4 deploy

CI ではワーカーのディレクトリからデプロイ：

- name: Deploy Worker
  working-directory: packages/my-worker
  run: pnpm run deploy
  env:
    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

パストリガーデプロイ

モノレポで複数ワーカーがある場合、ワーカーのファイルが変更された時のみデプロイをトリガーする：

on:
  push:
    branches:
      - main
    paths:
      - 'packages/my-worker/**'
  workflow_dispatch: