生产环境HTML代码质量保障：监控与告警

生产环境HTML质量保障：别只盯源码，端到端监控才是王道

生产环境的 HTML 代码质量，靠人工肉眼巡检基本不现实，必须上自动化手段来卡住底线。核心逻辑只有一个：监控渲染结果是否符合预期，而不是检查源码格式是否规范。换句话说，页面最终在用户浏览器里长什么样，比编辑器里的是否缩进整齐重要得多。

怎么用 Puppeteer 检测 DOM 结构异常

真实页面加载后，DOM 结构可能因为 JS 错误、资源加载失败、或者 SSR 渲染不一致而缺失关键节点。Puppeteer 是目前最靠谱的端到端检测工具，没有之一。

• 重点监听 page.evaluate() 的返回值，而不是只盯着 page.content() 输出的 HTML 字符串——后者很可能只包含 JS 还没执行前的占位结构，和用户看到的完全不是一回事。
• 检测逻辑写在浏览器上下文里，比如直接判断 document.querySelector('header nav') 是否为 null。这比服务端解析 HTML 更贴近真实用户体验，脚本跑出来的结果基本等于用户看到了什么。
• 别在 page.goto() 后立刻断言，加一句 await page.waitForSelector('main', { timeout: 5000 })，确保关键区域已经挂载到 DOM 上了再做检查。
• 超时设置务必显式传入。默认是 30 秒，如果用默认值，一旦页面加载卡住，告警响应速度会被拖慢好几个量级，这显然不能接受。

为什么不能只用 HTMLLint 或 prettier-check 做生产校验

这些工具只校验源码字符串，对以下几种情况完全无感知，等于形同虚设：

• SSR 模板里 {{ user.name }} 渲染为空字符串，导致
  出现非法空 class
• 前端路由切换后 document.title 没更新，SEO 抓取到错误标题
• 动态插入的 因为 CDN 故障返回 404，但 HTML 源码本身的语法完全合法
• Vue/React 组件里 v-if 或 useEffect 逻辑出错，最终 DOM 缺失 data-testid 属性，导致自动化测试脚本全部失效

这些场景，源码校验工具一个都抓不住。而这才是生产环境里最容易出问题的雷区。

如何把 HTML 质量指标接入 Prometheus + Alertmanager

别把 Puppeteer 脚本直接丢进 CronJob 就跑路了。得包装成一个可以暴露指标的小型 HTTP 服务。

• 用 express 启动一个轻量端点，每次请求触发一次完整的页面检测，返回类似 { "status": "ok", "checks": [{ "name": "header-exists", "passed": true }] } 的结构。
• 在响应头里额外加上 X-Check-Timestamp 和 X-Page-Url，方便出告警时一眼定位到具体页面和时间点。
• 用 prom-client 注册自定义指标，比如 html_check_failed_total{page="checkout",check="submit-button"} 1。这样做的好处是，告警来的时候你不会只看到一句“某处失败”，而是能直接知道哪个页面的哪个检查点了。
• Alertmanager 的 for 时间建议设为 2m，可以有效防止单次网络抖动引发误报；同时配置 group_by: [page, check]，避免 checkout 页和首页的错误混杂在一起，排查成本高得吓人。

其实，真正难点不是跑通检测流程，而是定义哪些 DOM 断言算“不可接受”。比如 footer 缺失可能只是 UI 的小瑕疵，但 form[action] 为空就是功能阻断。每个断言都得和业务影响挂钩，否则告警再多也等于没告。