htmlhint是模块化场景下唯一能在构建前捕获html结构性错误的守门员，但需手动启用id-unique、tag-pair等规则，并添加attr-value-not-empty检查data-config，禁用attr-lowercase以适配pug/nunjucks，且必须对最终生成的完整html运行检查。
HTMLHint 配置必须覆盖模块化特有风险点
模块化组装本身不校验 HTML 合法性，htmlhint 是唯一能在构建前捕获结构性错误的守门员。但默认规则集对模块化场景覆盖不足——比如它不检查 <include></include> 或 data-module 属性是否被正确解析，也不验证跨文件拼接后是否出现重复 id 或嵌套 <main></main>。
实操建议：
- 启用
id-unique和tag-pair必选规则，防止组件合并后 DOM 结构断裂 - 手动添加自定义规则：用
attr-value-not-empty检查data-config是否为空字符串（常见于模板引擎未传参时） - 在 CI 流程中对最终生成的完整 HTML 文件运行
htmlhint，而非只扫单个header.html片段 - 禁用
attr-lowercase若你用的是 Pug/Nunjucks —— 它们输出的属性名大小写可能与 HTMLHint 默认策略冲突
语义标签边界不能被构建工具“吃掉”
Webpack 的 html-loader 或 Vite 的 html-plugin 在 include 时若配置不当，会把 <header></header> 外层标签当成纯文本吞掉，只剩内部内容，导致语义丢失、屏幕阅读器跳过、:focus-within 失效。
实操建议：
- 确认构建插件配置中
sources或preprocessor选项开启 HTML 解析（如html-loader的esmodules: true） - 避免在组件文件里写
<div class="header">...</div>，直接用<header>...</header>—— 构建工具更难误删原生语义标签 - 用浏览器开发者工具的 “Elements” 面板检查最终 HTML，确认
<nav></nav>、<main></main>等标签真实存在且未被包裹进无意义<div> <li>若使用 Web Components，确保 <code>customElements.define()调用发生在<template></template>克隆之后，否则 Shadow DOM 内部语义可能无法被 Lighthouse 正确识别 - 强制所有模块根节点使用 BEM 命名（如
header__logo、card__body），禁止裸用.title或.content - 避免用
display: contents做模块容器 —— 它删除了 DOM 节点的盒模型，但保留了子元素的可访问性层级，造成渲染与语义错位 - 用
data-module属性替代 class 控制样式作用域：[data-module="carousel"] .slide比.carousel .slide更安全 - 检查构建后 CSS 文件，确认没有重复注入同一份
normalize.css—— 多个组件各自@import会导致样式叠加异常 - 所有模块级 JS 必须用
type="module"，且入口文件顶部加export {}防止被当作普通脚本执行 - 动态插入模块时，用
insertAdjacentHTML('beforeend', htmlString)，但插入前先剥离其中的<style></style>标签，改用document.adoptedStyleSheets注入 - 首屏模块的 HTML 片段必须内联 critical CSS，非首屏模块的 CSS 用
<link rel="preload" as="style" onload="this.rel='stylesheet'">加载 - Vite 项目中慎用
import('./module.html')—— 这是无效语法，应改用import('./module.js')并由 JS 控制 HTML 插入
模块间 CSS 作用域冲突比 JS 更隐蔽
HTML 模块化常搭配 CSS-in-JS 或 scoped style，但纯静态 HTML + 外链 CSS 时，.btn 这类通用类名极易在不同组件中互相覆盖。更麻烦的是，display: contents 包裹模块会让父级样式穿透失效，而 visibility: hidden 则直接让语义结构“消失”。
实操建议：
首屏 HTML 阻塞点藏在模块加载时机里
模块化不是性能银弹。一个 <script type="module"></script> 引入的组件，若其 import 链中包含未标记 async 的依赖，仍会阻塞 parser；而用 insertAdjacentHTML 动态插入的模块，若含内联 <style></style>，会触发 CSSOM 重建，打断渲染流水线。
实操建议：
模块化越深入，HTML 就越不像“静态文档”，而更像一个运行时装配系统。质量把控的关键不在单个文件，而在组装链条上每个环节的契约是否清晰——从构建插件的解析行为，到浏览器对语义标签的真实处理，再到样式和脚本的加载时序，任何一环松动都会让模块变成隐患。
