← Cloudflare Workers / workers / cache

Ladění

Pokud se cachování nechová podle očekávání, Cf-Cache-Status hlavička odpovědi je první místo, kam se podívat. Nese ji každá odpověď a její hodnota přesně říká, co se s daným požadavkem stalo.

Odešlete dva požadavky na stejnou URL adresu a porovnejte hlavičky:

curl -I https://my-worker.example.workers.dev/api/users/42
curl -I https://my-worker.example.workers.dev/api/users/42

Porovnejte hodnotu stavu s níže uvedenými scénáři.

Cf-Cache-Status chybí. Zkontrolujte, zda máte verzi wrangler 4.69.0 nebo novější a že wrangler.toml nebo wrangler.jsonc obsahuje cache.enabled = true pro daného workera.

Cf-Cache-Status je MISS při každém požadavku, nebo DYNAMIC, nebo BYPASS. Ukládání do cache nic neukládá, nebo se uplatňuje pravidlo pro obejití cache.

Zkontrolujte svůj Cache-Control hlavička. Odpověď musí obsahovat direktivy, díky kterým je možné ji uložit do mezipaměti:

• public, max-age=N : uloženo do mezipaměti Cloudflare a prohlížečů po dobu N sekund.

Odpověď s Cache-Control: private nebo no-store se neukládá a Cf-Cache-Status je BYPASS.

Odpověď s Cache-Control: no-cache je uložena, ale Cloudflare považuje každý následující request za zastaralý a před jeho odbavením se dotáže vašeho Workeru. Přesné Cf-Cache-Status závisí na tom, zda stale-while-revalidate je také nastavena:

• Jen s Cache-Control: no-cache, každý další požadavek spustí okamžitou revalidaci. Cf-Cache-Status je REVALIDATED pokud váš Worker vrátí 304 Not Modified (tělo poskytnuto z mezipaměti), nebo EXPIRED pokud váš Worker vrátí nový 200 (tělo nahrazeno).
• S Cache-Control: no-cache, stale-while-revalidate=N, tělo odpovědi z cache se odešle okamžitě a Worker běží na pozadí. Cf-Cache-Status je UPDATING pro okno SWR.

Pokud chcete dlouhotrvající zásahy v mezipaměti, použijte max-age místo toho. Viz no-cache není obcházením.

Pokud odpověď obsahuje ne Cache-Control hlavičku vůbec, chování závisí na stavovém kódu: Workers Caching použije RFC 9111, heuristická čerstvost ↗ a ukládá do mezipaměti výchozí stavové kódy po heuristickou dobu TTL, například 200 je uložena v mezipaměti po dobu 2 hodin a 404 po dobu 3 minut. Úplnou tabulku výchozích hodnot TTL najdete v Odpovědi bez Cache-Control hlavičkou jsou stále ukládány do mezipaměti v referenční dokumentaci ke konfiguraci. Pokud nechcete, aby se použila některá z těchto výchozích hodnot, nastavte Cache-Control explicitně na odpovědi.

Zkontrolujte metodu požadavku. Pouze GET a HEAD požadavky jsou ukládány do mezipaměti. Všechno ostatní je BYPASS. GET a HEAD požadavky na stejnou URL adresu sdílejí stejnou položku v mezipaměti, více informací najdete v Cache keys o tom, jak Cloudflare plní mezipaměť z obou metod.

Zkontrolujte podmínky automatického obejití. Cloudflare cache obchází v těchto případech:

• Odpověď obsahuje Set-Cookie hlavička.
• Požadavek obsahuje Authorization hlavičku, pokud odpověď výslovně nenastaví Cache-Control: public, must-revalidate, nebo s-maxage.

Pokud váš Worker bezpodmínečně nastavuje Set-Cookie (například cookie relace v každé odpovědi), se odpověď nikdy neukládá do mezipaměti. Cookie buď z odpovědí, které lze ukládat do mezipaměti, odstraňte, nebo rozdělte nastavování cookie a ukládané odpovědi do různých tras.

Zkontrolujte stavový kód. Workers Caching se řídí RFC 9111 ↗. Odpovědi se stavovými kódy, které nejsou ve výchozím nastavení ukládány do cache (například 401, 403, 500) se neukládají, pokud je výslovně neoznačíte direktivami cacheable.

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

• 520-526 jsou považovány za záložní odpovědi Cloudflare a nikdy se neukládají.
• 206 Partial Content vrácená vaším Workerem se neukládá. Workers Caching zpracovává Range požadavky tak, že si z vašeho Workeru vyžádá celé tělo a rozdělí je z uložené položky v mezipaměti. Pokud váš Worker vrátí vlastní 206, je tato odpověď považována za neukládatelnou do cache. Vraťte úplnou 200 místo toho. Viz Range požadavky.

Cf-Cache-Status je MISS při prvním požadavku, ale přesto MISS u následujících požadavků.

Cache je pravděpodobně rozdělena na části. Klíč mezipaměti zahrnuje cestu požadavku, cílový entrypoint a vlastnost volání ctx.props. Dva požadavky, které vám připadají stejné, mohou vytvořit odlišné cache keys, pokud se liší v některém z těchto ohledů.

Časté příčiny:

• Cesta URL nebo query string se mezi požadavky liší (záleží i na koncových lomítkách).
• Volající Worker předává různé ctx.props pro každý požadavek, například jiné ID uživatele.
• Požadavky dopadají na různé pojmenované entrypointy stejného Workeru.

Cloudflare v současnosti nezobrazuje složení cache key, takže vypočítaný klíč nelze zobrazit přímo. Místo toho projděte komponenty uvedené v Cache keys a ověřte, že každá z nich je stejná pro oba požadavky.

To je s výchozí konfigurací očekávané chování. Ve výchozím nastavení Verze Workeru je součástí klíče cache, takže každá nová verze začíná se studenou cache a nemůže znovu použít odpovědi uložené v cache předchozí verze. První požadavky po nasazení jsou promeškané (miss), zatímco se cache nové verze plní, poté se míra zásahů (hit rate) obnoví.

Pokud nasazujete často a vaše odpovědi se mezi nasazeními mění jen zřídka, povolte cache.cross_version_cache pro sdílení uložených odpovědí mezi verzemi a zamezení resetování mezipaměti při každém nasazení. Nevýhodou je, že změny ovlivňující mezipaměť se neprojeví okamžitě, více informací najdete níže.

Ve výchozím nastavení se nasazení projeví okamžitě, protože verze Workeru je součástí cache klíče a nová verze začíná se studenou cache. Pokud stále vidíte odpovědi z předchozí verze, máte cache.cross_version_cache zapnuto, což sdílí položky uložené v cache napříč verzemi. Aby se nasazení projevilo okamžitě a přitom zůstalo zachováno cross_version_cache při:

• Zavolejte ctx.cache.purge({ purgeEverything: true }) po nasazení. Toto je nejjednodušší přístup.
• Označte každou odpověď v cache verzí, která ji vytvořila pomocí vazba metadat verze, poté při rollbacku tento tag vyčistěte (purge). Více informací najdete v Vymazání specifické pro verzi.

Pokud se data na originu změnila, ale požadavky stále vrací zastaralý obsah:

• Zkontrolujte TTL. Odpověď zůstává v mezipaměti po dobu max-age sekund. Může se stát, že se díváte na odpověď, která je stále v rámci svého okna platnosti.
• Vymažte ovlivněné odpovědi. Použijte ctx.cache.purge() se štítky nebo předponou cesty pro zneplatnění konkrétních položek. Viz Vymazávání mezipaměti.
• Přidejte tagy v době zápisu. Pokud jste nenastavili Cache-Tag hlavičky, nemůžete mazat podle tagu. Přidejte tagy ke svým odpovědím ukládaným do mezipaměti, nasaďte je, a jakmile se zapíší nové záznamy, půjde je mazat.

K tomu by nemělo dojít, pokud používáte ctx.props pro autorizační kontext podle jednotlivých volajících. Pokud ano, platí jedno z následujícího:

• Volající ověřujete pomocí hlavičky nebo parametru dotazu, který není součástí cache key. Přesuňte vstup pro autorizaci do ctx.props. Viz Bezpečnost pro více nájemců pomocí ctx.props.
• Service binding voláte s parametrem dotazu specifickým pro uživatele, který chybí. Řetězec dotazu je součástí cache key, ujistěte se, že cesta požadavku každého volajícího se skutečně liší.

UPDATING znamená, že odpověď byla doručena z cache, přestože byla zastaralá, a váš Worker na pozadí běží, aby ji obnovil. Toto chování je očekávané při použití stale-while-revalidate.

Pokud se zobrazí UPDATING častěji, než byste čekali:

• Váš max-age je kratší než rychlost příchodu vašich požadavků. Každý požadavek, který přijde po max-age uplyne, vyvolá revalidaci.
• S max-age=0, stale-while-revalidate=<large>, každý požadavek vyvolá revalidaci. Jde o chování „vždy obsluhovat z mezipaměti“, nikoli „nespouštět Worker“. Přečtěte si Zvolte hodnoty TTL a stale-while-revalidate.

UPDATING se generuje pouze tehdy, když all z následujícího platí:

• Položka v cache existuje, ale je za hranicí své platnosti (zastaralá).
• Odpověď obsahuje stale-while-revalidate=N, a požadavek dorazí do N sekund od okamžiku, kdy záznam zastará.
• Odpověď ne také obsahují s-maxage, must-revalidate, nebo proxy-revalidate.

Pokud je některá z těchto podmínek nepravdivá, požadavky na zastaralé záznamy se místo toho zpracují pomocí inline revalidace, což vede k EXPIRED (Worker vrátil nové tělo odpovědi) nebo REVALIDATED (Worker vrátil 304 Not Modified).

Časté důvody UPDATING se neobjeví:

• Ne stale-while-revalidate direktivu v odpovědi. Výchozí okno SWR je 0, takže bez výslovné direktivy se každý zastaralý požadavek revaliduje synchronně, na popředí.
• s-maxage, must-revalidate, nebo proxy-revalidate je přítomen. Za RFC 9111 §4.2.4 ↗, tyto direktivy zakazují podávání zastaralého obsahu, takže Cloudflare vypíná stale-while-revalidate (a stale-if-error) pokud je přítomná některá z nich. Použijte max-age pro okno aktuálnosti na edge, pokud chcete, aby fungovalo podávání zastaralého obsahu.
• Okno SWR vypršelo. Pokud vaše odpověď používá max-age=60, stale-while-revalidate=120, uvidíte UPDATING pro požadavky přicházející během 120 sekund poté, co záznam zastará. Požadavky přicházející později se vracejí k inline revalidaci.

STALE znamená, že Cloudflare doručil dříve uloženou odpověď z cache, protože při požadavku, který by ji obnovil, došlo u vašeho Workeru k chybě, například Worker vyvolal výjimku, vypršel časový limit nebo vrátil 5xx odpověď. Toto je stale-if-error chování. Více informací najdete v Poskytování zastaralého obsahu při chybě pomocí stale-if-error.

Pokud se zobrazí STALE a neočekávali jste to:

• Váš Worker selhává při plnění cache nebo při revalidacích. Zkontrolujte Přehledový panel pozorovatelnosti Workers pro chyby u požadavků, které měly vrátit čerstvou odpověď. Skutečnost, že klienti vidí zastaralou odpověď namísto 5xx maskuje skutečnou chybu.
• Nenastavili jste stale-if-error explicitně a vaše odpověď neobsahuje s-maxage/must-revalidate/proxy-revalidate. V takovém případě je výchozím chováním Cloudflare při chybě Workeru donekonečna poskytovat zastaralé odpovědi, dokud není daný záznam z cache vymazán. Pokud chcete, aby se chyby klientům projevily rychle, nastavte stale-if-error=0 v Cache-Control. Podrobnosti najdete v Poskytování zastaralého obsahu při chybě pomocí stale-if-error.
• Poskytuje se dříve nasazená verze. Pokud jste nasadili opravu, ale STALE se stále objevuje, při každé chybě se i nadále vrací záznam z cache patřící nefunkční verzi. Vymazání ovlivněné položky, aby se vynutilo nové naplnění z aktuální verze.

Chcete-li odlišit STALE z běžného HIT v klientské observabilitě zaznamenejte Cf-Cache-Status společně s odpovědí, STALE je jediným signálem, že Worker selhává a klienti to nevidí.

Pokud je odpověď na uložení do cache příliš velká, Cloudflare ji neuloží. Zobrazí se Cf-Cache-Status: MISS při každém požadavku, i když odpověď jinak vypadá jako uložitelná do mezipaměti.

Limity velikosti odpovědi podle plánu najdete v Limity velikosti pro ukládání do mezipaměti. Vezměte na vědomí, že při spuštění všechny odpovědi Workers Caching podléhají limitu velikosti platného pro plán Free, viz Velikost odpovědi s podrobnostmi.

Při spuštění jsou hlavními nástroji pro ladění Cf-Cache-Status hlavičku odpovědi a informace o zásahu do mezipaměti pro jednotlivá volání v Přehledový panel pozorovatelnosti Workers.