真正降低维护成本的做法不是“写得更小心”，而是从结构上切断重复：用构建时预处理（如Vite插件）内联navbar.html，或用Web Components封装<app-header>；语义化标签是止损手段，注释须解释“为什么”而非“做什么”，属性值必须用双引号、布尔属性显式写出完整形式。
为什么改一个导航链接要打开十几个文件
因为页头、页脚、侧边栏这些结构被硬编码在每个 HTML 文件里，而不是抽离成可复用的模板。一旦设计变更（比如加个 aria-label 或换链接），就得手动搜遍所有页面，漏掉一个就可能让无障碍检测失败或 SEO 降权。class="header-v2-fix" 和 class="header-new-2024" 并存是典型信号——这不是迭代，是失控。
真正降低维护成本的做法不是“写得更小心”，而是从结构上切断重复：用构建时预处理（如 Vite 的 vite-plugin-html）把 navbar.html 内联进每个页面，输出纯静态 HTML；或者用 Web Components 封装 <app-header>，JS 逻辑和 DOM 结构都收口在组件内部。
- 别用
fetch()加载导航——首屏白屏、CSP 报错、SEO 抓不到内容都是已知风险 -
<template>标签本身不解决复用，必须配合document.importNode()或自定义元素才生效 - 所有模板入口统一加
data-module="header"，JS 查询用document.querySelectorAll('[data-module="header"]')，比靠 class 名可靠得多
嵌套超过三层就该警觉
看到 <div><div><div><div><p>正文</p></div></div></div></div> 这种结构，不是“写完了”，是埋了雷。DOM 深度每增加一层，CSS 选择器匹配开销上升、JS 查询变慢、审查元素定位耗时翻倍，更重要的是——没人能一眼看出哪个 <div> 对应导航、哪个对应商品卡片。
语义化标签不是锦上添花，是止损手段：<header> 替代 <div class="header">，<main> 替代 <div id="content">，<section> 必须配 <h2> 表明主题。W3C 明确要求每页只能有一个 <main>，违反这条，axe 等无障碍工具会直接报错。
立即学习“前端免费学习笔记（深入）”；
-
<main>必须包裹核心内容，不能空着或只放广告 - 连续两个
<section>主题相同时，优先合并，用<h2>分隔子区块 - Chrome DevTools → Elements → 右键节点 → “Break on” → “Attribute modifications” 可快速暴露冗余包裹层
注释不是写给机器看的，是写给三个月后的自己
HTML 注释的价值不在“说明代码在做什么”，而在“解释为什么这么写”。<!-- 主导航菜单 --><nav> 没信息量；<!-- v1.3 - 2026-06-15: 移除 hover 下划线，适配 WCAG 2.2 聚焦可见性要求 --> 才有用。后者告诉你改了什么、依据是什么、谁拍的板。
块级注释要成对出现，且紧贴结构边界：<!-- 页脚内容开始 --><footer>...</footer><!-- 页脚内容结束 -->。这样在折叠代码时能一眼识别区域，也方便搜索定位。
- 避免在每行标签前加
<!-- div wrapper -->这类无意义注释 - TODO/FIXME 必须带责任人和截止时间，例如
<!-- FIXME @zhangsan 2026-08-30: 处理 Safari 17.5 下 flex gap 回退方案 --> - 国际化项目中，注释统一用英文，避免中文注释在团队协作时造成理解偏差
引号缺失和布尔属性写法是隐形维护陷阱
<img src=logo.png alt=公司标识> 看似能跑，但实际会导致属性值截断（logo.png?w=100&h=50 里的 & 会被解析为新属性起点）、JS 获取 el.getAttribute('src') 返回 null、甚至在某些构建工具中直接报错。HTML5 明确要求所有属性值用双引号包裹。
布尔属性如 required、disabled 也不能简写：<input required> 是合法的，但 <input required="required"> 更稳妥——尤其当 JS 动态设置时，el.setAttribute('required', '') 和 el.setAttribute('required', 'required') 行为一致，而前者在部分旧环境可能失效。
- 所有属性值必须用双引号，包括空字符串：
data-id="" - 布尔属性显式写出完整形式，避免依赖浏览器隐式转换
- 用 Prettier 或 ESLint + HTML 插件做保存时自动修复，别靠人眼检查
语义化不是风格选择，是结构底线；模板化不是工程炫技，是止损动作；而注释和引号这些细节，恰恰是交接时最先被忽略、出问题时最难排查的部分。
