HTML可维护性差的核心在于结构模糊、命名随意、嵌套失控；应优先使用语义化标签（如）、描述性类名、扁平结构与规范属性，而非堆砌div和样式化命名。

HTML 可维护性差，通常不是因为写得“不够炫”，而是结构模糊、命名随意、嵌套失控——改一处，三处出 bug。核心判断就一条：别人（或三个月后的你）打开文件，5 秒内能不能准确定位「导航在哪」「主内容从哪开始」「页脚是否独立」？

用对语义化标签，别堆 div

浏览器和开发者工具靠标签名理解结构，div 本身不带任何含义。当你写

，其实是在用 CSS 类“模拟”语义；而

是原生语义，自带 ARIA role、SEO 权重和可访问性支持。

• 必须且只能出现一次，代表页面唯一主体内容；误用多个会破坏屏幕阅读器逻辑
• 不是“分块容器”，它需要有明确主题，最好带
  或更高层级标题
• 不等于“右边栏”，而是与当前上下文相关但可独立存在的补充内容（比如博客文章旁的作者简介）
• 避免

  这类纯装饰性嵌套——能用

  就别用三层 div

  类名必须描述「是什么」，而不是「长怎样」

  类名是 HTML 的接口契约。一旦写成 red-box 或 float-left，CSS 换个配色或布局方式，这个类名就失效甚至误导人。

  • 用 article-card 而不是 box-3，哪怕它现在只是个
  • 状态类用 BEM 风格：button--disabled、nav-list__item--current，不依赖顺序或父级
  • ID 优先用于 JS 锚点或表单关联（如 ），不用作样式钩子
  • 禁止出现 style1、temp-fix、copy-of-header 这类类名——它们会在三个月后变成谜题

  结构扁平、闭合清晰、属性规范

  DOM 层级过深会让 CSS 选择器脆弱、JS 查询变慢、审查元素时眼花。同时，松散的标签书写会放大协作成本。

  
  DeepBI DHTML 页面生成器
  生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
  下载
  • 嵌套建议控制在 3 层以内：比如
    合理，

    就该重构

  • 所有属性值必须用双引号：class="btn btn-primary"，不是 class=btn ——后者在含空格或特殊字符时直接解析失败
  • 自闭合标签统一写法：（HTML5 允许省略 /），不写 或 （后者在 XHTML 场景下不合法）
  • 每个 必须有 或明确的 ，否则表格语义断裂，无障碍工具无法识别

    注释和工具不能替代结构设计

    加注释是补救手段，不是设计缺陷的遮羞布。一个需要大段注释才能看懂的 HTML 片段，大概率结构本身就有问题。

    • 只在真正必要的地方注释：比如复杂组件的边界（），而不是每段
      都加
    • 用 Prettier 或 VS Code 的格式化插件统一缩进（推荐 2 空格），禁用手动 Tab 混用
    • 检查 lang 属性是否设置： 影响字体回退、语音合成、SEO 语言识别
    • 图片必填 alt，空图也写 alt=""（非省略），否则屏幕阅读器会读出文件名或 URL

    真正难的不是记住规则，而是每次敲下

    前多问一句：“这里有没有更准确的语义标签？”——答案往往就在手边的
    、
    或
    里。