静的アセットと Pages — サイトホスティング

Workers の静的アセット機能

前章までの Worker は「コードだけ」をデプロイしていました。Workers の static assets 機能を使うと、HTML・CSS・画像などの静的ファイルを Worker の一部としてアップロードでき、キャッシュと配信は Cloudflare に任せられます。Worker コードと静的アセットは 1 回の wrangler deploy で単一のユニットとしてデプロイされます。

中心になるのは Wrangler 設定ファイルの assets.directory です。ここで指定したフォルダ（フレームワークなら ./public/ や ./dist/、./build/ が定番）の中身が、デプロイ時に Wrangler によって自動アップロードされます。main を持たない「アセットだけの Worker」も作れます。

// wrangler.jsonc — アセットのみの最小構成
{
  "name": "my-static-site",
  "compatibility_date": "2026-08-11",
  "assets": {
    "directory": "./public"
  }
}

配信面の特徴は次の 3 点です。

• アセットへのリクエストは無料・無制限 — 課金対象になるのは Worker スクリプトが呼び出されたときだけで、アセットの保存自体にも追加コストはありません（2026-08 時点）。
• 自動キャッシュ — 一度リクエストされたアセットは最寄りの Cloudflare ロケーションにキャッシュされ、tiered cache により他のデータセンターからも近くのキャッシュ経由で取得されます。
• 既定のレスポンスヘッダー — Content-Type はファイル拡張子から自動判定され、Cache-Control: public, max-age=0, must-revalidate と ETag が付きます。ブラウザは毎回鮮度を確認しますが、変更が無ければ再ダウンロードは発生しないため、高速さと「古いコンテンツを配らない」ことを両立します。

主な制限は次のとおりです（2026-08 時点）。1 つの Worker に設定できるアセットのコレクションは 1 つだけで、Paid プランのファイル数上限を使うには Wrangler v4.34.0 以降が必要です。

ルーティング挙動を制御する

静的アセットと Worker スクリプトが同居するとき、リクエストは既定で次の順に処理されます。

1. リクエストパスがアセットディレクトリ内のファイルに一致すれば、Worker スクリプトを起動せずにそのファイルを配信する（課金なし）
2. 一致しなければ Worker スクリプトを呼び出す
3. Worker スクリプトが無ければ 404 Not Found（本文なし）を返す

Worker スクリプトからは env.ASSETS.fetch(request)（assets binding）でアセット配信へ処理を委譲できます。URL のホスト名部分は無視され、パス名だけがアセットの照合に使われます。この「アセット優先」の既定挙動は、assets 配下のオプションで変更できます。

not_found_handling — SPA フォールバックとカスタム 404

SPA モードでは、/dashboard のようにアセットへ一致しない URL への直アクセスにも /index.html が 200 で返り、クライアントサイドルーターが処理を引き継げます。Pages はプロジェクト構成からこの挙動を自動判定していましたが、Workers では誤設定防止のため明示的に設定します。

html_handling — 末尾スラッシュの正規化

既定の auto-trailing-slash は、単独ファイル foo.html を /foo で、フォルダ配下の folder/index.html を /folder/ で配信し、/foo.html や /folder のような非正規 URL は 307 で正規 URL にリダイレクトします。force-trailing-slash（常にスラッシュ付き）・drop-trailing-slash（常にスラッシュなし）・none（正規化を無効化）も選べます。SEO 上の重複コンテンツ問題を防ぐ仕組みです。

run_worker_first — Worker を先に実行する

run_worker_first: true を設定すると、アセットに一致するリクエストでも常に Worker スクリプトが先に実行されます。認証チェック・リクエストログ・HTMLRewriter によるアセット加工といった「ミドルウェア」を実装したいときに使います。配列でパスパターンを渡すと対象ルートを絞り込めます（glob の * と ! による除外パターンに対応。Wrangler v4.20.0 以降）。除外パターンが優先され、記述順は評価に影響しません。

// wrangler.jsonc — SPA + API の典型構成
{
  "name": "my-spa-worker",
  "main": "./src/index.ts",
  "compatibility_date": "2026-08-11",
  "assets": {
    "directory": "./dist",
    "not_found_handling": "single-page-application",
    "binding": "ASSETS",
    "run_worker_first": ["/api/*", "!/api/docs/*"]
  }
}

navigation リクエストの最適化

Worker スクリプトがあり、not_found_handling を設定していて、compatibility_date が 2025-04-01 以降（または assets_navigation_prefers_asset_serving フラグ有効）の場合、ブラウザのページ遷移で送られる navigation リクエスト（Sec-Fetch-Mode: navigate ヘッダー付き）は Worker スクリプトを呼ばずにアセットを配信します。SPA のページ遷移のたびに課金対象の Worker 起動が発生するのを防ぐ最適化です。不要なら assets_navigation_has_no_effect フラグで無効化できます。

_headers と _redirects で配信を宣言的に制御する

静的アセットディレクトリの直下に _headers / _redirects という拡張子なしのプレーンテキストファイルを置くと、Workers がそれらを解釈し、静的アセットの応答にカスタムヘッダーとリダイレクトを適用します。ファイル自体は静的アセットとして配信されません。フレームワーク利用時は、ビルドで出力ディレクトリへコピーされる public/ や static/ に置くのが定石です。

_headers

「URL パターン 1 行 + インデントしたヘッダー行」のブロックで記述します。複数ルールに一致したリクエストはすべてのルールのヘッダーを継承し、既定ヘッダーの除去は ! （感嘆符 + 空白）をヘッダー名に前置します。

# ハッシュ付きファイル名のアセットはブラウザに長期キャッシュさせる
/assets/*
  Cache-Control: public, max-age=31556952, immutable

# 全体に CSP を掛けつつ、JPEG 画像からは除去する
/*
  Content-Security-Policy: default-src 'self';

/*.jpg
  ! Content-Security-Policy

ルールは最大 100 個、1 行あたり 2,000 文字までです（2026-08 時点）。同じヘッダーが複数回適用された場合、値はカンマで結合されます。

_redirects

1 行につき [source] [destination] [code?] を記述します。ステータスコードを省略すると 302 になります。*（splat、転送先では :splat で参照）と :placeholder が使え、ステータスコードに 200 を指定すると同一サイト内のプロキシ（rewrite）として動作します（外部ドメインへのプロキシは不可）。

# 恒久移転は 301 を明示（省略時は 302）
/old-top / 301
/blog/* https://blog.example.com/:splat
/products/:code /items/:code 301

静的リダイレクト 2,000 件 + 動的リダイレクト 100 件の計 2,100 件まで、1 ルール 1,000 文字までです（2026-08 時点）。同一 source に複数ルールがある場合は上にある行が優先され、リダイレクトはヘッダー適用より先に評価されます。またリダイレクトはアセット照合よりも手前で評価されるため、一致するアセットが無いパスでも適用されます。なお、この 2 ファイルのルールが働くのは静的アセット配信の経路だけで、Worker コードが生成したレスポンスには効きません（詳細はつまずきポイント参照）。

フレームワークのデプロイと Pages との関係

React や Astro などのフレームワークで作るサイトも、ビルド出力は「静的アセット（+ SSR 用の Worker スクリプト）」なので同じ仕組みでデプロイできます。C3 の --framework フラグを使うと、フレームワーク込みのプロジェクトを一発で scaffold できます。たとえば React なら npm create cloudflare@latest -- my-react-app --framework=react です。生成されるテンプレートでは worker/index.ts が API バックエンドになり、assets.not_found_handling は single-page-application に設定済み、Cloudflare Vite プラグインにより本番同等の Workers ランタイムでローカル開発できます。Astro・React Router（旧 Remix）・Next.js・Nuxt・SvelteKit など主要フレームワークには Workers 向けガイドとアダプタが用意されています。

Cloudflare Pages との使い分け

Cloudflare Pages は、Git 連携による push 時の自動ビルド・デプロイとプレビュー環境を備えたホスティングサービスで、サーバー処理は Pages Functions が担ってきました。現在は Workers の static assets が Pages の主要機能（無料の静的配信・_headers / _redirects・SPA フォールバック・ASSETS binding・Git 連携ビルド）をカバーしたうえで、Workers でしか使えない機能が多くあります。

公式ドキュメントには Pages から Workers への移行ガイドと機能互換マトリクスが用意されており、Pages docs 側からも「Migrate to Workers」として案内されています。新規開発では Workers を選ぶのが現在の流れです。移行の要点は「pages_build_output_dir を assets.directory へ」「Pages Functions を Worker スクリプトへ」「wrangler pages dev / deploy を wrangler dev / deploy へ」の置き換えです。advanced mode の _worker.js を使っていた場合は、静的アセットとして公開されないよう .assetsignore（.gitignore と同形式）で除外するか、アセットディレクトリの外へ移動します。なお、Pages より前の世代の仕組みである Workers Sites は新規プロジェクトで使わないでください。

ここからのハンズオンでは、静的サイトのデプロイから始めて、「静的サイト + API を 1 つの Worker で配信する」構成までを実際に作ります。3 本とも Free プランで完走できます。

つまずきポイント

理解度チェック

まとめと次章へ

• assets.directory を指定するだけで静的サイトを Worker として配信できる。アセットへのリクエストは無料で、保存コストもかからない
• 既定のルーティングは「アセット優先 → Worker → 404」。not_found_handling で SPA / SSG のフォールバックを明示し、run_worker_first で認証などの前段処理を差し込める
• _headers / _redirects で静的アセット応答のヘッダーとリダイレクトを宣言的に管理できる（Worker が生成するレスポンスには効かない）
• 主要フレームワークは C3 と Vite プラグインで Workers にデプロイできる。Pages には公式の移行ガイドがあり、新規開発では Workers が推奨される流れ

サイトの「ガワ」を配信できるようになったので、次章からはデータを扱います。第 5 章では、エッジで読み取り最速のグローバル key-value ストア Workers KV を学び、この章で作った構成に動的なデータを持たせていきます。

参考リンク:

• Static Assets（概要）
• Routing（SPA / SSG / Worker script）
• Headers / Redirects
• Billing and Limitations
• Migrate from Pages to Workers
• Framework guides