← Cloudflare Workers / workers / static-assets

Konfigurace a Bindings

Konfigurace Workeru s aktivy vyžaduje zadání adresář a volitelně vazba assets, v souboru Wrangler vašeho Workeru. vazba assets umožňuje dynamicky načítat assety přímo ve skriptu vašeho Workeru (např. env.ASSETS.fetch()), podobně jako byste mohli vytvořit fetch() volání s Service binding.

V každém Workeru lze nakonfigurovat pouze jednu kolekci statických assetů.

Složka statických souborů, které se mají obsluhovat. U mnoha frameworků je to ./public/, ./dist/, nebo ./build/ složka.

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

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

[assets]
directory = "./public/"

V adresáři assets se někdy vyskytují soubory, které by se neměly nahrávat.

V tomto případě vytvořte .assetsignore soubor v kořenovém adresáři se statickými aktivy. Tento soubor má stejný formát jako .gitignore.

Wrangler nenahraje soubory s assety, které odpovídají řádkům v tomto souboru.

Příklad

Migrujete z projektu Pages, kde adresář s assets je dist. Kód Workeru běžící na straně serveru ani konfigurační soubory Pages byste neměli nahrávat jako veřejné assety na straně klienta. Přidejte následující .assetsignore soubor:

_worker.js
_redirects
_headers

Wrangler nyní při nasazení Workeru tyto soubory nenahraje jako klientská aktiva.

Ovládá, zda se skript Workeru volá bez ohledu na požadavek, který by jinak odpovídal aktivu. run_worker_first = false (výchozí) obslouží jakékoli statické aktivum odpovídající požadavku, zatímco run_worker_first = true bezpodmínečně vyvolat skript Workeru.

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

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

Můžete také zadat run_worker_first jako pole vzorů tras, aby se skript Workeru spouštěl jako první selektivně jen pro konkrétní trasy.

Pole podporuje glob vzory s * pro hloubkové porovnávání a negativní vzory s ! prefix.

Negativní vzory mají přednost před nenegativními vzory. Worker se spustí jako první, pokud odpovídá nenegativnímu vzoru a zároveň neodpovídá žádnému negativnímu vzoru.

Na pořadí, ve kterém jsou vzory uvedeny, nezáleží.

run_worker_first se často používá společně s not_found_handling = "single-page-application" nastavení:

{
	"name": "my-spa-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"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-08-28"
main = "./src/index.ts"

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

V této konfiguraci požadavky na /api/* trasy nejprve vyvolají skript Workeru, kromě /api/docs/* které bude následovat výchozí chování směrování asset-first.

Časté způsoby použití run_worker_first zahrnují kontroly ověřování, testování A/B a vkládání zaváděcích dat do shellu vaší aplikace SPA.

Konfigurace volitelného binding vám dává přístup ke kolekci assetů z vašeho Worker skriptu.

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

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

Ve výše uvedeném příkladu by byly assety dostupné prostřednictvím env.ASSETS.

Parametry

• request: Request | URL | string Předejte Objekt Request, objekt URL nebo řetězec URL. Požadavky odeslané touto metodou mají html_handling a not_found_handling konfiguraci, která je na ně použita.

Odpověď

• Promise<Response> Vrací odpověď se statickým assetem pro daný požadavek.

Příklad

Váš dynamický kód může vytvářet nové požadavky nebo předávat příchozí požadavky na statická aktiva vašeho projektu pomocí bindingu assets. Například env.ASSETS.fetch(request), env.ASSETS.fetch(new URL('https://assets.local/my-file')) nebo env.ASSETS.fetch('https://assets.local/my-file'). Hostname použitý v URL (například assets.local) nemá žádný význam: funguje jakýkoli platný hostitel. Ke shodě s prostředky se používá jen cesta URL.

Následující příklad ukazuje konfiguraci skriptu Workeru tak, aby vracel odpověď na všechny požadavky směřující na /api/. V opačném případě skript Workeru předá příchozí požadavek dál na asset binding. V tomto případě, protože skript Workeru se volá pouze tehdy, když požadovaná cesta neodpovídá žádnému statickému assetu, se toto vždy vyhodnotí jako not_found_handling chování.

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>;

Různé možnosti konfigurace směrování statických prostředků najdete v Směrování.

Smart Placement lze použít k umístění kódu Workeru blíže vaší backendové infrastruktuře. Smart Placement se projeví pouze v případě, že jste zadali main, odkazující na kód vašeho Workeru.

Pokud chcete spustit Kód Workeru má přednost před assety nastavením run_worker_first=true, všechny požadavky musí nejprve projít přes váš Worker umístěný pomocí Smart Placement. V důsledku toho může docházet ke zvýšené latenci u požadavků na assety.

Použijte Smart Placement s run_worker_first=true když potřebujete integraci s jinými backendovými službami, ověřovat požadavky před doručením jakýchkoli assetů, nebo pokud chcete assety před doručením upravit.

Pokud chcete, aby se některé statické soubory doručovaly uživateli co nejrychleji, zatímco jiné mají procházet přes chytře umístěný Worker, zvažte rozdělení aplikace do více Workerů a použití service bindings k jejich propojení.

Povolení Smart Placement pomocí run_worker_first=false (nebo jeho nezadání) umožňuje doručovat prostředky co nejblíže k vašim uživatelům, ale logiku vašeho Workeru přesune tak, aby běžela co nejefektivněji (například blízko databáze).

Použijte Smart Placement s run_worker_first=false (nebo jeho nezadání) při upřednostnění rychlého doručování prostředků.

Toto nemá vliv na výchozí chování směrování.