html结构是项目可维护性的地基，需用语义化标签（如）、data-属性替代class/id定位模块，并通过精准注释和模板规范保障协作效率。
HTML结构不是“写完就扔”的骨架，而是整个项目可维护性的地基。不从结构入手，只靠CSS类名或JS选择器硬扛，三个月后自己都得重读三遍才能改对一个按钮。
为什么套是协作灾难当页面里全是class="container"、class="wrap"、class="box"时，没人能靠扫一眼HTML判断出哪个是主导航、哪个是主内容区、哪个该被SEO抓取。开发者必须切到CSS查样式、跳进JS看绑定、再翻设计稿确认语义——这不是写代码，是在考古。
-
class="header-v2-fix"和class="header-new-2024"共存是常态，没人敢删，也不敢动
-
id不能用作模块锚点：同一页面多次渲染商品卡片，id="product-card"会重复，document.getElementById()只返回第一个
- 嵌套超过三层就该警觉：
<div><div><div><p>文本</p><div class="aritcle_card flexRow artxards">
<div class="artcardd flexRow">
<a class="aritcle_card_img" rel="nofollow" href="/xiazai/skill5493" title="html-to-pptx"><img
src="https://img.php.cn/upload/skill/000/000/081/179051045119472.jpg" alt="html-to-pptx" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a>
<div class="aritcle_card_info flexColumn">
<a rel="nofollow" href="/xiazai/skill5493" title="html-to-pptx" class="overflowclass">html-to-pptx</a>
<p class="overflowclass">将多页 HTML 演示文稿转换为美化的 PPTX 文件，便于分享和分发。</p>
</div>
<a rel="nofollow" href="/xiazai/skill5493" title="html-to-pptx" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span>
</a>
</div>
</div></div></div></div>，审查元素要点四下才能定位目标节点
用对语义标签比写对CSS更重要
浏览器、屏幕阅读器、搜索引擎、新同事，都靠标签名理解结构。<div class="header">是在用CSS模拟语义；<code><header></header>是原生语义，自带ARIA role、SEO权重和可访问性支持。
-
<main></main>必须且只能出现一次，代表页面唯一主体内容；多个会触发axe等无障碍工具报错
-
<section></section>不是“分块容器”，它需要有明确主题，最好带<h2></h2>或更高层级标题
-
<aside></aside>不等于“右边栏”，而是与当前上下文相关但可独立存在的补充内容（比如文章旁的作者简介）
- 避免
<div><nav><ul></ul></nav></div>这种纯装饰性包裹——能用<header><nav><ul></ul></nav></header>就别堆div
data-属性才是JS模块锚点的正确打开方式
靠class="header-nav"或id="main-slider"定位模块，在CSS和JS里耦合太紧。一旦改样式类名或加新交互，JS很可能静默失效。
- 用
data-module="navigation"代替class="navigation"，JS里直接document.querySelectorAll('[data-module="navigation"]')稳稳命中
- 配置走
data-config='{"sticky": true, "mobileBreakpoint": 768}'，而不是拼一堆data-sticky="true" data-breakpoint="768"，后者难维护且易类型错乱
- 禁止在CSS里写
[data-module="header"]——样式逻辑和模块职责不能混
- 每个模块根元素加
data-version="1.3"，CI流程可自动校验HTML片段是否匹配文档版本
注释和模板结构要服务于“人”而不是“机器”
注释不是装饰，是半年后你愿意重写还是愿意修复的关键分水岭。模糊注释如<!-- header -->毫无价值，而动态生成的HTML中注释还可能被SSR框架剥离。
- 组件级注释放在
<section></section>开头，明确作用+上下文，例如：<!-- 搜索框:响应式 + 支持键盘聚焦 + 与 header.js 中 initSearch() 绑定 -->
- 模板片段统一用
<template></template>包裹，而非display:none的<div>——前者不参与渲染、不触发样式计算<li>服务端渲染项目用<code><?php include 'partials/header.php'; ?>，静态站点用{% include header.html %}，纯前端项目别硬上fetch('./header.html')——它不执行脚本、不加载CSS、不解析相对路径
- 模块拆分不是把
<header></header>单独存成header.html就完事，关键看构建链路是否支持、运行时是否引入额外开销
真正卡住维护节奏的，从来不是某个JS函数写得不够优雅，而是<main></main>被误塞进<section></section>、data-module值写成ProductCarousel导致JS查询失败、或者一个<img>缺alt让整页无障碍检测挂掉。这些点看似琐碎，但每一条都在悄悄抬高下次修改的成本。
是协作灾难
当页面里全是class="container"、class="wrap"、class="box"时，没人能靠扫一眼HTML判断出哪个是主导航、哪个是主内容区、哪个该被SEO抓取。开发者必须切到CSS查样式、跳进JS看绑定、再翻设计稿确认语义——这不是写代码，是在考古。
-
class="header-v2-fix"和class="header-new-2024"共存是常态，没人敢删，也不敢动 -
id不能用作模块锚点：同一页面多次渲染商品卡片，id="product-card"会重复，document.getElementById()只返回第一个 - 嵌套超过三层就该警觉：
<div><div><div><p>文本</p><div class="aritcle_card flexRow artxards"> <div class="artcardd flexRow"> <a class="aritcle_card_img" rel="nofollow" href="/xiazai/skill5493" title="html-to-pptx"><img src="https://img.php.cn/upload/skill/000/000/081/179051045119472.jpg" alt="html-to-pptx" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a> <div class="aritcle_card_info flexColumn"> <a rel="nofollow" href="/xiazai/skill5493" title="html-to-pptx" class="overflowclass">html-to-pptx</a> <p class="overflowclass">将多页 HTML 演示文稿转换为美化的 PPTX 文件，便于分享和分发。</p> </div> <a rel="nofollow" href="/xiazai/skill5493" title="html-to-pptx" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span> </a> </div> </div></div></div></div>，审查元素要点四下才能定位目标节点
用对语义标签比写对CSS更重要
浏览器、屏幕阅读器、搜索引擎、新同事，都靠标签名理解结构。<div class="header">是在用CSS模拟语义；<code><header></header>是原生语义，自带ARIA role、SEO权重和可访问性支持。
-
<main></main>必须且只能出现一次，代表页面唯一主体内容；多个会触发axe等无障碍工具报错 -
<section></section>不是“分块容器”，它需要有明确主题，最好带<h2></h2>或更高层级标题 -
<aside></aside>不等于“右边栏”，而是与当前上下文相关但可独立存在的补充内容（比如文章旁的作者简介） - 避免
<div><nav><ul></ul></nav></div>这种纯装饰性包裹——能用<header><nav><ul></ul></nav></header>就别堆div
data-属性才是JS模块锚点的正确打开方式
靠class="header-nav"或id="main-slider"定位模块，在CSS和JS里耦合太紧。一旦改样式类名或加新交互，JS很可能静默失效。
- 用
data-module="navigation"代替class="navigation"，JS里直接document.querySelectorAll('[data-module="navigation"]')稳稳命中 - 配置走
data-config='{"sticky": true, "mobileBreakpoint": 768}'，而不是拼一堆data-sticky="true" data-breakpoint="768"，后者难维护且易类型错乱 - 禁止在CSS里写
[data-module="header"]——样式逻辑和模块职责不能混 - 每个模块根元素加
data-version="1.3"，CI流程可自动校验HTML片段是否匹配文档版本
注释和模板结构要服务于“人”而不是“机器”
注释不是装饰，是半年后你愿意重写还是愿意修复的关键分水岭。模糊注释如<!-- header -->毫无价值，而动态生成的HTML中注释还可能被SSR框架剥离。
- 组件级注释放在
<section></section>开头，明确作用+上下文，例如：<!-- 搜索框:响应式 + 支持键盘聚焦 + 与 header.js 中 initSearch() 绑定 --> - 模板片段统一用
<template></template>包裹，而非display:none的<div>——前者不参与渲染、不触发样式计算<li>服务端渲染项目用<code><?php include 'partials/header.php'; ?>，静态站点用{% include header.html %}，纯前端项目别硬上fetch('./header.html')——它不执行脚本、不加载CSS、不解析相对路径 - 模块拆分不是把
<header></header>单独存成header.html就完事，关键看构建链路是否支持、运行时是否引入额外开销
真正卡住维护节奏的，从来不是某个JS函数写得不够优雅，而是<main></main>被误塞进<section></section>、data-module值写成ProductCarousel导致JS查询失败、或者一个<img>缺alt让整页无障碍检测挂掉。这些点看似琐碎，但每一条都在悄悄抬高下次修改的成本。
