Skip to content

非公式本サイトは非公式の日本語ドキュメントであり、Cloudflare 公式サイトではありません。最新情報はdevelopers.cloudflare.comをご確認ください。

静的アセット

最終更新 Markdown で表示Agent セットアップ

Workers for Platforms では、フロントエンドアプリケーションを大規模にデプロイできます。静的アセットを Cloudflare のグローバルネットワークでホストすると、世界中で読み込みが速くなり、外部インフラは不要になります。これらの静的アセットを Cloudflare Workers の動的ロジックと組み合わせれば、顧客にフルスタックの体験を提供できます。

作れるもの

静的サイト

HTML、CSS、JavaScript、メディアファイルを Cloudflare のネットワークから直接ホストして配信します。世界中で読み込みが速くなります。ブログ、ランディングページ、ドキュメントサイトに向いています。

フルスタックアプリケーション

アセットのホスティングと Cloudflare Workers を組み合わせて、動的でインタラクティブなアプリケーションを動かします。Cloudflare KV、D1、R2 Storage でデータを保存・取得し、フロントエンドアセットとバックエンドロジックを 1 つの Worker から提供できます。

メリット

グローバルキャッシュによる高速化

Cloudflare は静的アセットを世界中のデータセンターに自動でキャッシュします。レイテンシが下がり、どこにいるユーザーでも読み込み時間が最大 2 倍速くなることがあります。

インフラ管理なしのスケール

アプリケーションは高トラフィックに合わせて自動でスケールします。インフラのプロビジョニングや管理は不要です。Cloudflare が需要に合わせてリアルタイムに調整します。

静的コンテンツと動的コンテンツの一括デプロイ

フロントエンドアセットとサーバーサイドロジックを、すべて Cloudflare Workers 内でデプロイします。別のホスティングプロバイダーは不要で、デプロイ手順もシンプルになります。

User Worker に静的アセットをデプロイする

プラットフォーム側として、エンドユーザーに代わって静的アセットをアップロードする役割を担うことがよくあります。流れは次のようになります。

  1. ユーザーがインターフェース経由でファイル（HTML、CSS、画像）をアップロードします。
  2. プラットフォームが Workers for Platforms の API を呼び出し、静的アセットを User Worker スクリプトに関連付けます。

ユーザーから静的ファイルを受け取ったら（新規サイトでも更新でも）、対応する User Worker にファイルを関連付けるために次の手順を完了します。

  1. Upload Session を作成する
  2. ファイル内容をアップロードする
  3. Worker をデプロイ / 更新する

これらの手順が終わると、User Worker の静的アセットが Cloudflare のグローバルネットワーク上で公開されます。

1. Upload Session を作成する

ファイルデータを送る前に、アップロードするファイルを Cloudflare に伝えます。このファイル一覧をマニフェストと呼びます。マニフェストの各項目には次を含めます。

  • ファイルパス（例: "/index.html" や "/assets/logo.png"）
  • ファイル内容を表すハッシュ（16 進 32 文字）
  • ファイルサイズ（バイト）

マニフェストの例（JSON）

{
	"/index.html": {
		"hash": "08f1dfda4574284ab3c21666d1ee8c7d4",
		"size": 1234
	},
	"/styles.css": {
		"hash": "36b8be012ee77df5f269b11b975611d3",
		"size": 5678
	}
}

アップロードを始めるには、Create Assets Upload Session の API エンドポイント に POST リクエストを送ります。

POST /accounts/{account_id}/workers/dispatch/namespaces/{namespace}/scripts/{script_name}/assets-upload-session

パスパラメーター:

  • namespace: Workers for Platforms の dispatch namespace 名
  • script_name: User Worker 名

リクエストボディには、各ファイルパスとそのハッシュ・サイズを列挙した JSON オブジェクトを含めます。Cloudflare はこれでアップロード対象を把握し、すでに保存済みのファイルがないかも確認できます。

リクエスト例

curl -X POST \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/$NAMESPACE_NAME/scripts/$SCRIPT_NAME/assets-upload-session" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_TOKEN" \
  --data '{
    "manifest": {
      "/index.html": {
        "hash": "08f1dfda4574284ab3c21666d1ee8c7d4",
        "size": 1234
      },
      "/styles.css": {
        "hash": "36b8be012ee77df5f269b11b975611d3",
        "size": 5678
      }
    }
  }'

ハッシュの生成

ファイル内容の SHA-256 ダイジェストを計算し、16 進 32 文字の文字列として切り詰めるか、同じ表現に揃えます。毎回同じ方法で計算してください。Cloudflare がアップロード間でファイルを確実に照合できます。

API レスポンス

すべてのファイルがすでに Cloudflare に保存されている場合、レスポンスは JWT トークンだけを返します。新規または更新されたファイルが必要な場合、レスポンスは次を返します。

  • jwt: アップロードトークン（有効期限 1 時間）。手順 2 のファイル内容アップロード API で使います。
  • buckets: まとめてアップロードするファイルハッシュのグループ配列です。最近アップロードしたファイルは、Cloudflare がすでに持っているため buckets に出ません。

2. ファイル内容をアップロードする

Upload Session API のレスポンスに buckets がある場合、新規または変更されたファイルを Cloudflare にアップロードする必要があります。

不足または変更されたファイルについて、生のファイルバイトを Base64 エンコードして Workers Assets Upload API で送信します。アップロードが完了すると、Cloudflare はこれらのファイルを保存し、User Worker に関連付けられるようにします。

API リクエストの認証

多くの Cloudflare API 呼び出しは Authorization ヘッダーにアカウント全体の API トークンを使いますが、ファイル内容のアップロードでは、assets-upload-session レスポンスの jwt フィールドで返る短命の JWT トークンを使います。

ヘッダーに Bearer トークンとして含めます。

Authorization: Bearer <upload-session-token>

このトークンの有効期限は 1 時間です。Workers Assets Upload API へのアップロードリクエストごとに指定します。

ファイルフィールド（multipart/form-data）

ファイルは、Base64 エンコードした内容を multipart/form-data で送ります。

  • フィールド名: ファイルハッシュ（例: 36b8be012ee77df5f269b11b975611d3）
  • フィールド値: ファイルの生バイトを Base64 エンコードした文字列

例: 1 つの bucket に複数ファイルをアップロードする

Upload Session のレスポンスに、2 つのファイルハッシュを含む bucket が 1 つある場合:

"buckets": [
  [
    "08f1dfda4574284ab3c21666d1ee8c7d4",
    "36b8be012ee77df5f269b11b975611d3"
  ]
]

両方のファイルを、それぞれ form-data フィールドとして 1 回のリクエストでアップロードできます。

curl -X POST \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/assets/upload?base64=true" \
  -H "Authorization: Bearer <upload-session-token>" \
  -F "08f1dfda4574284ab3c21666d1ee8c7d4=<BASE64_OF_INDEX_HTML>" \
  -F "36b8be012ee77df5f269b11b975611d3=<BASE64_OF_STYLES_CSS>"
  • <upload-session-token> は手順 1 の assets-upload-session レスポンスのトークンです
  • <BASE64_OF_INDEX_HTML> は index.html の Base64 エンコード済み内容です
  • <BASE64_OF_STYLES_CSS> は styles.css の Base64 エンコード済み内容です

bucket が複数ある場合（例: [["hashA"], ["hashB"], ["hashC"]]）、bucket グループごとにこの処理を繰り返し、1 グループにつき 1 リクエスト送ります。

マニフェスト内のすべてのファイルのアップロードが完了すると、ステータスコード 201 が返り、jwt フィールドが含まれます。この JWT は「完了」トークンで、このアセット一式を使った Worker のデプロイ作成に使えます。完了トークンの有効期限は 1 時間です。

{
	"success": true,
	"errors": [],
	"messages": [],
	"result": {
		"jwt": "<completion-token>"
	}
}

<completion-token> は、マニフェストで指定したファイル内容を Cloudflare が受信して保存したことを示します。手順 3 でこの <completion-token> を使い、これらのファイルを Worker へ関連付けます。

3. 静的アセット付きで User Worker をデプロイする

Cloudflare が必要なファイルをすべて持っているので（前のアップロード手順）、Upload User Worker API に PUT リクエストを送り、User Worker に関連付けます。この最終手順で、ファイル内容アップロード後に受け取った完了トークンを使い、静的アセットを User Worker に紐づけます。

assets.config フィールドで任意の設定も指定でき、ファイルの配信方法をカスタマイズできます（HTML パスの末尾スラッシュの扱いなど）。

API リクエストの例

curl -X PUT \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/$NAMESPACE_NAME/scripts/$SCRIPT_NAME" \
  -H "Content-Type: multipart/form-data" \
  -H "Authorization: Bearer $API_TOKEN" \
  -F 'metadata={
    "main_module": "index.js",
    "assets": {
      "jwt": "<completion-token>",
      "config": {
        "html_handling": "auto-trailing-slash"
      }
    },
    "compatibility_date": "2025-01-24"
  };type=application/json' \
  -F 'index.js=@/path/to/index.js;type=application/javascript'
  • "jwt": "<completion-token>" が、新しくアップロードしたファイルを Worker に紐づけます
  • "html_handling"（または "config" 配下の他のフィールド）は任意です。静的ファイルの配信方法をカスタマイズできます
  • ユーザーの Worker コードが変わっていない場合は、コードファイルを省略するか、同じ index.js を再アップロードできます

この PUT リクエストが成功すると、ファイルは User Worker から配信されます。その Worker にルーティングされたリクエストは、新しいまたは更新された静的アセットを返します。

Wrangler で静的アセットをデプロイする

CLI で進めたい場合で、プラットフォーム構成が直接の公開を許しているときは、Wrangler で Worker コードと静的アセットの両方をデプロイできます。Wrangler は指定ディレクトリの静的アセットを Worker スクリプトと一緒にバンドルしてアップロードするので、一箇所で管理できます。

Wrangler の設定ファイル を作成または更新し、静的ファイルの場所を指定します。

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-static-site",
	"main": "./src/index.js",
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"assets": {
		"directory": "./public",
		"binding": "ASSETS",
	},
}
"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-static-site"
main = "./src/index.js"
# Set this to today's date
compatibility_date = "2026-09-20"

[assets]
directory = "./public"
binding = "ASSETS"
  • directory: 静的ファイルがあるローカルフォルダー（例: ./public）。
  • binding: Worker コードからこれらのアセットを参照するときの binding 名。

1. ファイルを整理する

静的ファイル（HTML、CSS、画像など）を指定ディレクトリ（この例では ./public）に置きます。Worker を公開するとき、Wrangler がこれらのファイルを検出してバンドルします。

Worker スクリプトからこれらのファイルを参照して動的に配信するには、次のように ASSETS binding を使います。

export default {
	async fetch(request, env, ctx) {
		return env.ASSETS.fetch(request);
	},
};

2. 静的アセット付きで User Worker をデプロイする

Wrangler を実行し、Worker コードと静的アセットの両方を公開します。

npx wrangler deploy --name <USER_WORKER_NAME> --dispatch-namespace <NAMESPACE_NAME>

Wrangler は静的ファイルを自動で検出し、バンドルして、Worker コードと一緒に Cloudflare へアップロードします。

役に立ちましたか？