custom cache key-CDN(CDN)-阿里云帮助中心

A cache key is the unique identifier for a file cached on a CDN point of presence (POP). By default, the cache key is the request URL, including its parameters.

Feature comparison

Parameter filtering and Custom cache key conflict. Enabling parameter filtering removes query string parameters from URLs, which makes any parameters you configured in a custom cache key ineffective. Verify that you have not created custom cache keys before enabling this feature.

CDN provides three features that control how URL query strings affect caching. The following table compares them.

Use case	Parameter filtering	Custom CacheKey
Ignore all query parameters in the cache key	Set Ignore Parameters to Yes and leave Retain Specified Parameters blank.	Add a request parameter rule: set Action to Retain and Parameter Name to a non-existent value such as `example-argument`.
Retain only `key1` in the cache key	Set Ignore Parameters to Yes and set Retain Specified Parameters to `key1`.	Add a request parameter rule: set Action to Retain and Parameter Name to `key1`.
Remove only `key1` from the cache key	Set Remove Specified Parameters to `key1`.	Add a request parameter rule: set Action to Delete and Parameter Name to `key1`.

Rewrite origin parameters: To modify query parameters in origin requests, use Rewrite origin parameters instead. Setting cache key only changes request URL without modifying the origin URL.
Purge cache: After you configure a custom cache key, if you purge resources by URL, the task may not match the cached content. Submit the cache key generated by the custom cache key feature as the object to purge.

Use cases

Cache key customization serves two opposite goals: consolidating requests or splitting them.

Consolidate: Multiple requests for the same file have different URLs due to varying parameters. POPs treat them as separate files and cache them individually, increasing origin fetches. A custom cache key rule unifies these requests under a single cache key.

Split: Multiple requests share the same URL but require different cached responses — for example, based on a client type header. Without a custom cache key, CDN serves all clients the same cached file. Adding the header value to the cache key creates separate cache entries per client type.

场景一场景二

Important

When a feature configuration references rule conditions configured in the rules engine, the execution order follows the priority order of the associated rule conditions, not the priority order of the feature configurations.

Configure a custom cache key

Log on to the CDN console.
In the left navigation pane, click Domain Names.
On the Domain Names page, find the accelerated domain name and click Manage in the Actions column.
In the domain's navigation pane, click Cache.
On the Custom Cache Key tab, click Configure.

Set the cache key rules using the parameters described in the following table.

Parameter	Description
Rule Condition	Filters requests by request attributes to determine which requests this rule applies to. Important When a feature configuration references rule conditions configured in the rules engine, the execution order follows the priority order of the associated rule conditions, not the priority order of the feature configurations. Defaut: do not use rule conditions . To add or edit rule conditions, go to Rules Engine.
URIs	Replaces a matched URI path with a different path when constructing the cache key. Set Source URI to the original path pattern (must start with `/`, no `http://` prefix or domain; supports PCRE regular expressions) and Final URI to the replacement path (must start with `/`, no `http://` prefix or domain). When multiple URI replacement rules exist, they are matched top-down and the first match applies.
Request Parameter	Modifies the query string parameters in the cache key. Supported operations: Add (append new parameters), Delete (remove specified parameters), Modify (change a parameter's value), and Reserve (keep only specified parameters, drop the rest). When multiple operations exist, they run sequentially top-down. If multiple operations target the same parameter, the priority order is: Add > Delete > Reserve > Modify.
HTTP Headers	Appends the values of specified HTTP request headers to the cache key. Separate multiple header names with spaces. Header values are appended in the order listed.
Custom Variables	Extracts a value from a request parameter, HTTP header, cookie, or URI path using a regular expression, then appends the extracted value to the cache key. For usage details and examples, see Configuration examples.

自定义Cachekey

Click OK.

Configuration examples

URIs

To treat requests for http://aliyundoc.com/a/b/image.jpg and http://aliyundoc.com/a/b/c/image.jpg as the same file, configure a URI rule that maps both paths to /c/image.jpg. Both requests resolve to the cache key http://aliyundoc.com/c/image.jpg.

Request parameter

For a request to http://aliyundoc.com/a/b/image.jpg?delete_par=1&modify_par=1, apply three parameter operations: add add_par=1, delete delete_par, and change modify_par to 2. The resulting cache key is http://aliyundoc.com/a/b/image.jpg?modify_par=2&add_par=1.

Important

When multiple operations target the same parameter, the priority order is: Add > Delete > Reserve > Modify.

HTTP headers

To include User-Agent and Accept-Language header values in the cache key: for a request to http://aliyundoc.com/a/b/image.jpg with User-Agent: Mozilla/5.0 (Linux; X11) and Accept-Language: en, the cache key becomes http://aliyundoc.com/a/b/image.jpgMozilla/5.0(Linux;X11)en.

Custom variables

Custom variables extract a value from a request attribute using a regular expression, then append the extracted value to the cache key. In the variable expression, $n refers to the value captured by the n-th capture group in the match rule.

Example 1: Extract from a request header

Variable name: language | Source: Request Header | Source field: Accept-Language | Match rule: ([%w]+),([%w]+) | Variable expression: $1aa

A client requests http://aliyundoc.com/a/b/image.jpg with Accept-Language: en,ch. The match rule captures en as $1. The expression produces enaa, which is appended to the cache key: http://aliyundoc.com/a/b/image.jpgenaa.

In the expression ([%w]+),([%w]+) applied to en,ch: $1 is en and $2 is ch.

Example 2: Extract from a cookie

Variable name: expired | Source: Request Cookie | Source field: a | Match rule: [%w]+:(.*) | Variable expression: $1

A client requests http://aliyundoc.com/a/b/image.jpg with Cookie a=expired_time:12635187. The match rule extracts 12635187 as $1, which is appended to the cache key: http://aliyundoc.com/a/b/image.jpg12635187.

Example 3: Combine a URI rule with a custom variable

URI rule: merge all requests matching /abc/.*/abc to /abc.

Custom variable: name testname | Source: Path | Match rule: /abc/xyz/(.*) | Variable expression: $1

A client requests http://aliyundoc.com/abc/xyz/abc/image.jpg. The URI rule maps it to http://aliyundoc.com/abc/image.jpg. The custom variable then matches /abc/xyz/(.*) against the original URL, captures abc as $1, and appends it. The final cache key is http://aliyundoc.com/abc/image.jpgabc.

If the request does not match the custom variable's rule, the variable is not appended to the cache key.

Example 4: Serve different cache entries for mobile and PC clients

Define two rule conditions:

Mobile: User-Agent contains any of *Mobile*,*Android*,*iPhone*,*ipad*
PC: User-Agent does not contain any of *Mobile*,*Android*,*iPhone*,*ipad*

Then configure two custom cache key rules:

Mobile cache key: Rule condition Mobile | Custom variable: name Mobile, Source Path, Matching rule /, Variable expression +mobile
PC cache key: Rule condition PC | Custom variable: name PC, Source Path, Matching rule /, Variable expression +pc

For a request to http://aliyundoc.com/image.jpg, the cache key resolves to http://aliyundoc.com/image.jpg+mobile for mobile clients and http://aliyundoc.com/image.jpg+pc for PC clients.