HTML打包前必须做代码质量检查，否则会将结构错误、语义缺失、链接失效和可访问性问题直接发布，导致空白页、404链接或屏幕阅读器无法解析等严重后果；通过htmlhint、axe-cli和link-checker等工具可在构建阶段拦截这些问题，确保SEO、可用性和部署稳定性。
为什么 HTML 打包必须先做代码质量检查
HTML 文件看似简单，但没经过 lint 和可访问性验证就打包，等于把结构错误、语义缺失、链接失效甚至 a11y 问题一并发布。一旦上线，用户看到的是空白页、404 链接或屏幕阅读器无法解析的页面——而这些在 htmlhint 或 axe-core 跑一遍就能拦截。
常见错误现象包括：<img> 缺 alt、<a> 指向已删除路径、<section> 嵌套违反 WAI-ARIA 规则、内联样式掩盖响应式断点等。这些问题不会阻断构建，但会直接损害 SEO 和可用性。
- 用
htmlhint检查基础结构（如标签闭合、属性拼写），配置项.htmlhintrc中至少启用attr-no-duplication、id-unique、head-script-disabled - 用
axe-cli扫描可访问性：执行npx axe-cli ./dist/index.html --reporter=json，CI 中设阈值（如 error ≥ 1 则失败） - 用
lychee或link-checker验证所有<a href>和<img src>是否可解析，避免部署后出现大量 404
打包时如何让 HTML 资源路径不翻车
很多团队打包后发现 CSS 不生效、图片 404、JS 报 Cannot find module，根本原因不是构建工具配错，而是 HTML 中资源引用方式和 publicPath / base 不匹配。
关键点在于：原始 HTML 文件里的 <link rel="stylesheet" href="css/app.css"> 这类硬编码路径，不会被 Webpack/Vite 自动重写；只有通过模块化引入（如 import './app.css'）或 html-webpack-plugin 注入的资源才受控。
立即学习“前端免费学习笔记（深入）”；
- 纯 HTML 项目（无 JS 构建入口）：把静态资源全放
public/目录，HTML 中用/css/app.css（开头斜杠表示根路径），并在构建配置中设base: '/'或publicPath: '/' - Vite 项目：确保
vite.config.js的base与部署路径一致，例如部署到https://example.com/myapp/就设base: '/myapp/'，否则<script type="module" src="/assets/index.xxxx.js">会 404 - Webpack +
html-webpack-plugin：禁用inject: false时，必须手动在模板里用<%= htmlWebpackPlugin.files.js %>插入脚本，否则资源路径丢失
压缩 HTML 时最容易踩的坑
html-minifier-terser 默认配置可能破坏功能，尤其当 HTML 含有服务端模板语法（如 {{variable}}）、内联 SVG 或动态 data- 属性时，盲目开启 collapseWhitespace 或 removeComments 会导致渲染异常。
典型翻车场景：压缩后 Vue 的 v-if 指令被删掉、React 的 data-reactroot 被移除、SVG <use xlink:href="#icon"> 因空格合并失效。
- 关闭危险选项：
collapseWhitespace: false、removeComments: false、removeRedundantAttributes: false（除非确认无服务端逻辑） - 保留必需属性：显式设置
keepClosingSlash: true（防止<img/>变成<img>）、caseSensitive: true（避免 JSX 属性名被转小写） - 对含模板语法的文件跳过压缩：Gulp 或 Webpack 中用
exclude过滤**/template.html等路径，别一刀切
CI 流程里怎么让 HTML 发布真正“自动化”
很多团队以为加个 npm run build 就算自动化了，结果每次还得手动登录服务器 rsync，或者漏传 .htaccess 导致 SPA 路由 404——这不算自动化，只是半自动。
真正的自动化发布，是代码提交 → lint → build → test → deploy 全链路无人值守，且失败能准确定位环节。
- GitHub Actions 示例：在
.github/workflows/deploy.yml中，用actions/upload-artifact@v4上传dist/，再用appleboy/scp-action@v0.1.7推送到目标服务器指定目录，比手敲命令少出错 - Netlify/Vercel 用户：直接连 GitHub 仓库，设
build command为npm run build，publish directory为dist，它们内置的预览 URL 和回滚机制比自建更稳 - Jenkins 场景：避免用
sh -c "rsync ..."直连生产机，改用Publish Over SSH插件，它支持失败重试、权限校验和日志归档，且能隔离密钥
最常被忽略的点：HTML 静态站点没有后端兜底，一次路径配置失误或压缩误操作，就会导致整个页面不可用。所以质量检查不能只跑一次，得嵌在每次 PR 和主干提交里——不是“能打包”，而是“敢发布”。
