By configuring cache expiration rules, you can control the cache duration for resources on CDN points of presence (POPs) to balance content freshness, access performance, and origin fetch costs. This document explains how to configure and validate cache rules, provides troubleshooting guidance, and outlines best practices.
How it works
When a request reaches a CDN point of presence (POP), the system uses the following prioritized process to decide whether to serve a cached copy or fetch the latest content from the origin server.
CDN does not cache resources if the origin server responds with
pragma:no-cache,cache-control:no-cache(orno-store, ormax-age=0).Cache rules configured in the CDN console take precedence, unless the origin server explicitly sends a no-cache directive as described above.
Priority logic when multiple console cache rules match a request:
Scenario
Priority logic
Example
Different weights
The rule with the higher weight (1-99) takes precedence.
Rule A (directory
/image/, weight 50) and Rule B (file extension.jpg, weight 90) both matchimage/a.jpg. Rule B takes effect because it has a higher weight.Same weight
The earliest created rule takes precedence.
You configure a directory rule (
/static/) and a file extension rule (.js) for a domain name, both with a weight of 60. If the directory rule was created before the file extension rule, a request for/static/app.jsmatches the directory rule.Once a request matches a cache rule, no other rules are evaluated.
By default, if the origin server responds with
Pragma: no-cacheorCache-Control: no-cache/no-store/max-age=0, the CDN POP does not cache the resource. To force caching, select Ignore Origin No-Cache Header when you configure the cache expiration rule.
CDN honors the origin server's HTTP response headers if a request does not match any CDN console rule, or if the matched rule has Honor Origin TTL enabled. Header priority, from highest to lowest, is as follows:
cache-control>expires>last-modified>ETag.Response header
CDN handling
Notes and examples
Cache-Control
Uses
s-maxage(CDN cache duration) first, and thenmax-age.Example:
s-maxage=86400, max-age=3600Expires
Specifies the expiration time. This is used only if no
Cache-Controlheader is present.Example:
Expires: Wed, 21 Oct 2025 07:28:00 GMTLast-Modified
The
Last-Modifiedheader is a timestamp that indicates when the resource was last modified.The cache duration is calculated as follows:
(Current Time -
last-modified) × 0.1. The calculated duration is then capped between a minimum of 10 seconds and a maximum of 3,600 seconds.Example:
Last-Modified: Wed, 21 Oct 2023 07:28:00 GMTETag
An
ETagis a unique identifier generated by the server for a specific version of a resource, typically a hash or version number.By default, a resource with an
ETagis cached for 10 seconds.Example:
ETag: "abc123"CDN no-cache policy: If a request does not match any cache rules in the CDN console and the origin server does not return cache response headers such as
Cache-Control, then CDN applies a no-cache policy.
CDN applies cache policies only to requests for which the origin server returns a status code of 200, 203, 206, 300, 301, 308, or 410. To cache requests with other status codes, such as 404, you must configure this behavior on the Cache Configuration > Status Code Expiration.
Procedure
Console (recommended)
In the CDN console, go to the Domain Names page and click Manage next to the target domain name.
On the Cache > Cache Expiration page, click Add to configure a cache rule.
Parameter
Description
Default/example
Type
Specify the scope of the rule by Directory or File Extension.
• Directory: Sets a uniform cache rule for all resources under a path.
• File Extension: Sets a uniform cache rule for files of a specific type.Directory, File Extension
Object
Enter a value based on the selected type:
• Directory: Must start with a forward slash (/), for example,/static/. A single forward slash (/) matches all paths. You can add only one directory at a time.
• File Extension: Enter one or more file extensions, separated by commas, for example,jpg,png,css. The entries are case-sensitive and do not support the vertical bar (|) or other symbols./static/,jpg,png,cssExpire In
The cache duration for resources on POPs. The maximum duration is three years.
• For rarely updated static resources (e.g., images, installers), set a duration of ≥ 1 month.
• For frequently updated static resources (e.g., JS/CSS files), set a shorter duration, such as 1 to 7 days.
• For dynamic content (e.g., PHP/JSP pages), set the duration to 0 seconds (no cache).0 seconds to 3 years
Honor Origin TTL
This is disabled by default. If enabled, the cache policy of the origin server takes precedence and overrides this rule.
Off
Ignore Origin No-Cache Header
If enabled, CDN ignores the following no-cache directives from the origin server:
Cache-Control: no-store,no-cache, ormax-age=0, andPragma: no-cache. Resources are cached according to the console rule.Off
Follow POP Cache Policy
If enabled, CDN returns its effective cache policy, such as
max-age=3600, to the client in the response header.Off
Force Revalidation
This setting is effective only when the expiration time is set to 0 seconds.
• Disabled (default, equivalent to theno-storecache policy): The POP does not cache the file, and every request must be forwarded to the origin server to fetch the content.
• Enabled (equivalent to theno-cachecache policy): The POP caches the file, but every request must be revalidated with the origin server by using the 304 mechanism. This is useful for scenarios that require real-time validation but also need to reduce bandwidth pressure on the origin server.Off
Weight
The priority of the rule. The value can range from 1 to 99, where a higher value indicates a higher priority. When multiple rules match the same resource, the rule with the higher weight takes precedence. If the weights are the same, the rule that was created first takes precedence. We recommend setting a high weight for specific paths or file extensions and a low weight for the root directory (
/) to achieve fine-grained control.1 to 99
Rule Condition
Further refine the rule's scope based on request parameters such as headers and URL parameters. This is not used by default. To configure conditions, use the Rule Engine. When rule conditions are referenced, they are matched based on the priority of the associated conditions, not the configuration order of the feature itself.
Do not use
Cache rule matching logic
CDN cache expiration rules support two rule types with different matching behaviors:
Directory: Uses path prefix matching. For example, configuring
/static/matches all resources under that directory (such as/static/image/1.jpgand/static/css/style.css). Configuring/matches all paths. The directory path must start with a forward slash (/). Each rule supports only one directory.File Extension: Uses exact extension matching. Enter extensions without dots, and separate multiple extensions with commas (for example,
jpg,css,js). Extensions support alphanumeric characters only, with no restriction on specific extension types. The following types can all be configured:Common static resource extensions:
jpg,png,gif,css,js,htmlFont file extensions:
ttf,otf,woff,woff2,eotDynamic page extensions:
php,aspx,jspAny other alphanumeric extension
Note the following about cache rule matching:
When multiple cache rules match the same request (for example, a directory rule and a file extension rule), the rule with the higher Weight takes precedence. Rules with equal weights are resolved by creation order (earlier rule wins). For details, see the "How it works" section above.
If you associate a rule condition (configured in the Rule Engine) with a cache rule, multiple conditions use AND logic — the request must satisfy all conditions to match.
If you set a blanket no-cache rule for all dynamic extensions (such as
aspx), make sure it does not affect static resources you intend to cache. To cache font files, add a dedicated rule with extensions such asttf,otf,woff,woff2,eot.
API
Call the BatchSetCdnDomainConfig API operation to configure multiple domain names in batches. For more information about how to configure parameters for other features, see Domain name configuration functions.
Apply rule changes immediately
New or modified rules apply only to newly cached resources. Previously cached resources continue to use the old cache policy until they expire.
To apply new rules network-wide immediately, you must manually clear the existing cache. If you change a rule, perform a purge operation by using the Purge and Prefetch resources feature. If you add a new rule, perform a prefetch operation by using the prefetch resource feature.
Verification
After you complete the configuration, you can use the curl command or browser developer tools to inspect the HTTP response headers of a resource to verify that caching is working as expected.
1. Run the verification command
Run the following command in your terminal to test the configuration.
curl -I "https://your.domain.com/path/to/file.jpg"2. Interpret key response headers
Response header | Description |
| Indicates whether the request hit the CDN cache. |
| After you enable "Client Follows CDN Cache Policy", this header displays the caching directive that CDN passes to the browser, such as |
| The total configured cache duration for the resource on the POP, in seconds. |
Best practices
Use versioned filenames (recommended): When you update a static resource like
style.css, use a new filename with a version or hash, such asstyle-v2.cssorstyle-a1b2c3d.css, and update the reference in your HTML. This method ensures that users receive the latest content immediately without requiring a manual CDN cache purge and is the recommended way to update cached content.Implement dynamic and static content separation: Use different domain names or directory paths for dynamic and static resources. Configure separate, high-weight cache rules for each to avoid policy conflicts. For example, set a long cache duration for all resources in the
/static/directory and no cache for resources in the/api/directory.Effectively use the browser cache: Enable "Client follows CDN cache policy" to reduce repeated requests to CDN, improve loading speed, and save CDN traffic.
Avoid excessively short cache durations: A short cache duration causes CDN to perform frequent origin fetches, which negates the benefits of acceleration and increases your origin server's traffic and costs.
Be cautious with long cache durations: A long cache duration can prevent clients from receiving timely content updates. For content that needs frequent updates, make sure to purge the cache or use versioned filenames.
Small file scenarios: For small file resources in the game industry (such as configuration files and asset packages) that are updated infrequently (for example, weekly or biweekly), set the cache expiration time to 15 days or match it to the actual resource update cycle. This balances update speed and acceleration performance. A cache duration that is too short leads to frequent origin fetches and reduces acceleration benefits; one that is too long may serve stale content to players. We recommend using the purge and prefetch feature to proactively refresh the cache when content is updated.
HTTP cache control mechanisms
The HTTP protocol uses three types of headers for cache control: