SSR模板碎片化缓存必须严格区分可缓存与不可缓存边界，安全片段需完全静态、无用户上下文、不依赖请求变量；缓存键须包含locale、设备类型、AB分组、权限等级等维度；需动态注入ID前缀避免hydration冲突，并关闭CDN的HTML自动优化功能。
服务端渲染（SSR）中，HTML模板碎片化缓存不是“多缓存几块就更快”，而是必须严格区分可缓存片段与不可缓存边界——否则极易导致 CSRF token 错乱、用户态混用、动态 ID 冲突等静默故障。
哪些模板片段能安全缓存？
可缓存的前提是：内容完全静态、无用户上下文、不依赖请求时变量（如 req.User.ID、time.Now()、CSRF token）。常见安全片段包括：
- 通用页头/页脚 HTML（不含登录状态按钮）
- 产品卡片结构（仅含
product.Name、product.Price等只读字段） - 帮助文档段落（纯 Markdown 渲染后 HTML，无 session 数据）
- 带哈希的资源引用：
<link href="/css/main.a1b2c3.css">
一旦片段含 {{.CurrentUser.Name}} 或 {{.Nonce}}，哪怕只占一行，整个片段就必须禁用缓存。浏览器或 CDN 缓存该片段后，下次渲染可能把 A 用户的昵称塞进 B 用户的页面里。
碎片缓存必须绑定请求上下文键
不能只按模板文件名缓存（如 "header.templ"），而要构造带签名的缓存键，包含所有影响输出的变量维度：
立即学习“前端免费学习笔记（深入）”；
- 当前 locale（
zh-CN/en-US） - 设备类型（
desktop/mobile，影响<picture>候选集） - AB 实验分组（
exp=checkout-v2） - 权限等级（
role=guest/role=admin）
错误示例：cache.Get("header") → 所有用户拿到同一份 HTML；正确做法：cache.Get("header:zh-CN:mobile:guest")。Go 的 templ 引擎本身不处理键生成，需在调用层拼接。
如何避免 hydration 时 DOM ID 冲突？
SSR 输出的碎片若含 id="modal-root"，客户端 JS 动态插入同名碎片会触发 document.getElementById 返回首个节点——造成事件绑定错位、焦点丢失。解决方案不是删 ID，而是动态注入前重写：
- 服务端渲染时，对每个碎片加唯一前缀：
id="{{.FragmentID}}-modal-root" - 客户端 hydrate 前，用
document.querySelectorAll('[id^="fragment-"]')批量重写 ID，再挂载逻辑 - 绝对不要在模板里写固定
id="sidebar"—— 即使它看起来“不会重复”
这个细节在微服务聚合场景下尤其致命：订单服务、用户服务、推荐服务各自返回带 id="loading" 的碎片，合并后只剩一个生效。
CDN 缓存碎片时必须关闭 HTML 自动修正
Cloudflare、阿里云 CDN 默认开启“HTML 自动优化”（如自动补全 <tbody>、移除注释、压缩空格），这会破坏 templ 渲染的精确结构——特别是当碎片含未闭合标签或依赖 whitespace 的 inline-block 布局时。
务必在 CDN 控制台关闭以下选项：
Auto Minify HTMLPolish (HTML optimization)-
Smart Routing（可能改写响应头）
验证方式：curl -I 请求碎片 URL，检查 Content-Length 是否与本地渲染一致；再对比原始 HTML 字符串的 SHA256，任何差异都意味着 CDN 在中间篡改。
最常被忽略的点是缓存键的粒度——不是“模板能不能缓”，而是“这个模板在当前请求参数组合下，输出是否绝对确定”。少算一个 locale 或权限字段，缓存就变成定时炸弹。
