静态页面生成：动态标签与HTML代码质量管控

在静态页面生成过程中，一个常见的问题是模板语法未被正确识别，导致其原样输出为HTML原始代码。这不是浏览器渲染的问题，而是生成阶段出现的错误。关键在于生成器必须真正“看得懂”这些占位符。例如，StaticHtml只做HTTP快照抓取，SSI或PHP标签不在它的处理范围内；而基于Node的html-webpack-plugin配合lodash.template，需要显式配置loader才能解析{{ }}这类语法。

静态生成时，动态标签怎么才能不炸开？

静态页面生成过程中，、、{{ title }} 这类模板语法如果没被正确处理，就会原样输出到 HTML 文件里，变成肉眼可见的“乱码”或空白——这不是浏览器渲染问题，是生成阶段就失败了。

关键在于：生成器是否识别并执行了这些占位符。比如 StaticHtml 默认只做 HTTP 抓取快照，对服务端 SSI 或 PHP 标签完全无感；而基于 Node 的 html-webpack-plugin + lodash.template 则需要显式配置 loader 才能解析 {{ }}。

• 确认生成工具链是否支持目标模板引擎（如 EJS、Handlebars、Twig）
• 检查构建脚本中是否漏掉 render() 或 compile() 步骤，仅 copy 了原始模板文件
• 避免在 块内混用双大括号语法（如 {{ data }}），可能被 HTMLHint 当作未闭合标签报错

HTMLHint 怎么不把合法的动态占位符当错误？

HTMLHint 是纯静态分析器，它看到 {{ title }} 就会报 attr-lowercase 或 attr-no-duplication 错误，因为它根本不知道这是模板变量——不是 bug，是设计如此。

解决办法不是关掉规则，而是精准排除：

• 在 .htmlhintrc 中用 "attr-req-value": false 松动对属性值的强制要求（适用于 data-* 类动态属性）
• 用注释临时禁用：
• 更稳妥的做法：把模板语法统一放在 或 块里，HTMLHint 默认跳过这些区域

lang 属性和 DOCTYPE 在静态生成中为什么总出错？

很多静态生成器（如 Hugo、Jekyll）默认注入的 和 位置不对，导致 HTMLHint 报 doctype-first 或 charset-req 错误，甚至触发 IE 的怪异模式。

真正起作用的只有两件事：

• </code> 必须是文件开头第一个非空、非注释字符，前面不能有 BOM、空格或
• 必须出现在 前 1024 字节内，且不能被 JS 或 CSS 阻塞（尤其注意某些 CMS 模板里把它放在 后面）
• lang 属性值必须匹配实际内容语言，lang="zh" 和 lang="zh-CN" 对 SEO 和屏幕阅读器行为影响不同，别硬套默认值

语义化标签在静态生成里最容易被忽略什么？

生成器常把所有区块都塞进

，看起来能跑，但

缺失、

嵌套在

里、多个 并列——这些都不是样式问题，是 DOM 结构失效。

后果比想象中严重：

• 搜索引擎可能降权整个页面，因为无法识别主内容区域
• 屏幕阅读器跳过
  直接读 footer，用户根本找不到正文
• document.querySelector('main') 返回 null，JS 逻辑崩掉

检查点很简单：打开生成后的 HTML，在浏览器开发者工具里执行 document.body.querySelectorAll('main, header, na v, footer').length，结果必须 ≥ 4 且每个只出现一次。