CDN:Configure CDN cache expiration time

How it works

When a request reaches a CDN point of presence (POP), the system decides whether to serve a cached copy or fetch the latest content from the origin server. The following steps are evaluated in priority order, and a lower number indicates a higher priority.

1. Origin no-cache directives — CDN does not cache a resource if the origin server responds with Pragma: no-cache, Cache-Control: no-cache, Cache-Control: no-store, or Cache-Control: max-age=0. To force caching for these resources, select Ignore Origin No-Cache Header when you configure the cache expiration rule.

2. Cache rules configured in the console — Cache rules configured in the CDN console take precedence, unless the origin server explicitly sends a no-cache directive as described in step 1. When multiple console cache rules match a request, the rule with the higher weight takes precedence, and rules with the same weight are resolved by creation order. Once a request matches a cache rule, no other rules are evaluated.

3. Origin response headers — 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.

4. Default no-cache policy — If a request does not match any cache rule in the CDN console and the origin server does not return cache response headers such as Cache-Control, CDN applies a no-cache policy.

5. 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 configure the expiration time of status codes such as 404, use the Cache Settings > Status Code TTL page.

The following table describes the priority logic when multiple console cache rules match a request:

The following table describes how each origin response header is handled:

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.jpg and /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 an exact match on the extension. 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, html

  • Font file extensions: ttf, otf, woff, woff2, eot

  • Dynamic page extensions: php, aspx, jsp

  • Any 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 How it works.

• 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 as ttf,otf,woff,woff2,eot.

Procedure

Apply rule changes immediately

To apply new rules network-wide immediately, you must manually clear the existing cache. If you change a rule, purge the existing cache by using the Purge and prefetch resources feature. If you add a new rule, prefetch the resource by using the prefetch resource feature.

Verification

After you complete the configuration, use the curl command or browser developer tools to inspect the HTTP response headers of a resource and verify that caching works as expected. For details about when a rule change takes effect, see Apply rule changes immediately.

curl -I "https://your.domain.com/path/to/file.jpg"

Best practices

• Use versioned filenames (recommended) — When you update a static resource such as style.css, use a new filename with a version or hash, such as style-v2.css or style-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.

• Effectively use the browser cache — Enable Follow POP 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.

• Game industry and 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. (Recommended) Use thepurge and prefetch feature to proactively refresh the cache when content is updated.

• robots.txt and sitemap.xml — These files directly affect search engine crawling. Configure their cache duration separately to prevent them from being matched by a broad extension rule that caches them for too long, which would delay updates. (Recommended) To target only these two files, select Directory as the type, enter the specific file path (such as /robots.txt) in the Object field, and then set a high weight to override broad extension rules. If you prefer to configure by file extension, set a cache duration of 1 hour to 1 day for the txt,xml extensions. An extension rule applies to every resource with those extensions, not only to robots.txt and sitemap.xml. For frequently updated sitemaps, set the cache duration to no more than 1 hour.

Troubleshooting

For how to troubleshoot caching not taking effect, cache misses, a low cache hit rate, and content not being updated, see Troubleshoot cache issues.

Appendix: HTTP cache control mechanisms

This section provides protocol background. For the corresponding cache behavior on POPs, see How it works. The HTTP protocol uses three types of headers for cache control:

1. Expiration time validation

   When a client requests a resource from a server, both parties agree on an expiration time for the resource. Before this time, the cached copy is considered valid. After this time, the cached copy becomes invalid.

   In HTTP, the following headers are commonly used to control cache expiration:

   Header	Protocol version	Description	Example	Type
   Pragma	HTTP/1.0	Indicates whether the content should be cached. Its value is typically no-cache, meaning the file should not be cached. It is often used for compatibility with servers that support only the HTTP/1.0 protocol.	Pragma: no-cache	Request/Response
   Expires	HTTP/1.0	The Expires response header specifies the date and time when the cached content becomes stale. If an invalid date is used, such as 0, it means the resource has already expired.	Expires: Wed, 21 Oct 2022 07:28:00 GMT	Response
   Cache-Control	HTTP/1.1	The Cache-Control response header provides flexible cache control through various directives and is the primary header that modern clients, like browsers, use for this purpose.	The following three examples indicate that the file should not be cached: Cache-Control: no-cache; Cache-Control: no-store; Cache-Control: max-age=0. Example of a 1-hour cache validity period: Cache-Control: max-age=3600.	Request/Response

2. Resource tag validation

   The server includes a resource tag (such as an ETag) in its initial response. When the client requests the same resource again, it sends this tag back to the server for validation. If the resource is unchanged, the server responds with an HTTP status code of 304, allowing the client to use its cached copy. If the resource has changed, the server sends the new content.

   In HTTP, the following headers are commonly used to control cache versions:

   Header	Protocol version	Description	Example	Type
   Last-Modified	HTTP/1.0	Indicates the last modification time of the resource.	Last-Modified: Wed, 21 Oct 2015 07:28:00 GMT	Response
   ETag	HTTP/1.1	Provides a unique identifier for a specific version of a resource. Comparing ETags can determine if a resource has changed. If it has not, the origin server does not need to send a full response.	ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"	Response

3. Content negotiation

   Caching software uses a keyword to index objects cached on disk. In HTTP/1.0, the resource URL is used as the keyword. However, different representations of a resource can exist at the same URL. To distinguish them, more information is needed from the client, such as the Accept-Language and Accept-Charset headers. To support content negotiation, HTTP/1.1 introduced the Vary header in the response message. This header lists which request headers are required for content negotiation.

   Content negotiation typically uses the HTTP Vary header to differentiate between different cached copies, allowing different clients to receive different cached copies when requesting the same resource: