HTML模块化需构建流程、语义结构、类名规范三者咬合，否则仅转移混乱；语义标签须承载明确职责边界，组件复用依赖构建工具而非简单include，边界定义比技术选型更重要。
直接说结论：HTML 模块化不是靠“写几个 include”就能落地的，它必须和构建流程、语义结构、类名规范三者咬合，否则只是把混乱从一个文件转移到多个文件。
用语义化标签划分模块，但别只停留在 header/main 表层
很多人以为用了 header、nav 就算模块化了，其实这只是第一步。关键在于每个语义标签是否承载明确的职责边界：
-
section应该对应一个可独立理解、可被单独测试或复用的内容单元（比如“用户评价区”），而不是单纯为了套标签而套 -
article必须能脱离当前页面上下文被 RSS 抓取或搜索引擎索引——如果删掉它整个页面逻辑就断了，那它大概率不该是article -
aside不等于“右边那栏”，它代表的是与主内容相关但可移除的信息；若侧边栏含关键导航或筛选控件，用nav或自定义role="complementary"更准确 - 避免嵌套过深：连续三层
section > article > section会削弱语义，此时应考虑用data-module+ JS 控制更合适
组件复用不能靠手写 <!--#include-->，得绑定构建阶段
原生 SSI 或 PHP include 看似简单，但会导致开发时无法预览组件状态、热更新失效、样式作用域失控。真正可行的路径是：
- 用 Webpack/Vite 的
html-loader或vite-plugin-html处理.html片段，在构建时注入并解析data-props属性传参 - 组件文件统一放在
src/components/下，命名带版本号（如navbar.v2.html），避免多人修改冲突 - 禁止在组件 HTML 内硬编码 CSS 类名；所有样式通过 BEM 命名 + 构建时自动注入 scoped class 前缀（例如
navbar__logo→navbar-v2__logo） - 如果用
<template></template>标签做运行时克隆，必须配合contentDocument或Shadow DOM隔离样式，否则全局 CSS 会污染组件内部
Web Components 不是银弹，先搞清它解决什么问题
注册一个 customElements.define('my-card', MyCard) 很容易，但实际项目中常踩的坑是：
立即学习“前端免费学习笔记（深入）”；
- Shadow DOM 默认隔离样式，但也会隔离
:focus-visible、@media prefers-reduced-motion等系统级响应，需显式透传 - 属性传递只支持字符串，复杂对象得用
JSON.stringify+attributeChangedCallback解析，性能损耗明显 - SSR 场景下，服务端渲染出的
<my-card></my-card>在客户端 hydration 前是空白的，必须配合defer或async加载脚本，否则首屏白屏 - 浏览器兼容性仍存缺口：iOS Safari 对
adoptedStyleSheets支持不全，slot的 fallback 内容在旧版 Edge 中可能错位
最常被忽略的一点：HTML 模块化真正的成本不在写法，而在**边界定义**——一个“登录表单”到底该是组件还是模块？它是否需要携带 auth 状态？是否允许被第三方嵌入？这些决策比选哪个构建工具影响更大。
