INTEGRITY Dokumentace

Konfigurace

Workers Caching se konfiguruje pro každý Worker ve vašem konfiguračním souboru Wrangler. Po zapnutí se ukládání do mezipaměti vztahuje na každý fetch() volání: požadavky od uživatelů, service binding fetch() volání a loopback fetch() volání mezi entrypointy přes ctx.exports, unless you zakázat ji pro konkrétní entrypoint. Vlastní Metody RPC obejde cache.

Toto je cache vašeho Workeru : nakonfigurováno prostřednictvím kódu vašeho Workeru a souboru Wrangler. Váš Worker plně řídí svou mezipaměť pomocí:

To je celý rozsah konfigurace.

Povolení cachování

Přidejte cache blok do konfigurace Wrangler:

{
	"name": "my-worker",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"cache": {
		"enabled": true,
	},
}
name = "my-worker"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-08-28"

[cache]
enabled = true

Nastavení cache.enabled na true způsobí, že Cloudflare zkontroluje cache před každým voláním vašeho Workeru při každém HTTP požadavku. Toto je výchozí chování pro každý entrypoint; můžete ho pro jednotlivé entrypointy přepsat pomocí exports.

cache blok přijímá dvě pole: enabled (povinné) a cross_version_cache (volitelné). Všechna ostatní pole jsou vyhrazena pro budoucí použití a v budoucích verzích Wrangleru mohou způsobit chyby ověření.

Zakázat ukládání do mezipaměti

Chcete-li vypnout ukládání do mezipaměti, nastavte cache.enabled na false (nebo odeberte cache blok) a znovu nasaďte:

{
	"name": "my-worker",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"cache": {
		"enabled": false,
	},
}
name = "my-worker"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-08-28"

[cache]
enabled = false

Zakázání ukládání do mezipaměti nevymaže dříve uložené odpovědi: pouze zabrání Cloudflare kontrolovat mezipaměť nebo do ní ukládat data u dalších požadavků. Pokud ukládání do mezipaměti později znovu povolíte, záznamy, které jsou stále v rámci platnosti TTL, budou opět použitelné. Pokud potřebujete, aby se ukládané odpovědi přestaly podávat okamžitě, vymazat cache po vypnutí.

Ukládání do mezipaměti pro jednotlivé entrypointy

cache.enabled nastavuje výchozí hodnotu pro celý Worker, ale Worker může vystavovat několik entrypoints, the default export and any number of named WorkerEntrypoint tříd, přičemž cachování můžete pro každou z nich zapnout nebo vypnout nezávisle. Použijte exports mapu, klíčovanou podle názvu entrypointu, s "default" odkazující na výchozí export:

{
	"name": "my-worker",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"cache": {
		"enabled": true,
	},
	"exports": {
		// Opt the default entrypoint out of caching.
		"default": { "type": "worker", "cache": { "enabled": false } },
		// Keep caching on for the Admin entrypoint.
		"Admin": { "type": "worker", "cache": { "enabled": true } },
	},
}
name = "my-worker"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-08-28"

[cache]
enabled = true

[exports.default]
type = "worker"

  [exports.default.cache]
  enabled = false

[exports.Admin]
type = "worker"

  [exports.Admin.cache]
  enabled = true

Každá položka je { "type": "worker", "cache": { "enabled": <boolean> } }. Nastavení cache.enabled přepisuje nastavení nejvyšší úrovně cache.enabled pro daný entrypoint; entrypointy, které neuvedete, dědí hodnotu z nejvyšší úrovně. Ukládání do mezipaměti můžete povolit i pro jeden entrypoint bez hodnoty na nejvyšší úrovni cache blok tak, že uvedete pouze tento entrypoint.

Díky tomu můžete aktivovat a deaktivovat konkrétní entrypointy beze změny kódu vašeho Workeru:

Verzovaná nasazení

cache konfigurace je součástí verze vašeho Workeru:

Sdílení cache mezi verzemi

Ve výchozím nastavení Verze Workeru je součástí klíče cache. Každá nasazená verze má vlastní izolovanou mezipaměť, takže nové nasazení začíná s prázdnou mezipamětí a nikdy neposkytuje odpovědi zapsané předchozí verzí. Toto chování je výchozí, protože se nejsnáze chápe: nové nasazení se projeví okamžitě a nikdy neposkytnete odpověď, kterou vytvořila nahrazená verze.

Kompromis spočívá v tom, že míra úspěšnosti cache se po každém nasazení vynuluje. Protože nová verze nemůže znovu použít odpovědi uložené v cache z předchozí verze, jsou první požadavky po nasazení neúspěšné, dokud se cache nové verze nezaplní. To je nejčastější důvod, proč hned po nasazení klesá míra úspěšnosti cache u Workeru.

Pokud chcete maximalizovat míru zásahů v mezipaměti a jste ochotni akceptovat pomalejší nasazování změn ovlivňujících mezipaměť, nastavte cross_version_cache na true. Odpovědi uložené v cache se poté sdílejí napříč verzemi: odpověď zapsanou jednou verzí může obsloužit pozdější verze, dokud nevyprší její TTL:

{
	"name": "my-worker",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"cache": {
		"enabled": true,
		"cross_version_cache": true,
	},
}
name = "my-worker"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-08-28"

[cache]
enabled = true
cross_version_cache = true

Pokročilí uživatelé, kteří nasazují často a jejichž odpovědi se mezi většinou nasazení nemění, by měli zvážit povolení cross_version_cache : vyhnete se tak zahazování zahřáté mezipaměti při každém nasazení. Cenou za to je, že nasazení už mezipaměť neinvaliduje: po změně, která ovlivní obsah odpovědi, se starší uložené odpovědi nadále poskytují, dokud nevyprší jejich platnost nebo dokud vymazání je, a během postupné nasazení obě verze sdílejí jednu cache. Pokud potřebujete, aby se nasazení projevilo okamžitě s cross_version_cache zapnuto, po nasazení vyprázdněte cache, nebo označte odpovědi verzí. Podrobnosti v Zneplatňování cache napříč nasazeními.

cross_version_cache má vliv pouze tehdy, když je zapnuté ukládání do mezipaměti. Vztahuje se na každý entrypoint, u kterého je mezipaměť zapnutá.

Konfigurace specifická pro dané prostředí

cache blok lze nastavit na nejvyšší úrovni a přepsat pro jednotlivé prostředí. Obvyklým postupem je zapnout cachování v produkci až ve chvíli, kdy jste si jistí, že je to bezpečné, zatímco staging necháváte bez cache kvůli snazšímu ladění:

{
	"name": "my-worker",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"cache": {
		"enabled": false,
	},
	"env": {
		"production": {
			"cache": {
				"enabled": true,
			},
		},
	},
}
name = "my-worker"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-08-28"

[cache]
enabled = false

[env.production.cache]
enabled = true

Sémantika Cache-Control

Když je cachování zapnuté, váš Worker slouží jako origin pro cache Cloudflare. Standardní HTTP Cache-Control direktivy v odpovědi, kterou váš Worker vrací, určují, zda a jak dlouho ji Cloudflare uloží do mezipaměti. Úplný seznam direktiv a jejich vzájemné působení najdete v Cache-Control.

Nastavte okno aktuálnosti pomocí max-age

Použijte max-age pro řízení toho, jak dlouho je odpověď považována za aktuální:

src/index.js
export default {
	async fetch(request) {
		const body = await renderPage(request);

		return new Response(body, {
			headers: {
				"Content-Type": "text/html",
				// Cached for 1 hour at Cloudflare's edge and in the browser.
				"Cache-Control": "public, max-age=3600",
			},
		});
	},
};

// Replace with your own rendering logic.
async function renderPage(request) {
	return `<!doctype html><title>Home</title><h1>Hello</h1>`;
}
src/index.ts
export default {
	async fetch(request): Promise<Response> {
		const body = await renderPage(request);

		return new Response(body, {
			headers: {
				"Content-Type": "text/html",
				// Cached for 1 hour at Cloudflare's edge and in the browser.
				"Cache-Control": "public, max-age=3600",
			},
		});
	},
} satisfies ExportedHandler;

// Replace with your own rendering logic.
async function renderPage(request: Request): Promise<string> {
	return `<!doctype html><title>Home</title><h1>Hello</h1>`;
}

Pokud potřebujete, aby prohlížeče a edge ukládaly do mezipaměti na různě dlouhou dobu, použijte cdn-cache-control (nebo cloudflare-cdn-cache-control) pro direktivu platnou pouze na edge a ponechte Cache-Control pro to, co vidí prohlížeče. Podrobnosti najdete v Priorita hlaviček níže.

Použijte stale-while-revalidate pro obnovování s nízkou latencí

Když odpověď uložená v mezipaměti zastará, stale-while-revalidate umožňuje Cloudflare okamžitě vrátit zastaralou odpověď a aktualizovat ji na pozadí:

src/index.js
export default {
	async fetch(request) {
		const data = { timestamp: Date.now() };

		return new Response(JSON.stringify(data), {
			headers: {
				"Content-Type": "application/json",
				// Fresh for 10 minutes; may be served stale for up to 1 minute
				// while a background revalidation runs.
				"Cache-Control": "public, max-age=600, stale-while-revalidate=60",
			},
		});
	},
};
src/index.ts
export default {
	async fetch(request): Promise<Response> {
		const data = { timestamp: Date.now() };

		return new Response(JSON.stringify(data), {
			headers: {
				"Content-Type": "application/json",
				// Fresh for 10 minutes; may be served stale for up to 1 minute
				// while a background revalidation runs.
				"Cache-Control": "public, max-age=600, stale-while-revalidate=60",
			},
		});
	},
} satisfies ExportedHandler;

Zvolte hodnoty TTL a stale-while-revalidate

Vysoká úspěšnost zásahů do mezipaměti a vysoká aktuálnost dat jsou ve vzájemném rozporu. Revalidace na pozadí skrývá latenci obnovování mezipaměti, ale váš Worker se přesto při každé revalidaci znovu spustí. Není to zadarmo.

Dva běžné vzory:

Poskytování zastaralého obsahu při chybě pomocí stale-if-error

stale-if-error umožňuje Cloudflare vrátit dříve uloženou odpověď z cache v případě, že Worker selže při obnovování vypršelé položky v cache, například když dojde k výjimce, vypršení časového limitu nebo vrácení 5xx odpověď. To chrání klienty před dočasnými výpadky Workeru.

"Cache-Control": "public, max-age=600, stale-if-error=86400",

Když Worker vytváří novou odpověď, stale-if-error nemá žádný účinek. Pokud Worker selže při obnovování vypršelé položky, Cloudflare doručí poslední úspěšně uloženou odpověď z mezipaměti (s Cf-Cache-Status: STALE) až do stale-if-error okno. Skutečný výpadek mezipaměti (bez předchozího záznamu) nemůže využít stale-if-error protože neexistuje žádný zastaralý obsah, který by bylo možné obsloužit: chyby Workeru v takovém případě procházejí přímo ke klientům.

Priorita hlaviček

Pokud je přítomno více hlaviček mezipaměti, vyhrává ta nejspecifičtější:

  1. cloudflare-cdn-cache-control : specifické pro Cloudflare, nejvyšší priorita. Cloudflare je zpracuje a odstraní z odpovědi vracené klientům.
  2. cdn-cache-control, standard header for CDN-only directives. Respected by Cloudflare and passed through to downstream CDNs.
  3. Cache-Control, standard HTTP header. Respected by Cloudflare and passed through to clients.

Použijte cloudflare-cdn-cache-control když chcete delší edge TTL, než jaké zveřejňujete prohlížečům, aniž by se tato direktiva dostala dál po řetězci.

Přepsat Cache-Control od volajícího Workeru

Volaná strana obvykle rozhoduje, jak se její odpovědi ukládají do cache, pomocí nastavení Cache-Control na nich. Když jeden entrypoint vyvolá jiný cachovaný entrypoint přes ctx.exports loopback, volání vstupní bod může místo toho poskytnout Cache-Control direktivu pro dané volání nastavením cf.cacheControl na požadavku.

Zde Backend vstupní bod nevrací žádné Cache-Control vlastní; výchozí entrypoint rozhoduje o zásadách ukládání do mezipaměti při volání Backend přes ctx.exports:

src/index.js
import { WorkerEntrypoint } from "cloudflare:workers";

// Cached entrypoint. It does not set Cache-Control itself.
export class Backend extends WorkerEntrypoint {
	async fetch(request) {
		return new Response("Hello from the backend", {
			headers: { "Content-Type": "text/html" },
		});
	}
}

// Gateway entrypoint. Caches the Backend's response for this call for
// 5 minutes, without the Backend needing to set Cache-Control itself.
export default {
	async fetch(request, env, ctx) {
		return ctx.exports.Backend.fetch(request, {
			cf: { cacheControl: "public, max-age=300" },
		});
	},
};
src/index.ts
import { WorkerEntrypoint } from "cloudflare:workers";

// Cached entrypoint. It does not set Cache-Control itself.
export class Backend extends WorkerEntrypoint<Env> {
	async fetch(request: Request): Promise<Response> {
		return new Response("Hello from the backend", {
			headers: { "Content-Type": "text/html" },
		});
	}
}

// Gateway entrypoint. Caches the Backend's response for this call for
// 5 minutes, without the Backend needing to set Cache-Control itself.
export default {
	async fetch(request, env, ctx): Promise<Response> {
		return ctx.exports.Backend.fetch(request, {
			cf: { cacheControl: "public, max-age=300" },
		});
	},
} satisfies ExportedHandler<Env>;

Cloudflare zachází s cf.cacheControl jako důvěryhodný Cache-Control direktivu pro ukládání odpovědi volané funkce do mezipaměti pro dané volání. Hodnota je standardní Cache-Control string a řídí se stejná sémantika direktivy popsané v celém tomto článku: max-age, stale-while-revalidate, no-store, a tak dále. Volající entrypoint díky tomu může určit, jak se mají ukládat odpovědi cachovaného entrypointu, aniž by musel upravovat jeho kód.

Stejně jako vlastní klíče mezipaměti, cf.cacheControl se respektuje pouze u volání, která zůstávají v rámci vašeho účtu. Cloudflare odstraní cf objekt pokaždé, když požadavek překročí hranici účtu, takže volající v jednom účtu nemůže změnit způsob, jakým Worker v jiném účtu ukládá své odpovědi do mezipaměti. Direktiva také nemá žádný vliv na požadavky typu eyeball, protože cf objekt u příchozího požadavku vyplňuje Cloudflare, nikoli klient.

Hlavičky odpovědi

Cf-Cache-Status

Každá odpověď obsahuje Cf-Cache-Status hlavička uvádějící, co se s daným požadavkem stalo. Nejčastěji uvidíte tyto hodnoty: HIT, MISS, EXPIRED, REVALIDATED, UPDATING, STALE, a BYPASS. Úplný seznam hodnot a jejich významů najdete v Odpovědi mezipaměti Cloudflare.

Cache-Tag

Cache-Tag hlavička odpovědi připojuje ke kešované odpovědi značky, díky nimž ji později můžete hromadně vyčistit. Cloudflare tuto hlavičku zpracuje a před doručením odpovědi klientovi ji odstraní.

src/index.js
export default {
	async fetch(request) {
		const html = `<!doctype html><title>Post</title>`;

		return new Response(html, {
			headers: {
				"Content-Type": "text/html",
				"Cache-Control": "public, max-age=3600",
				"Cache-Tag": "blog,posts,post-123",
			},
		});
	},
};
src/index.ts
export default {
	async fetch(request): Promise<Response> {
		const html = `<!doctype html><title>Post</title>`;

		return new Response(html, {
			headers: {
				"Content-Type": "text/html",
				"Cache-Control": "public, max-age=3600",
				"Cache-Tag": "blog,posts,post-123",
			},
		});
	},
} satisfies ExportedHandler;

Cache-Tag hlavičky je seznam tagů oddělených čárkami. Platí stejné limity jako pro mezipaměť zóny, více informací najdete v Limity cache tagů pro úplný seznam. Nejčastější omezení, na která je třeba pamatovat:

Neplatné tagy (příliš dlouhé, obsahující mezery nebo znaky mimo ASCII) se při ukládání do cache tiše zahodí. Odpověď se přesto uloží do cache se zbývajícími platnými tagy, ale nijak nezjistíte, které tagy byly zahozeny. Pokud na tom záleží, ověřte tagy ve Workeru ještě před jejich odesláním.

Podmínky automatického obcházení

Workers Caching dědí standardní pravidla pro obcházení cache. Nejčastější příčiny:

Pokud platí kterákoli z těchto podmínek, Cf-Cache-Status je BYPASS a váš Worker se spustí při každém požadavku.

Stavové kódy, které se nikdy neukládají do mezipaměti

Několik stavových kódů se nikdy neukládá, a to ani při explicitním Cache-Control direktivy:

Range požadavky

Workers Caching poskytuje Range požadavky z uložené úplné odpovědi, váš Worker tak nemusí implementovat dělení podle bajtových rozsahů (byte range slicing).

Když klient odešle Range požadavek, Cloudflare odstraní Range hlavičku před vyvoláním vašeho Workeru a požádá váš Worker o celé tělo. Váš Worker vrátí běžnou 200 odpověď s Cache-Control hlavička (stejně jako u jakéhokoli jiného požadavku), Cloudflare uloží celou tuto odpověď do mezipaměti a poté z ní vyřízne požadovaný rozsah bajtů a vrátí ho klientovi jako 206 Partial Content odpověď (nebo 416 Range Not Satisfiable pokud je rozsah neplatný). Následné Range požadavky na stejnou URL adresu jsou zcela obslouženy z položky v mezipaměti, váš Worker se nevyvolá a Cf-Cache-Status je HIT.

Například GET hodnotou Range: bytes=0-9 proti studené cache vytvoří MISS cestou dovnitř (váš Worker se spustí a vrátí celé tělo), poté vrátí 206 s prvními 10 bajty. Navazující GET Range: bytes=10-19 pro stejnou URL je HIT a vrátí těchto 10 bajtů z mezipaměti, aniž by vyvolal váš Worker.

Pokud váš Worker vrátí 206 vlastní odpověď, například proto, že jste implementovali Range zpracování uvnitř Workeru: Cloudflare ji považuje za odpověď, kterou nelze ukládat do mezipaměti, a neuloží ji. Vraťte úplnou 200 a nechte dělení rozsahů (range slicing) na Workers Caching.

Vary

Když váš Worker vrátí Vary hlavička odpovědi, Cloudflare ukládá samostatnou variantu v mezipaměti pro každou odlišnou kombinaci hodnot uvedených hlaviček požadavku a vrací pouze variantu, jejíž uložené hodnoty odpovídají příchozímu požadavku. Tím se implementuje RFC 9110 a výpočet klíče mezipaměti (cache key) v RFC 9111. Úvod s ukázkovým kódem najdete v Vyjednávání obsahu pomocí Vary.

Jak Vary se zpracovává pro Workers Caching:

Accept-Encoding a Content-Encoding

Váš Worker si sám řídí vyjednávání obsahu. Cokoli Content-Encoding váš Worker nastaví na odpovědi, je to, co Cloudflare uloží a poskytne dalším požadavkům.

Pokud váš Worker potřebuje vracet různá kódování různým klientům, máte dvě možnosti: