HTML代码质量迁移本质是语义与结构重构，而非格式美化；需将div id="header"改为<header>、相对路径转根路径、内联脚本提取为JSON script，并谨慎配置HTML Minifier以避免hydration失败和SEO问题。
HTML 代码质量迁移不是格式重排，而是语义与结构的重构
直接用 Prettier 或 HTML Tidy “美化”旧 HTML 文件，只会让问题更隐蔽。真正影响长期可维护性的，是标签语义错用、属性滥用、嵌套混乱和路径硬编码——这些在压缩后反而更难排查。
迁移时优先处理三类高风险结构：
-
<div id="header">→ 必须改为<header>，否则 CSS 和辅助技术无法识别语义层级 -
<img src="images/logo.png">→ 所有相对路径必须转为根路径或环境变量占位符（如/static/images/logo.png），否则构建产物部署到子路径时 404 -
<script>var config = {...}</script>→ 内联脚本中的 JSON 数据必须提取为<script type="application/json" id="app-config">，避免 JS 解析失败或 CSP 拦截
HTML Minifier 配置升级后最常踩的坑：collapseWhitespace 和 removeOptionalTags
升级到 html-minifier@4.0.0 后，collapseWhitespace: true 默认不启用，但一旦开启，会把 <p>Hello<br>World</p> 压成 <p>HelloWorld</p>——<br> 被当作空白吞掉，视觉断行消失。
removeOptionalTags: true 更危险：它会删掉 </head>、</body> 甚至 </li>，而某些 CMS 或 SSR 框架依赖显式闭合标签做 DOM 分割。常见错误现象包括：
立即学习“前端免费学习笔记（深入）”；
- Vue/React hydration 失败，控制台报
Mismatching childNodes - SEO 工具抓取不到
<meta>，因为</head>被删导致解析器提前结束 head 区域 -
<ol><li>A</li><li>B</li></ol>变成<ol><li>A<li>B</ol>，部分浏览器渲染为单个列表项
建议只开 removeComments 和 minifyCSS，其余选项逐个测试上线。
从 HTML4 迁移到 HTML5 时，<section> 不是 <div> 的简单替换
很多团队机械地把所有 <div class="section"> 替换为 <section>，结果破坏了文档大纲（document outline）。<section> 是有隐含标题层级的：它必须包含 <h1>–<h6>，否则会被屏幕阅读器忽略或降级为普通容器。
正确判断方式：
- 该区块是否表达一个独立、完整、可被单独引用的主题？比如“用户评论区”“产品规格表”——适合
<section> - 只是布局分块（如网格容器、响应式 wrapper）？继续用
<div>，加 ARIA role 更稳妥 - 是否需要被
document.getElementById()或锚点链接定位？优先保留id，而非强加语义标签
工具链里不要依赖自动转换插件，html-validate 的 no-unused-elements 规则比任何正则替换都可靠。
迁移中容易被忽略的 meta 和 link 标签校验
很多人只盯着 <body> 内容，却让 <meta name="viewport">、<link rel="canonical">、<meta property="og:title"> 随意带入新项目，导致 SEO 断崖式下跌或移动端渲染异常。
必须逐项检查：
-
<meta charset>是否统一为UTF-8？旧项目可能混用gbk或缺失声明，新构建工具默认 UTF-8，不一致会乱码 -
<link rel="stylesheet">的href是否指向构建后的真实路径？Webpack/Vite 输出的 CSS 文件名带 hash，硬编码路径必然 404 -
<meta name="robots">是否误设为noindex？CMS 导出模板常带测试环境配置，上线前不清理会屏蔽整站
最稳妥的做法：把 <head> 提取为独立模板片段，用构建时变量注入动态值，而不是靠人工复制粘贴。
