HTML模板与前端构建缓存与组件更新策略-html教程-PHP中文网

必须用 map，不是推荐而是硬性要求；对象字面量会因查询参数、unicode 等导致键名失真而静默失效，map 支持任意类型键且提供 size/clear 等可靠操作。

html模板与前端构建缓存与组件更新策略

服务端模板碎片缓存该用 Map 还是对象字面量

必须用 Map，不是“推荐”，是硬性要求。对象字面量（{}）在服务端模板缓存场景下会 silently 失效——尤其当碎片路径含查询参数、Unicode 字符或动态构造键时。

常见错误现象：cache['header.html?theme=dark'] 和 cache['header.html?theme=light'] 被归为同一 key；或者 cache[filePath] 中 filePath 是 /fragments/用户信息.html，toString 后变成乱码键名，查不到缓存。

Map 支持任意类型键：可直接用 fs.Stats 实例、URL 对象甚至自定义类作 key，避免字符串化失真
Marko 编译器源码里明确用 new Map() 存模板编译结果，不是巧合
Map.size 和 Map.clear() 可用于构建阶段统计命中率或精准清理，对象字面量无法可靠遍历插入顺序
仅在标签库加载等极少数场景下，{} 可接受——前提是路径绝对、无参、ASCII-only（如 packages/compiler/src/taglib/loader/cache.js）

Django/Jinja2 中碎片缓存控制点在哪

不在模板语法里，也不在 {% include %} 参数中——Jinja2 和 Django 的 include 标签根本不解析 HTTP 缓存指令。真正能干预的地方只有三处：视图响应头、反向代理规则、数据层缓存。

典型错误：给 fragments/user_card.html 加 {% cache 60 "user_card" %}，但没考虑 user.is_authenticated 或 request.GET.q 导致缓存污染；或在 Nginx 里对 /fragments/*.html 统一设 max-age=3600，却忘了这些碎片可能读取 session 数据。

anything-to-html

将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。

下载

HTMX 请求必须显式设响应头：response['Cache-Control'] = 'no-cache'（Django）或 res.set('Cache-Control', 'no-cache')（Express），不能依赖中间件全局配置
完全静态碎片（如页脚）才适合 Nginx 路径级缓存：add_header Cache-Control "public, max-age=3600"，且需确保不读 request 对象
含数据库查询的碎片，应缓存数据而非 HTML：@cache_page(60) 包裹查询逻辑，而不是整个 render()
不要在模板里写 {% if request.headers.get('HX-Request') %}——Jinja2 不暴露请求头，这个判断永远 false

HTML 文件本身怎么避免缓存错乱

HTML 是应用外壳（App Shell），必须每次加载都最新，不能靠 Cache-Control: no-cache 混过去。浏览器 HTTP 缓存层和 Service Worker 缓存层互不感知，改了 HTML 源码但没动 SW，用户就卡在旧结构里。

常见错误现象：发版后页面 class 名变了，但用户打开仍是旧 DOM；Service Worker 报 TypeError: Failed to execute 'put' on 'Cache' ——旧 SW 正在用同名缓存，新 SW 写冲突。

Service Worker 的 cacheName 必须带版本号，如 pages-v2.1.0，不能写死为 pages
install 阶段显式 cache.addAll(['/index.html', '/offline.html'])，确保 HTML 进入新缓存桶
activate 阶段只清理非当前列表的缓存：caches.keys().then(keys => Promise.all(keys.map(key => !CURRENT_CACHES.includes(key) && caches.delete(key))))
HTML 动态生成（如 SSR）不能预缓存，得在 fetch 事件中拦截并 cache.put()，且响应头要设 Vary: Cookie 等维度

Webpack 构建时如何让碎片 HTML 不被缓存错乱

html-webpack-plugin 预生成的碎片文件（如 dist/fragments/header.html）本质是静态资源，缓存问题退化为文件名哈希是否生效。关键不是插件开关，而是 filename 模板里有没有 [contenthash]。

常见错误：开了 cache: false，以为能禁用构建缓存，结果输出文件名还是 header.html，浏览器复用旧副本；或用 [hash] 而非 [contenthash]，导致 JS 修改也触发 header.html 重命名，浪费 CDN 带宽。

必须用 filename: '[name].[contenthash].html'，确保内容不变则文件名不变，内容变则文件名变
碎片 HTML 被服务端 readFileSync 注入主模板时，服务端也要同步更新引用路径——不能硬编码 fragments/header.html，得读取 rev-manifest.json 映射
若碎片由 HTMX 异步加载，还需在 Nginx 中关闭对应路径缓存：location /fragments/ { add_header Cache-Control "no-store"; }
Gulp 场景下，gulp-rev-collector 必须匹配到 rev/**/*.json 和真实 HTML 路径，否则替换失败，版本号留在注释里没人读