不少开发者在初次尝试网页模板化时，容易陷入一个常见误区：直接将编写好的 HTML 代码复制粘贴到新文件中，便认为这就是“模板复用”了。

问题恰恰出在这里。你复制的那个 index.html 中，。另外，千万不要使用 这种自闭合写法，HTML5 不认可，老老实实写 才是最稳妥的起点。

如何提取并命名公共模块才能避免踩坑

首先要明确一个原则：并非所有重复代码都适合抽成模块。导航栏、页脚、面包屑、侧边栏这些，如果 90% 的页面几乎完全一致，那么拆分出来没有问题。但像轮播图或广告位这种每页都略有差异的区块，强行统一反而会让维护变得更为棘手。

判断标准其实很简单：这个区块在绝大多数页面中是否完全一致？如果是，就拆分；如果每次都需要微调 class 或文案，那就把它作为局部定制区域，不要硬塞进母版中。

再补充几个实践中的要点：

• 模块文件名一定要具备语义，例如 header-main.html，不要用 top.html 这种模糊的命名；common.html 更是大忌
• 在主模板中使用明确的注释标记插入点，比如 ，比单纯写 更容易让工具或后续接手的人快速定位
• 如果使用构建工具（如 Webpack + html-webpack-plugin），模块路径必须相对于入口 HTML，否则 include 指令会找不到文件
• 注意嵌套层级：header-main.html 中不要再 include 其他模块，除非你明确支持多层展开，否则很容易陷入循环引用或路径错乱的陷阱

占位符如何编写才能避免与真实内容冲突

使用 {{xxx}} 是最稳妥的做法。它既不是 HTML 标签，在 JS 字符串中也不常见，而且主流模板引擎（Jinja2、Handlebars、Nunjucks）都原生支持。千万不要用 $xxx$ 或 [xxx]——这些符号很容易与 CSS 变量、正则表达式甚至用户输入内容发生冲突。

以下是一些容易出问题的场景：

• 用户评论中写了 {{user_name}}，结果被模板引擎误解析为变量
• 占位符没有加空格，比如 {{title}}文章，实际渲染时变成“首页文章”，中间缺少分隔

应对方案也很直接：

• 占位符前后加空格或换行，例如

  {{page_title}}

  ，降低误匹配的概率
• 敏感字段（如 content）必须明确声明是否允许 HTML。如果允许，需要做 XSS 过滤；如果只接受纯文本，就用 {{content|safe}}（Jinja2 语法）或显式转义
• 路径类占位符要带前缀，比如 {{asset_path}}/css/app.css，而不是直接写 /css/app.css。这样部署到子路径时才能一键替换

本地开发时如何验证模板是否真正能够复用

仅看单个页面渲染正常远远不够。真正验证模板有效性的唯一方式，是新建至少两个结构不同的页面（比如列表页和详情页），都继承同一套母版，然后检查三件事：DOM 结构是否一致、CSS 选择器是否依然生效、JS 初始化逻辑是否还能正确获取到元素。

最容易忽略的地方往往是：