html模板复用需按项目类型选策略：静态站点用构建工具（如posthtml-include）、服务端渲染用jinja2的extends/include、纯前端用web components或框架组件；混用会增加维护成本。

HTML模板复用不是靠“复制粘贴+改几个字”撑起来的，而是要按项目规模和交付方式选对策略——静态站点、服务端渲染、纯前端应用，适用的方案完全不同，混用反而增加维护成本。

Web Components 适合轻量级、强隔离需求的组件

当你需要一个按钮、卡片或表单控件，在多个不相关项目里复用，且必须保证样式和行为完全不被外部 CSS/JS 干扰时，CustomElement + Shadow DOM 是最干净的选择。

• <template></template> 必须放在文档顶层（不能嵌在 <div> 或组件内部），否则 <code>template.content 可能为空
• 注册前必须确保 class 已定义，否则 customElements.define() 报错 TypeError: Class constructor cannot be invoked without 'new'
• IE 完全不支持，Edge 79+ 才开始稳定支持，若需兼容旧版，得配 polyfill（如 @webcomponents/webcomponentsjs）
• 不要在 connectedCallback 里直接操作 document.body 或全局样式表，这会破坏封装性

Jinja2 / Flask 的 extends 和 include 适用于服务端渲染项目

如果你用 Flask、Django 或其他后端模板引擎，base.html 继承是最自然的复用路径，但容易忽略继承链的加载顺序和上下文传递限制。


Wechat HTML Publisher
直接上传HTML富文本到微信公众号草稿箱。支持完整的HTML格式,无需Markdown转换。
下载
• {% extends "base.html" %} 必须是模板第一行，前面不能有空格或注释，否则 Jinja2 报错 TemplateSyntaxError: expected token 'name', got 'extends'
• {% include %} 默认不传上下文，若子模板需要变量，得显式写 {% include "header.html" with context %}
• 所有被 include 的文件路径都相对于模板搜索路径（如 Flask 的 templates/），不是相对于当前文件位置
• 避免多层 extends 嵌套超过 3 层，否则调试时很难定位 block 覆盖来源

构建时 HTML 片段合并（如 posthtml-include）适合静态站点生成

纯静态项目（如文档站、营销页）没有后端，又不想引入 JS 加载逻辑，用构建工具预处理 HTML 是最稳的方案。

• posthtml-include 默认只识别 <include src="header.html"></include>，不支持 src="./partial/footer.html" 这种相对路径写法，得统一用根路径或配置 root 选项
• Webpack 的 html-loader + html-webpack-plugin 需开启 preprocessor，否则 会被当成字符串原样输出
• 所有被 include 的 HTML 片段不能含 、 标签，否则最终 HTML 会出现嵌套结构错误
• 构建时无法做运行时条件判断（比如根据用户角色显示不同导航），这类逻辑必须前置到数据层或用 JS 补充

fetch 动态加载 HTML 片段仅限原型或简单页面

用 fetch('nav.html') 插入 DOM 看似简单，但上线后容易暴露跨域、加载失败、SEO 不友好等问题，不是工程化首选。

• 本地开发时 Chrome 会因 file:// 协议拒绝 fetch，必须起一个本地 server（如 npx serve）
• 没加 try/catch 或 fallback 时，网络抖动会导致整个区域空白，且控制台静默失败（除非监听 catch）
• 搜索引擎爬虫基本不执行这段 JS，所以被加载的内容不会进入索引，对 SEO 敏感页面慎用
• 如果片段含内联 <script></script>，innerHTML = html 不会执行它；要用 DOMParser + eval 或手动提取 script 标签再执行，风险高、不推荐

真正难的不是选哪种技术，而是统一团队对「什么该抽成组件、什么该保留在页面内」的判断标准——比如页脚是否带登录状态？导航是否随权限变化？这些业务耦合点一旦没理清，再规范的复用机制也会变成新包袱。