改完的网页半天不更新？调一下 CDN 刷新让它立刻生效

网站套了 CDN 加速之后，用户访问的是离他最近的边缘节点，速度确实快。但有个麻烦也跟着来了：你明明在源站把 index.html、app.js 改了，用户刷新却还是旧页面。原因是边缘节点上还存着旧缓存，没到期不会主动回源。等它自己过期往往要按小时算，急着生效就只能手动"刷新"。华为云 CDN 提供刷新和预热接口，调一下几分钟就让边缘节点更新或提前拉好内容。

一、先搞清楚刷新和预热是两件事

刷新（Refresh）是让边缘节点上已有的缓存立刻失效，下次有人访问再回源拉新内容。适合"我已经改完源站，赶紧让旧缓存作废"。预热（Preheat）是反过来，主动把源站内容提前推到边缘节点，用户第一次访问就直接命中、不用等回源。适合"大促前要放的新活动页，提前铺到节点上"。

一个是清旧，一个是铺新，别搞反。日常改完代码发布，用刷新就够了；上新内容又怕第一波流量打爆源站，才用预热。

二、用 KooCLI 一条命令刷新

华为云命令行工具 KooCLI 把 CDN 刷新接口包成了现成命令，不用自己拼签名。刷新一个文件：

hcloud CDN CreateRefreshTasks/v2 \
  --type file \
  --urls '["https://www.example.com/index.html","https://www.example.com/app.js"]'

type 可选 file（按文件）或 directory（按目录）。按目录刷新的写法是把目录 URL 传进去，该目录下全部缓存作废，适合一次性改了一堆静态资源。返回里会带一个任务 ID，拿它去查进度。

三、用接口在代码里自动刷

发布流水线里，更希望"构建完自动刷新"，而不是人工敲命令。CDN 刷新是 REST 接口，用任意语言都能调。核心是把任务提交到刷新接口，带鉴权头：

import os, requests, json

REGION = os.environ["HW_REGION"]
TOKEN  = os.environ["HW_TOKEN"]      # AK/SK 换取的临时凭证
URL    = f"https://cdn.myhuaweicloud.com/v1.0/cdn/refreshtasks"

body = {
    "refresh_task": {
        "type": "file",
        "urls": [
            "https://www.example.com/index.html",
            "https://www.example.com/app.js",
        ],
    }
}
resp = requests.post(URL, json=body,
                     headers={"X-Auth-Token": TOKEN,
                               "Content-Type": "application/json"})
task_id = resp.json().get("refresh_task")
print("刷新任务已提交:", task_id)

提交成功只代表任务进了队列，真正生效要等边缘节点逐个失效，通常几分钟。想确认哪条成了，用查询接口按 task_id 拉结果。生产里建议把"要刷新的 URL 清单"做成配置，发布脚本读清单批量提交。

四、容易踩的几个坑

第一，刷新有配额和频率限制，全量刷整站很浪费额度，尽量只刷改动的文件，改一个 JS 就别把整站目录都刷一遍。第二，目录刷新会作废目录下所有缓存，范围大、回源压力大，非必要不用。第三，刷新不是瞬间全局生效，边缘节点多、同步要时间，别提交完立刻断言"用户一定看到新版"，给几分钟余量。第四，缓存时间设为 0 的资源不允许预热，预热前确认源站资源过期时间大于 0。第五，大批量预热会占满源站带宽，要分批次、错开执行。第六，鉴权凭据走环境变量或凭据管理，别写进脚本提交仓库。

五、小结

CDN 让访问变快，但改完源站不刷新就会"用户看到旧版"。刷新是让旧缓存失效、预热是提前铺新内容，日常发布用刷新即可。KooCLI 一条命令 hcloud CDN CreateRefreshTasks/v2 就能提交，代码里用 REST 接口 POST /v1.0/cdn/refreshtasks 把改动文件清单批量提交进发布流水线最省心。记住只刷改动文件、留几分钟生效余量、凭据别入库，这套配合就能做到"改完立刻让用户看到新版"。端点、字段、配额以华为云官方文档为准。