Cloudflare Workersの実装設計：認証・キャッシュ・運用とLambdaとの使い分け

従来のサーバーレス（AWS Lambda等）と、エッジサーバーレス（Cloudflare Workers）は、アーキテクチャが根本的に異なります。

静的配信に近い軽量APIやリクエスト制御はWorkersが候補になります。一方、長時間の処理、豊富なランタイム、AWS内のデータへ近接させたい処理はLambdaが扱いやすい場合があります。料金表だけでなく、処理時間、依存ライブラリ、データの場所で判断します。

画面は静的配信に任せ、動的処理だけをWorkersへ寄せる構成が基本形です。PagesとWorkersのどちらを使うかという選択自体は、Cloudflare PagesとWorkersの違い：構成を選ぶための判断表で扱っています。本記事はWorkersで動的処理を実装する前提で、その設計と運用を扱います。

運用コストを含めた構成の判断は中小企業サイトの運用コストを抑える方法で整理しています。また、フロントエンドとAPIをリポジトリレベルで分離する場合は疎結合アーキテクチャの設計が前提になります。

1. User → Cloudflare Pages (CDN Edge)

まずは最寄りのエッジから、キャッシュされたHTML/JSを受信します。オリジンへの往復がないため、遅延は距離に依存しにくくなります。

2. Frontend → Cloudflare Workers (BFF)

ブラウザから動的なデータ（在庫、マイページ情報）をWorkersへリクエストします。

3. Workers → Upstream API / DB

WorkersがAPIキーを付与して外部API（Headless CMS, DBなど）を叩き、結果を整形して返します。

この構成のメリットは、「オリジンサーバー（重い処理をするサーバー）への負荷を極小化できる」点です。静的ファイルへのアクセスはオリジンに行かず、動的リクエストもWorkersがキャッシュや軽量処理を肩代わりします。

フロントエンド開発で最も危険なのが、APIキーやシークレットトークンの漏洩です。

「Secretsをフロントに出さない」ことが原則です。

• NG (危険)：
  Reactコード内に const API_KEY = "sk-..." と書く。
  → ブラウザの「ソースを表示」で誰でも見れてしまいます。
• OK (安全)：
  Cloudflare Workersの環境変数にAPIキーを保存し、フロントからはキー無しでWorkersを叩く。
  Workers内で env.API_KEY を付与して外部APIへプロキシする。

Cloudflareではダッシュボードから暗号化された環境変数を設定でき、コード内からは参照できますが、デプロイ後の値の閲覧はできないよう保護されています。

Cloudflare Workersの設定は設定ファイル一つで管理します（現在は wrangler.jsonc が推奨形式ですが、wrangler.toml も引き続き利用できます）。最小限の構成例は以下の通りです。

name = "my-worker-app"
main = "src/index.ts"
compatibility_date = "2026-01-01"

# 環境変数のバインディング
# シークレットはここには書かず、CLIで `npx wrangler secret put` して登録します
[vars]
API_HOST = "https://api.example.com"

# KV (Key-Valueストア) の設定
[[kv_namespaces]]
binding = "MY_KV"
id = "xxxxxxxxxxxxxxxxxxxxx"

# スマートプレースメント (最適配置) の有効化
# ユーザーに近いエッジではなく、DBに近いエッジで動かす場合にONにする
# [placement]
# mode = "smart"

このように、「インフラの設定」をコードとしてリポジトリ管理（IaC）できる運用性の高さも魅力の一つです。

エッジ活用の中心はキャッシュコントロールにあります。Workersを使えば、「特定のユーザーだけキャッシュしない」「1分だけキャッシュする」といった細かい制御が可能です。

Cache API活用例：

• ニュース一覧 (Public)： max-age=600 (10分キャッシュ)。誰が見ても同じなので、エッジで返し続ける。
• ユーザー情報 (Private)： no-store (キャッシュなし)。常にDBから最新を取得。
• 検索結果 (Query)： s-maxage=3600 (1時間)。同じキーワードでの検索負荷を下げる。

キャッシュが成立する範囲を先に決めると、オリジンやデータベースへの不要なアクセスを減らせます。個人情報を含むレスポンスや権限ごとに内容が変わる画面は、共有キャッシュへ混ぜない設計が必要です。

サーバーレスは「サーバー管理が不要」ですが、「運用が不要」なわけではありません。むしろ、ログが見えにくくなるため、意図的な可視化が必要です。

• ログの保存：
  Workers Logsで実行ログを保存・検索できます（保存期間やサンプリング率はプランにより異なります）。長期保管や外部SIEMへの集約が必要な場合は、LogpushやDatadog連携を設定します。
• リアルタイム監視：
  「Wrangler tail」コマンドで、今起きているエラーをターミナルで流し見ることができます。開発中のデバッグに必須です。
• バージョン管理：
  PagesもWorkersも、過去のデプロイメントに「1クリックでロールバック（切り戻し）」する機能があります。障害時は修正より先に、まず前バージョンに戻す判断が重要です。

導入時によくハマるポイントを挙げます。

• CORS (Cross-Origin Resource Sharing) エラー：
  Pages (Domain A) から Workers (Domain B) を叩く時、ブラウザがブロックします。Workers側で適切な Access-Control-Allow-Origin ヘッダーを返す実装が必要です。
• Node.js APIの非互換：
  Workersはブラウザ互換のV8エンジンで動いており、Node.jsではありません。fs モジュールなどは使えないため、型安全にWorkersを実装するTypeScript開発環境での実装時にライブラリ選びに注意が必要です。

Cloudflare環境での構築プロジェクトを始める前の確認リストです。