設定とバインディング

アセット付き Worker を設定するには、Wrangler ファイルで directory を指定し、任意でアセットバインディングも指定します。アセットバインディングを使うと、Worker スクリプト内からアセットを動的に取得できます（例: env.ASSETS.fetch()）。Service Binding で fetch() を呼ぶのと似ています。

各 Worker に設定できる静的アセットのコレクションは 1 つだけです。

`directory`

配信する静的アセットのフォルダーです。多くのフレームワークでは ./public/、./dist/、または ./build/ です。

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"assets": {
		"directory": "./public/",
	},
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker"
# Set this to today's date
compatibility_date = "2026-09-20"

[assets]
directory = "./public/"

アセットを無視する

アセットディレクトリ内に、アップロードしたくないファイルがあることがあります。

その場合は、アセットディレクトリのルートに .assetsignore ファイルを作ります。形式は .gitignore と同じです。

このファイルの行に一致するアセットファイルは、Wrangler はアップロードしません。

例

アセットディレクトリが dist の Pages プロジェクトから移行する場合です。サーバー側の Worker コードも、Pages の設定ファイルも、公開クライアント側アセットとしてはアップロードしたくありません。次の .assetsignore ファイルを追加します。

_worker.js
_redirects
_headers

これで、Worker のデプロイ時にこれらのファイルはクライアント側アセットとしてアップロードされません。

`run_worker_first`

本来アセットに一致するリクエストでも、Worker スクリプトを呼び出すかどうかを制御します。run_worker_first = false（デフォルト）は、リクエストに一致する静的アセットを配信します。run_worker_first = true は、無条件に Worker スクリプトを呼び出します。

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"main": "src/index.ts",
	// The following configuration unconditionally invokes the Worker script at
	// `src/index.ts`, which can programmatically fetch assets via the ASSETS binding
	"assets": {
		"directory": "./public/",
		"binding": "ASSETS",
		"run_worker_first": true,
	},
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker"
# Set this to today's date
compatibility_date = "2026-09-20"
main = "src/index.ts"

[assets]
directory = "./public/"
binding = "ASSETS"
run_worker_first = true

run_worker_first をルートパターンの配列にして、特定ルートだけで Worker スクリプトを先に動かすこともできます。

配列は、深い一致用の * グロブと、! 接頭辞の否定パターンをサポートします。

否定パターンは、否定でないパターンより優先されます。否定でないパターンに一致し、どの否定パターンにも一致しないときに、Worker が先に動きます。

パターンの並び順に意味はありません。

run_worker_first は、not_found_handling = "single-page-application" 設定と組み合わせることが多いです。

{
	"name": "my-spa-worker",
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"main": "./src/index.ts",
	"assets": {
		"directory": "./dist/",
		"not_found_handling": "single-page-application",
		"binding": "ASSETS",
		"run_worker_first": ["/api/*", "!/api/docs/*"]
	}
}

name = "my-spa-worker"
# Set this to today's date
compatibility_date = "2026-09-20"
main = "./src/index.ts"

[assets]
directory = "./dist/"
not_found_handling = "single-page-application"
binding = "ASSETS"
run_worker_first = [ "/api/*", "!/api/docs/*" ]

この設定では、/api/* ルートへのリクエストは Worker スクリプトを先に呼び出します。/api/docs/* は除き、こちらはデフォルトのアセット優先ルーティングに従います。

run_worker_first のよくある用途は、認証チェック、A/B テスト、SPA シェルへのブートストラップデータの注入です。

`binding`

任意のバインディングを設定すると、Worker スクリプト内からアセットのコレクションへアクセスできます。

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-worker",
	"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-worker"
main = "./src/index.js"
# Set this to today's date
compatibility_date = "2026-09-20"

[assets]
directory = "./public/"
binding = "ASSETS"

上の例では、アセットは env.ASSETS 経由で使えます。

Runtime API リファレンス

`fetch()`

パラメーター

request: Request | URL | string Request オブジェクト、URL オブジェクト、または URL 文字列を渡します。このメソッドで行ったリクエストには、html_handling と not_found_handling の設定が適用されます。

レスポンス

Promise<Response> 指定したリクエストに対する静的アセットのレスポンスを返します。

例

動的コードから、アセットバインディングを使ってプロジェクトの静的アセットへ新しいリクエストを送ったり、受信リクエストを転送したりできます。例: env.ASSETS.fetch(request)、env.ASSETS.fetch(new URL('https://assets.local/my-file'))、env.ASSETS.fetch('https://assets.local/my-file')。URL のホスト名（例: assets.local）に意味はありません。有効なホスト名ならどれでも動きます。アセットの照合に使うのは URL のパス名だけです。

次の例は、/api/ 向けのすべてのリクエストにレスポンスを返す Worker スクリプトです。それ以外は、受信リクエストをアセットバインディングへ渡します。この場合、Worker スクリプトはリクエストされたルートがどの静的アセットにも一致しないときだけ呼び出されるため、常に not_found_handling の挙動が評価されます。

export default {
	async fetch(request, env) {
		const url = new URL(request.url);
		if (url.pathname.startsWith("/api/")) {
			// TODO: Add your custom /api/* logic here.
			return new Response("Ok");
		}
		// Passes the incoming request through to the assets binding.
		// No asset matched this request, so this will evaluate `not_found_handling` behavior.
		return env.ASSETS.fetch(request);
	},
};

interface Env {
	ASSETS: Fetcher;
}

export default {
	async fetch(request, env): Promise<Response> {
		const url = new URL(request.url);
		if (url.pathname.startsWith("/api/")) {
			// TODO: Add your custom /api/* logic here.
			return new Response("Ok");
		}
		// Passes the incoming request through to the assets binding.
		// No asset matched this request, so this will evaluate `not_found_handling` behavior.
		return env.ASSETS.fetch(request);
	},
} satisfies ExportedHandler<Env>;

ルーティング設定

静的アセットの各種ルーティング設定は Routing を参照してください。

Smart Placement

Smart Placement を使うと、Worker のコードをバックエンドインフラの近くに置けます。Smart Placement が効くのは、Worker コードを指す main を指定した場合だけです。

Worker コードを先に動かす Smart Placement

run_worker_first=true でアセットより先に Worker コードを動かす場合、すべてのリクエストは先に Smart Placement 済みの Worker へ届きます。その結果、アセットリクエストのレイテンシが増えることがあります。

run_worker_first=true で Smart Placement を使うのは、ほかのバックエンドサービスと連携する、アセット配信前にリクエストを認証する、配信前にアセットを加工したい場合です。

一部のアセットはできるだけ速くユーザーへ届け、ほかは Smart Placement 済み Worker の後ろで届けたい場合は、アプリを複数の Workers に分け、サービスバインディングでつなぐことを検討してください。

アセットを先に動かす Smart Placement

run_worker_first=false で Smart Placement を有効にする（または指定しない）と、アセットはできるだけユーザーの近くから配信され、Worker ロジックは効率よく動く場所（データベースの近くなど）へ移ります。

高速なアセット配信を優先するときは、run_worker_first=false（または未指定）で Smart Placement を使います。

デフォルトのルーティング挙動には影響しません。