必须在校验构建产物而非源码，因Vite/Webpack等工具会重写HTML（如注入script、改base href、动态id、删alt），导致源码与dist语义不一致；校验源码漏检80%线上风险，故需在容器中对dist/*/.html执行html-validate，并确保路径映射正确、glob生效、编码支持UTF-8。
CI/CD 流水线里 HTML 校验必须在容器内、编译后、部署前执行，否则 html-validate 检测的只是源码模板，而真正上线的是构建产物（如 Vite/Webpack 注入变量、删除注释、重写路径后的 index.html），两者语义可能不一致。
为什么不能在校验源码阶段就结束？
构建工具会改写 HTML：Vite 插件自动注入 <script type="module">、Webpack 的 HtmlWebpackPlugin 重写 <base href>、SSR 框架输出的 HTML 可能含动态 id 或缺失 alt——这些只有在 dist/ 目录生成后才真实存在。校验源码等于漏检 80% 的线上风险。
-
index.html里<img src="">在源码中合法，但构建后变成<img src="">，触发img-req-alt失败 - Webpack 自动添加的
<link rel="preload" as="script">若as值拼错（如as="scrip"），W3C 不报，但 Chrome 会忽略，html-validate默认规则也不覆盖 - 构建后插入的 BOM 或空行（尤其 Windows 环境下
copy-webpack-plugin误读文件）会导致missing DOCTYPE报错，本地开发完全看不到
怎么让容器只校验 dist/ 里的最终 HTML？
关键不是“能不能”，而是“要不要把构建和校验拆开”。推荐单阶段镜像 + 构建后 COPY，避免多阶段镜像中 dist/ 被遗漏或路径错位。
- Dockerfile 中先运行构建命令（如
npm run build），再COPY dist/ ./dist/，而不是从宿主机 COPY 构建产物——后者破坏可重现性 -
html-validate命令目标必须是dist/**/*.html，且配置里"files"字段要显式排除!node_modules/**和!src/**，防止误扫残留文件 - 加
--no-warnings参数抑制非阻断提示，只让exit 1由 error 触发，避免 warning 干扰 CI 判断 - 若用
axe-core做运行时检测，必须在容器里装 Chromium（apk add --no-cache chromium），且启动时加--headless --no-sandbox，否则axe.run()会卡住
常见失败原因：容器里 html-validate 找不到文件
根本问题不是命令写错，而是路径映射失效。Alpine 镜像默认工作目录是 /，WORKDIR /app 后没 RUN cd /app，导致 COPY dist/ ./dist/ 实际落在 /dist/，但 html-validate dist/**/*.html 会因 glob 展开失败静默跳过。
立即学习“前端免费学习笔记（深入）”；
- 确认
COPY后执行RUN ls -la dist/查看文件是否真在预期位置 - 用绝对路径调用：
CMD ["html-validate", "--config", "/app/.htmlvalidate.json", "/app/dist/**/*.html"] - 避免 shell 形式 CMD（如
CMD html-validate ...），它会触发 Alpine 的/bin/sh，而 glob 不被支持；必须用 exec 形式（方括号语法） - 如果构建产物含中文路径或特殊字符，Alpine 默认 locale 是
C，html-validate读取文件名会乱码，加ENV LANG=C.UTF-8解决
最易被忽略的点：校验器本身不验证 <link href="/css/app.css"> 是否真存在，也不检查 CSP header 是否匹配内联脚本——它只管语法和结构。所以容器化校验只是第一道闸，后面还得接 htmlproofer 扫 404 和 curl -I 检查响应头。
