导航|地址|刷新
Serving tailored content with Cloudflare

Skip to contentDocumentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/cache/llms.txt
Use this file to discover all available pages before exploring further.

Docs Directory API SDKs Changelog

Search

Log in

Cache / CDN

/

Overview

Plans

Get started

Concepts

CDN-Cache-Control

Cloudflare cache responses

Customize cache

Default cache behavior

Head Requests and Set-Cookie Headers

Origin Cache Control

Retention vs Freshness (TTL)

Revalidation

Vary

Cache configuration

Purge cache

Overview

Purge by single-file

Purge everything

Purge cache by cache-tags

Purge cache by hostname

Purge cache by prefix (URL)

Purge cache key resources

Purge varied images

Purge zone versions via API

Cache Response Rules

Overview

Create a rule in the dashboard

Create a rule via API

Terraform example

Available settings

Cache Rules

Overview

Create a rule in the dashboard

Create a rule via API

Terraform example

Available settings

Order and priority

Examples

Overview

Browser Cache TTL

Bypass Cache on Cookie

Cache by Device Type

Cache Deception Armor

Cache everything for hostnames in a list

Cache Everything while ignoring query strings

Cache Level (Cache Everything)

Cache TTL by status code

Custom Cache Key

Edge Cache TTL

Origin Cache Control

Query String Sort

Respect Strong ETags

Migration from Page Rules

Edge and Browser Cache TTL

Overview

Set Browser Cache TTL

Always Online

Cache by status code

Cache keys

Caching levels

Tiered Cache

Advanced configuration

Serving tailored content

Cache Reserve

Crawler Hints

Early Hints

Query String Sort

Vary for images

Performance review

Cache Analytics

Cache performance

Cache security

Avoid web cache poisoning

Cache Deception Armor

Cross-Origin Resource Sharing (CORS)

Reference

CDN Reference Architecture ↗

CSAM Scanning Tool

Development Mode

Using ETag Headers with Cloudflare

Interaction with Cloudflare products

Customize cache behavior with Workers

How Workers interact with Cache Rules

Enable cache in an R2 bucket

Control cache access with WAF and Snippets

Troubleshooting

Dynamic content and login issues

Issues with MP4 videos on iOS and Safari

Bot Management cookie causes cache bypass in O2O setups

edgeResponseBytes and cacheResponseBytes discrepancy

Always Online

Changelog

Glossary

Agent resources

Agent setup ↗

Cloudflare Skills ↗

Code Mode MCP Server ↗

Domain-specific MCP Servers ↗MCP

Cache llms.txt ↗

Cache llms-full.txt ↗

Cloudflare Docs llms.txt ↗

Cloudflare Docs llms-full.txt ↗

Home

/Cache / CDN

/Advanced configuration

/Serving tailored content

Serving tailored content with Cloudflare

Last updated Apr 16, 2026|Copy as Markdown|View as Markdown|Agent setup

OverviewUse query strings Geolocation exampleVary for Images Enable Vary for ImagesUse Snippets for programmatic caching Example: A/B testingCustom Cache Keys (Enterprise) Example: Same URL, different contentUse Cloudflare Workers for advanced logic Example: Device type – Free/Pro/Biz (without Tiered Cache) Example: Device type – Enterprise (with Tiered Cache)Example: Caching Next.js RSC payloads Method 1: Transform Rules Method 2: Snippets or Custom Cache Keys

Content negotiation is the practice of serving different versions of a resource from a single URL, tailoring the experience to the end user. Common examples include delivering content in a specific language (Accept-Language), optimizing for a device (User-Agent), or serving modern image formats (Accept).

Cloudflare's global network is designed to handle this at scale. For common scenarios such as serving next-generation images, this negotiation is streamlined with a dedicated feature. For more customized logic, Cloudflare provides a toolkit including Transform Rules, Snippets, Custom Cache Keys, and Workers, giving you granular control to ensure the right content is served to every user, every time.

------

Use query strings

The Transform Rule method is ideal when you can create a distinct URL, such as serving content based on a visitor's location.

Geolocation example

In this example, you run an e-commerce site and want to display prices in the local currency based on the visitor's country.

In the Cloudflare dashboard, go to the Rules Overview page.
Go to Overview ↗

Select Create rule and select the option URL Rewrite Rule.

Enter a descriptive name, such as Vary by Country - Canada.

In If incoming requests match..., select Custom filter expression.

Under When incoming requests match..., create the following expression:

Field:Country

Operator:equals

Value:Canada

Under Then...

for Path, select Preserve.

for Query, select Rewrite to: Dynamicloc=ca

Select Save.

Now, requests from Canada to /products/item will be transformed to /products/item?loc=ca before reaching your origin or the cache, creating a distinct cache entry.

Availability

Free, Pro, Business, and Enterprise plans

------

Vary for Images

Vary for Images tells Cloudflare which variants your origin supports. Cloudflare then caches each version separately and serves the correct one to browsers without contacting your origin each time. This feature is managed via the Cloudflare API.

Enable Vary for Images

To enable this feature, create a variants rule using the API. This rule maps file extensions to the image formats your origin can serve.

For example, the following API call tells Cloudflare that for .jpeg and .jpg files, your origin can serve image/webp and image/avif variants:

Required API token permissions
At least one of the following token permissions is required:
Zone Settings Write

Zone Write
Change variants settingbashcurl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/cache/variants" \ --request PATCH \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "value": { "jpeg": [ "image/webp", "image/avif" ], "jpg": [ "image/webp", "image/avif" ] } }'
After creating the rule, Cloudflare will create distinct cache entries for each image variant, improving performance for users with modern browsers.

Availability

Pro, Business, and Enterprise plans

Use Snippets for programmatic caching

Snippets are self-contained JavaScript fetch handlers that run at the edge on your requests through Cloudflare. They allow you to programmatically interact with the cache, providing full control over the cache key and response behavior without changing the user-facing URL.

Example: A/B testing

In this example, you run an A/B test controlled by a cookie named ab-test (with values group-a or group-b). You want to cache a different version of the page for each group.

In the Cloudflare dashboard, go to the Snippets page.
Go to Snippets ↗

Select Create new Snippet and name it ab-test-caching.

Paste the following code. It modifies the cache key based on the ab-test cookie and caches the response for 30 days.

const CACHE_DURATION = 30 * 24 * 60 * 60; // 30 daysexport default { async fetch(request) { // Construct a new URL for the cache key based on the A/B cookie const abCookie = request.headers.get('Cookie')?.match(/ab-test=([^;]+)/)?.[1] || 'control'; const url = new URL(request.url); url.pathname = `/ab-test/${abCookie}${url.pathname}`; const cacheKey = new Request(url, request); const cache = caches.default; let response = await cache.match(cacheKey); if (!response) { // If not in cache, fetch from origin response = await fetch(request); response = new Response(response.body, response); response.headers.set("Cache-Control", `s-maxage=${CACHE_DURATION}`); // Put the response into cache with the custom key await cache.put(cacheKey, response.clone()); } return response; },};
Save and deploy the Snippet.

From the Snippets dashboard, select Attach to routes to assign the Snippet.

Availability

Pro, Business, and Enterprise plans

Custom Cache Keys (Enterprise)

If your account is on an Enterprise plan, the Custom Cache Keys feature provides a no-code interface to define which request properties are included in the cache key.

Custom Cache Key options:

Cache by device type

Query string option No query string parameters except

Include headers and values

Include cookie names and values

User: Device type, Country, Language

Example: Same URL, different content

If your origin serves different content types (for example, application/json vs. text/html) at the same URL based on the Accept header, use a custom cache key to cache them separately.

In the Cloudflare dashboard, go to the Cache Rules page.
Go to Cache Rules ↗

Select Create rule.

Enter rule name, such as Vary by Accept Header.

Set the condition for the rule to apply (for example, a specific hostname or path).

Under Cache key, select Use custom key.

Select Add new.

Type: Header

Name: Accept

Value: Add each value, or leave empty for all.

Select Deploy.

This configuration creates separate cache entries based on the Accept header value, respecting your API's content negotiation.

Availability

Enterprise plans only

Use Cloudflare Workers for advanced logic

For complex caching scenarios, Cloudflare Workers provide a full serverless environment ideal for custom logic at scale.

Example: Device type – Free/Pro/Biz (without Tiered Cache)

This Worker detects whether a visitor is on a mobile or desktop device and creates separate cache entries for each, ensuring the correct version of the site is served and cached.
export default { async fetch(request, env, ctx) { const userAgent = request.headers.get('User-Agent') || ''; const deviceType = userAgent.includes('Mobile') ? 'mobile' : 'desktop'; // Create a new URL for the cache key that includes the device type const url = new URL(request.url); url.pathname = `/${deviceType}${url.pathname}`; const cacheKey = new Request(url, request); const cache = caches.default; let response = await cache.match(cacheKey); if (!response) { console.log(`Cache miss for ${deviceType} device. Fetching from origin.`); response = await fetch(request); let responseToCache = response.clone(); ctx.waitUntil(cache.put(cacheKey, responseToCache)); } return response; },};

Availability

Free and Paid plans

Example: Device type – Enterprise (with Tiered Cache)

This Worker detects if a visitor is on a mobile device or a desktop and creates a separate cache entry for each, ensuring the correct version of the site is served and cached. Uses the Enterprise cf.customCacheKey feature.
export default { async fetch(request) { // 1. Determine the device type from the User-Agent header const userAgent = request.headers.get('User-Agent') || ''; const deviceType = userAgent.includes('Mobile') ? 'mobile' : 'desktop'; // 2. Create a custom cache key by appending the device type to the URL const customCacheKey = `${request.url}-${deviceType}`; // 3. Fetch the response. Cloudflare's cache automatically uses the // customCacheKey for cache operations (match, put). const response = await fetch(request, { cf: { cacheKey: customCacheKey, }, }); // Optionally, you can modify the response before returning it // For example, add a header to indicate which cache key was used const newResponse = new Response(response.body, response); newResponse.headers.set("X-Cache-Key", customCacheKey); return newResponse; },};

Availability

Enterprise only

Example: Caching Next.js RSC payloads

A common challenge is caching content from frameworks like Next.js, which uses an RSC (React Server Components) request header to differentiate between HTML page loads and RSC data payloads for the same URL. Here are the best ways to handle this.

Method 1: Transform Rules

The simplest solution is to create a Transform Rule that checks for the RSC header and adds a unique query parameter on the request, creating two distinct cacheable URLs: /page (for HTML) and /page?_rsc=1 (for the RSC payload).

In the Cloudflare dashboard, go to the Rules Overview page.
Go to Overview ↗

Select Create rule and select the option URL Rewrite Rule.

Enter a name, such as Vary by RSC Header.

In If incoming requests match, select Custom filter expression.

Under When incoming requests match, manually edit the expression so that it checks for the presence of the RSC header:

has_key(http.request.headers, "rsc")

Under Then:

For Path, select Preserve.

For Query, select Rewrite to, select Static: _rsc=1.

Select Save.

Method 2: Snippets or Custom Cache Keys

Alternatively, use Snippets or Custom Cache Keys to add the RSC header directly to the cache key without modifying the visible URL. This provides a cleaner URL but requires more advanced configuration.

Availability

Snippets: Pro, Business, Enterprise

Custom Cache Keys: Enterprise only

PreviousTiered CacheNextCache Reserve

Was this helpful?

YesNo

Edit pageReport issue

On this page

Overview

Use query strings

Geolocation example

Vary for Images

Enable Vary for Images

Use Snippets for programmatic caching

Example: A/B testing

Custom Cache Keys (Enterprise)

Example: Same URL, different content

Use Cloudflare Workers for advanced logic

Example: Device type – Free/Pro/Biz (without Tiered Cache)

Example: Device type – Enterprise (with Tiered Cache)

Example: Caching Next.js RSC payloads

Method 1: Transform Rules

Method 2: Snippets or Custom Cache Keys

Edit pageReport issue

Getting started
PlansContact salesPartnersFind a partnerStartupsUnder attack?Domain name search

Company
AboutCareersInvestorsPressPress kitGlobal network

Public interest
Project GalileoAthenian ProjectCloudflare for CampaignsProject FairshotImpact/ESG

Compliance
Compliance resourcesTrust HubData ProtectionResponsible AITransparency reportReport abuse

Resources
App innovation reportCloudflare RadarCase studiesStatusSupportEventsBlog

Developers
DocumentationLearning centerCommunity

Solutions
SSE and SASE platformCloudflare AI CloudAI SecurityFrontend Development PlatformMulti-Tenant Platform DevelopmentWeb Security Platform

Start BuildingLog In

© 2026 Cloudflare, Inc.

Privacy policy|Report security issues|Terms of use|Trademark
|
Your privacy choices

Docs
…(内容过长已截断)

------
导航页打开网址