CDN忽略?v=参数导致缓存不更新，因未将查询字符串纳入缓存键；应关闭CDN“忽略查询参数”设置、Nginx配置proxy_cache_key包含$args，并优先采用文件名哈希+强缓存策略。
CDN忽略?v=参数导致缓存不更新
你改了 CSS 文件、加了 v=1.2.3，但用户还是看到旧样式——大概率是 CDN（比如旧版 Cloudflare 免费计划）或 Nginx 反向代理没把查询参数算进缓存键里。它把 style.css?v=1.2.3 和 style.css?v=1.2.4 当成同一个 URL 缓存了。
验证方法：打开 DevTools → Network → 找到那个 CSS 请求，看响应头：X-Cache: HIT 且 Age 很大（比如几百秒），说明缓存来自 CDN，不是浏览器。
- Cloudflare：检查「Cache Rules」是否勾选了「Ignore query string」，关掉它
- Nginx：确认
proxy_cache_key包含$args，正确写法是proxy_cache_key "$scheme$request_method$host$request_uri$args"; - SCDN 或其他私有 CDN：查控制台缓存配置项，找“是否区分查询参数”或“query string cache policy”
浏览器强缓存 + CDN 长缓存双重锁死
前端只加 v= 参数，服务端却返回 Cache-Control: public, max-age=31536000，等于告诉浏览器和 CDN：“这个文件一年内别来问”。一旦 CDN 缓存命中，v= 就彻底失效。
生产环境真正可靠的组合是：文件名哈希 + 强缓存头，而不是依赖查询参数。
立即学习“前端免费学习笔记（深入）”；
- Webpack/Vite 构建时开启
contenthash，输出类似style.a1b2c3.css - HTML 中引用该带哈希的文件名，URL 变了，天然绕过所有层级缓存
- 同时配
Cache-Control: public, max-age=31536000，让 CDN 和浏览器都长期缓存 - 如果必须用
v=（比如 CMS 不支持改文件名），至少把服务端缓存时间设短些，例如max-age=3600
CDN 节点未全量刷新或地域性缓存不一致
你在华东节点看到新样式，华北用户还是旧的——这不是代码问题，是 CDN 边缘节点没同步更新，或者部分节点缓存过期策略不同步。
不要等自然过期，主动触发刷新：
- 登录 CDN 控制台，对 CSS 文件路径（如
/static/css/*.css）执行「缓存刷新」或「预热」 - 注意：有些 CDN 刷新是异步的，可能需几分钟才全网生效
- 若用多个 CDN（比如主用 jsDelivr，备用 BootCDN），确保两边都刷新，否则 fallback 会加载旧版本
- 避免用通配符过度刷新（如
/*），可能触发风控限频
本地开发没问题，上线后失效的典型链路断点
本地 localhost 直接跑 HTML 没问题，一上 CDN 就卡在旧样式，说明问题出在中间层，不是代码本身。
排查顺序要倒着来：
- 先看浏览器 Network 面板，确认请求发出的 URL 是带
v=的，且状态码是200（不是304） - 再看响应头里的
Cache-Control、Expires、X-Cache，判断是哪一层（浏览器 / CDN / 源站）在缓存 - curl 命令直连 CDN 域名验证：
curl -I https://cdn.example.com/style.css?v=1.2.3，观察Age和X-Cache - 最后检查源站是否被 CDN 回源时缓存了旧文件（比如 Nginx
proxy_cache_valid设得太宽）
最常被忽略的是：你以为 CDN 在缓存，其实源站返回了 Cache-Control: no-cache，CDN 就不敢缓；或者源站返回了 private，CDN 默认不缓存。这类响应头优先级高于 CDN 控制台设置。
