CDN Cache Refresh Strategies in Practice – Static Resource Versioning vs Directory Purge

Overview

The key to cdn acceleration is caching. But if cache updates are not timely, users may see old content. There are two common solutions: adding version numbers (or hashes) to static resources, and manually/CDN API purging directories.

This article analyzes the pros and cons of both strategies and provides practical recommendations.

I. Why Is Cache Refresh Needed?

CDN nodes cache static files (CSS, JS, images) to accelerate access. The default cache time can be several days. When you update a file, the CDN edge node may still keep the old version, causing users to see incorrect styles or functional anomalies.

II. Strategy 1: Version Number / Hashed Filename

Principle: Change the filename when modifying a file, e.g., style.css → style.v2.css or style.8a3f2.css. The HTML references the new filename, and the CDN treats it as a new file, so it won't read the old cache.

Pros:

• No need to actively refresh CDN cache.
• Can use old and new versions simultaneously without affecting online users.
• Suitable for front-end/back-end separation or build tools (webpack, vite automatically add hash).

Cons:

• Need to modify links in HTML (can be automatically replaced by build tools).
• If the HTML itself is also cached by CDN, other strategies need to be coordinated.

III. Strategy 2: CDN Directory / URL Purge

Principle: Submit a refresh request through the CDN management console or API to force CDN nodes to invalidate specified files or directories.

Pros:

• No need to change filenames; HTML content remains unchanged.
• Suitable for content management systems (such as WordPress) that dynamically generate pages.

Cons:

• Slightly cumbersome to operate (can be automated via API).
• Refresh has latency (tens of seconds to a few minutes).
• Some CDNs have limits on the number of refreshes.

IV. Practical Combined Strategy

For most websites, a hybrid approach is recommended:

• **CSS, JS, fonts, and other static resources**: Use versioning or hash-based builds (webpack's output filename with `[contenthash]`).
• **Images, videos, and other media files**: Generally not updated frequently, no special handling needed. If updated, refresh the file URL individually or use a new filename.
• **HTML pages**: If pages also go through CDN, it is recommended to set a shorter cache time (e.g., 5 minutes), or use the CDN cache refresh API to actively trigger on publish.

For dynamic websites like WordPress, you can use CDN plugins (such as the Upyun WordPress plugin) to refresh automatically.

V. Example: WordPress + Upyun Automatic Refresh

1. Install the Upyun WordPress plugin.
2. Configure the CDN domain and API key.
3. Enable "Refresh CDN cache when publishing posts".
4. In the theme, use version numbers for CSS/JS files (e.g., style.css?ver=1.0.1 or directly use the file version function filemtime).

Code example:

<link rel="stylesheet" href="<?php echo get_stylesheet_directory_uri(); ?>/style.css?ver=<?php echo filemtime(get_stylesheet_directory() . '/style.css'); ?>">

This way, after the file is modified, the URL changes, and the CDN automatically goes back to the origin to fetch the new file.

VI. Summary and Recommendations

• Small personal sites: Manual refresh or waiting for cache expiration is sufficient; there is no need for over-engineering.
• Corporate sites or frequently updated sites: Adopt a versioning strategy + API refresh of HTML pages on publish.
• Using the CDN console: Familiarize yourself with whether your CDN provides batch directory refresh; most Chinese CDNs support it.