W3C HTML验证服务无稳定公开API，必须使用nu Html Checker（https://validator.w3.org/nu/）的POST接口，传入UTF-8编码的HTML原始体，返回JSON格式校验结果。
W3C HTML验证服务本身不提供稳定、生产可用的公开API，所谓“自动化接入”必须绕过其网页界面，用间接方式实现——核心是调用 nu Html Checker（即 https://validator.w3.org/nu/）的 HTTP 接口，而非旧版 https://validator.w3.org/。
为什么不能直接调用 validator.w3.org 的 API？
旧版 W3C 验证器（validator.w3.org）从未设计为程序化服务：它没有文档化 API、无认证机制、无速率限制说明，且后端会主动拦截非浏览器 User-Agent 请求。实测中，curl 或 GitHub Actions 发起的请求多数返回 403 或空响应，不可靠。
nu Html Checker 是官方维护的现代替代品，支持 POST 提交 HTML 内容，并返回 JSON 结果——这才是唯一可工程化集成的入口。
- 接口地址固定为
https://validator.w3.org/nu/ - 必须用
POST方法，Content-Type: text/html; charset=utf-8 - HTML 内容需作为原始请求体（raw body）发送，不能塞在 query string 或 form-data 中
- 响应是 JSON，关键字段为
messages数组，每项含type（"error" 或 "info"）、line、message
如何在 CI/CD 中安全调用 nu Html Checker？
直接裸调接口有风险：网络超时、服务临时不可用、单次验证耗时波动大（尤其含外部资源时）。建议加三层防护：
立即学习“前端免费学习笔记（深入）”；
- 本地 fallback：先用
htmlhint做快速预检（如标签闭合、属性小写），失败则直接中断，不触发远程调用 - 超时控制：curl 设置
--max-time 30，或 Node.js fetch 加signal.timeout(30_000) - 重试机制：最多 2 次 retry，间隔 2 秒，避免瞬时抖动导致误报
示例（GitHub Actions step）：
curl -s --max-time 30 \ -H "Content-Type: text/html; charset=utf-8" \ --data-binary "@dist/index.html" \ https://validator.w3.org/nu/ \ | jq -r 'if .messages | length == 0 then "PASS" else .messages[] | select(.type == "error") | "\(.line):\(.message)" end' \ | grep -q "PASS" || (echo "HTML validation failed"; exit 1)
构建产物验证前必须做三件事
CI 中验证的是 dist/index.html，但这个文件仍可能因构建流程引入非标准内容，导致误报或漏报：
- 确认
dist/index.html开头严格为<!DOCTYPE html>，前面无 BOM、空行、注释——Webpack/Vite 插件有时会注入构建时间注释，需配置移除 - 确保所有框架指令（
v-if、x-data、{{ }}）已彻底编译，验证前运行npm run build而非npm run dev - 删掉开发专用的 inline script，比如
<script>console.log("dev only")</script>，这类代码虽不影响渲染，但可能触发Bad value for attribute类警告
真正难的不是调接口，而是让每次提交的 HTML 在语义和结构上足够干净——验证器不会告诉你 ARIA role 拼错成 roel，也不会发现 <img> 的 alt 是空字符串但实际该有描述。它只管“像不像标准 HTML”，不管“对不对”。
