服务端模板碎片缓存与前端构建产物缓存必须解耦，因二者层级不同、失效逻辑不同：Webpack/Vite输出的index.[contenthash].html需设no-cache，而碎片若预编译则文件名须含hash，若运行时渲染则应以fs.Stats为Map缓存key，严禁构建工具干预服务端缓存，CDN对/fragments/*.html须设no-store，且碎片缓存键必须包含device等上下文维度。
服务端模板碎片缓存和前端构建产物缓存必须解耦，否则会互相污染——比如 Webpack 生成的 index.[hash].html 被 CDN 缓存了，但里面引用的 header.html 碎片却走的是服务端 Map 缓存，两者生命周期不一致，就必然出现“骨架新、内容旧”或“内容新、骨架旧”的错位。
Webpack/Vite 构建产物缓存和模板碎片缓存怎么不打架
构建工具输出的是静态 HTML 字符串，服务端运行时加载的是动态拼装的碎片，二者缓存层级不同、失效逻辑不同，不能混用同一套 key 或同一套 TTL。
- Webpack 的
html-webpack-plugin输出的index.html必须带[contenthash]，且 Nginx 对它设Cache-Control: no-cache, must-revalidate—— 它是整个链路的锚点，不能强缓存 - 服务端碎片（如
header.html）若被预编译并readFileSync注入，它的文件名也得含 hash；若走运行时编译（如 Marko），缓存应存在Map中，键里不含路径字符串，而用fs.Stats实例作 key，避免查询参数或 Unicode 导致冲突 - 禁止让构建工具去“管理”服务端碎片缓存：比如在
webpack.config.js里写cache.delete('header')，这毫无意义——服务端进程根本看不到 Webpack 的内存
CDN 缓存规则怎么避开模板碎片陷阱
CDN 只认 URL 路径，不理解“碎片”概念。把 /fragments/header.html 暴露给 CDN 是高危操作，尤其当这个路径实际由 Express 路由动态返回时。
- 如果碎片走独立 HTTP 接口（如 HTMX 场景），CDN 必须对
/fragments/*.html显式关闭缓存：Cache-Control: no-store，不能依赖后端响应头——CDN 往往忽略no-cache - 如果碎片是内联进主 HTML 的（
{% include %}或render_partial），CDN 只需管好主页面缓存策略，碎片本身无独立缓存身份，强行给它配规则反而制造混乱 - Nginx 反向代理层若做路径转发，注意不要把
/fragments/转发到静态文件目录——那会绕过服务端上下文判断，导致未登录用户看到已登录版 header
服务端 Map 缓存和前端 localStorage 怎么协同不冲突
前端 JS 有时会把碎片 HTML 存进 localStorage 做离线兜底，但这和后端 Map 缓存完全无关，且极易出问题。
立即学习“前端免费学习笔记（深入）”；
-
localStorage存的是字符串，无法携带服务端上下文（如user.id、region），缓存键只能靠 URL，一旦 URL 含 query 参数（?theme=dark），不同参数会被当成同一 key - 服务端
Map缓存可以自然支持复合 key：map.set({ path: 'header', user: 123, region: 'cn' }, html)；而localStorage只能拼字符串，容易乱码或冲突 - 真正该做的，是让前端只缓存「不可变」的公共资源（如通用 icon SVG），而所有带上下文的碎片，一律交由服务端按粒度隔离缓存，前端只负责请求 + 渲染，不接管存储
最易被忽略的一点：模板碎片缓存键里漏掉 device 或 is_mobile 这类维度，会导致 PC 用户看到移动端布局，或者反过来——这不是构建配置问题，而是服务端缓存设计本身没覆盖真实请求上下文。
