最有效的方式是构建时生成带内容哈希的文件名（如app.a1b2c3.js），使URL随内容自动变化，浏览器视为新资源加载；配合Nginx对静态资源设public, immutable长缓存，HTML禁用缓存，并通过插件自动注入哈希路径。

最有效的方式不是靠“动态加版本号”，而是让版本号随内容自动变化——也就是构建时生成带内容哈希的文件名（如 app.a1b2c3.js、style.d4e5f6.css）。这样每次代码一改，文件名就变，浏览器自然当它是新资源加载，彻底绕过旧缓存导致的样式错乱或功能异常。

为什么手动加?v=时间戳或?v=1.2.0不推荐

这类查询参数看似简单，实际在生产环境容易失效：

• CDN 或公司级反向代理常忽略 URL 中的查询参数，仍返回旧缓存
• 浏览器可能复用带不同参数但相同主体的缓存（尤其在 HTTP/2 下）
• 运维发布时需人工同步修改 HTML 和版本号，易漏、易错、难审计
• 即使参数变了，服务器返回的仍是同一份文件，无法保证内容真实更新

推荐做法：构建阶段自动生成哈希文件名

现代前端工具（Webpack/Vite/ESBuild）默认支持 contenthash，只需配置输出规则：

• Webpack：在 output.filename 中设为 [name].[contenthash:8].js
• Vite：启用 build.rollupOptions.output.entryFileNames 并含 [hash]
• HTML 中引用由插件（如 HtmlWebpackPlugin）自动注入，无需手写路径

这样，main.js 变成 main.7f8a9b2c.js，只要内容有改动，哈希就变，URL 就不同。

HISUI 前端框架开发指南（IRIS版）

HISUI 前端框架基础开发指南。HISUI 是基于 easyui 二次开发的 jQuery UI 组件库，专为医疗信息系统设计。当涉及 HISUI 组件开发、jQuery easyui 表格/表单/布局/窗口、医疗系统前端页面编写时使用此 skill。 涵盖 40 个组件的官方文档参考，支持声明式与编程式两种初始化方式，提供 $cm/$m 数据访问方法。

下载

立即学习“前端免费学习笔记（深入）”；

Nginx 配置要配合哈希策略

一旦用了哈希文件名，Nginx 就可以放心设长缓存，且加上关键标识：

• 匹配所有哈希静态资源：location ~* \.(js|css|png|jpg|gif|woff2?)$
• 设置超长有效期：expires 1y;
• 添加强缓存头：add_header Cache-Control "public, immutable";
• immutable 告诉浏览器：“这文件一年内绝不会变”，跳过验证请求，既快又稳

特别注意 HTML 文件不能缓存太久

HTML 是入口，它本身不带哈希，必须确保用户每次访问都能拿到最新版（含最新 JS/CSS 链接）：

• 对 .html 单独配置：location ~* \.html$ { add_header Cache-Control "no-cache, must-revalidate"; }
• 或更严格：add_header Cache-Control "no-store, must-revalidate";
• 避免 CDN 对 HTML 缓存，需在 CDN 后台将 *.html 设为“不缓存”或“缓存 1 分钟”

上线后必须验证响应头

光配了没用，得看浏览器实际收到什么：

• 打开 DevTools → Network → 刷新 → 点开一个 .js 或 .css 请求
• 确认 Response Headers 中有：Cache-Control: public, immutable 且 max-age=31536000
• 点开一个 .html 请求，确认是 no-cache 或 no-store，状态码应为 200（非 304）
• 用 curl -I https://yoursite.com/app.abc123.js 快速检查