开发环境必须禁用HTML缓存,否则修改代码后页面不更新;根本原因是浏览器对index.html默认启用强缓存(如Cache-Control: public, max-age=3600),尤其本地服务未显式配置响应头时,代理或中间件会fallback至保守策略,导致加载磁盘缓存副本而非最新内容。

开发环境必须禁用HTML缓存,否则你改了代码却看不到效果,不是bug是缓存在捣鬼。
为什么开发时HTML总不更新
浏览器对 index.html 默认可能走强缓存(比如 Cache-Control: public, max-age=3600),尤其当本地服务(如 webpack-dev-server、vite dev 或 Nginx)没显式配置响应头时,某些代理或中间件会 fallback 到保守策略。结果就是:你保存了 HTML 模板,刷新页面却还是旧内容——实际加载的是磁盘缓存副本,根本没发请求。
常见现象包括:
- 修改了
<title></title>或内联脚本,刷新后无变化 - 硬刷新(Ctrl+F5)才生效,普通 F5 不行
- Network 面板里 HTML 请求状态码是
200 (from disk cache)或304,但你确定服务器已返回新内容
Webpack Dev Server 禁用 HTML 缓存的实操配置
如果你用 webpack-dev-server + html-webpack-plugin,默认不会给 HTML 响应加缓存头,但某些版本或反向代理(如 nginx 作为前置)可能覆盖行为。最可靠方式是在 dev server 配置中强制注入响应头:
立即学习“前端免费学习笔记(深入)”;
devServer: {
headers: {
'Cache-Control': 'no-store, must-revalidate'
}
}
注意:no-store 比 no-cache 更彻底——它禁止浏览器写入磁盘缓存,连协商缓存都跳过;must-revalidate 是保险项,防止中间代理擅自放宽策略。
额外建议:
- 确保
html-webpack-plugin的cache选项设为false(开发时无需模板快照比对) - 避免在
public/下放静态index.html,否则 webpack-dev-server 可能直接 serve 它而不经插件处理 - 如果用
CopyWebpackPlugin复制 HTML,检查是否意外启用了缓存逻辑
Vite 和其他现代工具链的处理差异
Vite 开发服务器默认就禁用 HTML 缓存,响应头自带 Cache-Control: no-cache。但要注意两个陷阱:
- 如果你在
vite.config.ts中配置了server.headers,且覆盖了Cache-Control,就会失效 - 使用
vite-plugin-html动态注入变量时,若启用其inject缓存(如cache: true),可能导致 HTML 内容未实时更新
推荐显式加固:
export default defineConfig({
server: {
headers: {
'Cache-Control': 'no-store'
}
}
})
另外,SvelteKit、Next.js(dev 模式)、Remix 等框架的 dev server 同样默认禁用 HTML 缓存,但一旦你加了自定义中间件(如 Express 封装),就得手动补上响应头。
本地 Nginx / Apache 代理场景下的绕过方案
很多团队用 Nginx 代理到 localhost:3000,这时 Nginx 可能按自身规则缓存 HTML。即使后端禁用了,Nginx 仍可能缓存 1 分钟以上。
解决方法是在 Nginx 的 location 块中明确覆盖:
location = /index.html {
add_header Cache-Control "no-store";
proxy_pass http://localhost:3000;
}
关键点:
- 必须用
location = /index.html精确匹配,不能用正则或前缀匹配,否则不生效 -
add_header在 Nginx 中默认不覆盖已有头,需确认未被其他模块(如headers-more-nginx-module)干扰 - 如果代理的是整个路径(如
/),还要排除所有 HTML 路由:location ~ \.html$ { ... }
Apache 同理,在 .htaccess 或虚拟主机配置中加入:
<Files "index.html"> Header set Cache-Control "no-store" </Files>
真正麻烦的从来不是“怎么配”,而是“谁在偷偷加缓存”——可能是公司统一网关、CI/CD 构建产物自动注入的头、甚至浏览器扩展。开发阶段务必打开 Network → Headers,逐个确认 index.html 响应里的 Cache-Control 和 ETag 字段是否符合预期。



















