真正稳的方案是让CSS文件名带contenthash并由构建工具自动重写HTML中<link>引用；?v=参数常因构建剥离、CDN忽略查询串或Nginx缓存键未含$args而失效。
加 ?v= 参数不是万能解法，它经常失效——真正稳的方案是让 CSS 文件名本身带 contenthash，由构建工具自动重写 HTML 中的 <link> 引用。
为什么 ?v= 经常不起作用
浏览器确实会把 style.css?v=1 和 style.css?v=2 当作两个资源，但前提是这个 URL 真的发到了服务器。常见断点包括：
- 构建工具（如 Vite 的
build.rollupOptions）默认剥离查询参数，HTML 里写的?v=xxx在产物中被删光了 - Nginx 或 CDN 配置了
proxy_cache_key但没包含$args，?v=1和?v=2被当成同一个缓存键 - Cloudflare 免费版默认勾选 “Ignore query string”，直接忽略所有
?后内容 - 参数加错位置，比如写成
style.css#main?v=1——#后内容根本不会发给服务端
Vite 项目必须配 assetFileNames 才能生成哈希文件名
Vite 默认生产构建不给 CSS 加 hash，你看到的仍是 style.css，CDN 就会一直缓存它。必须在 vite.config.ts 里显式配置：
build: {
rollupOptions: {
output: {
assetFileNames: 'assets/[name].[hash].css'
}
}
}
注意几点：
立即学习“前端免费学习笔记（深入）”；
-
[hash]是 Rollup 的写法，不是 Webpack 的[contenthash] - 如果开启
cssCodeSplit（默认开），还得同时配entryFileNames和chunkFileNames，否则异步加载的 CSS 可能没 hash - HTML 中的
<link>必须由 Vite 自动注入；手写href="style.css"会导致引用和实际文件名不匹配，404 或样式丢失
CSS 里的 @import 不会被自动重写
构建工具能重写 HTML 中的 <link>，但对 CSS 文件内部的 @import "base.css"; 无感。结果就是主 CSS 文件名变了，但 @import 还指向旧路径，浏览器 404 或加载旧版本。
可行解法只有两个：
- 把
@import改成 JS 动态import()，交给构建工具统一处理 - 构建前用脚本把
@import url("xxx.css")替换成相对路径或内联，避免运行时请求
别指望 postcss-import 自动加 hash——它不改 URL 结构，只做内容合并。
上线后必须验证响应头，不能只信配置
即使你配好了 assets/style.a1b2c3d4.css，如果 Nginx 对它返回 Cache-Control: no-cache，浏览器仍可能频繁验证；反之，如果对无 hash 的 style.css 返回了 max-age=31536000，问题会更顽固。
部署后立刻检查真实响应头：
- 打开 DevTools → Network → 刷新 → 点击一个带 hash 的 CSS 文件 → 看 Response Headers
- 正确应为：
Cache-Control: public, max-age=31536000, immutable - 用
curl -I https://yoursite.com/assets/style.a1b2c3d4.css快速确认
最容易被忽略的是：本地开发用 localhost 时，Chrome 对 file:// 协议不发缓存头，线上问题在开发环境根本复现不了。
