创建自动化报告的HTML代码质量看板实战

W3C nu-validator是唯一被广泛验证的HTML合规性检查服务，需解析其JSON响应中的messages数组定位问题，且必须校验status是否为0；cheerio比正则更稳定，xmlMode: false须显式设置。

用 cheerio + W3C nu-validator 做 HTML 结构检查

直接靠正则匹配 <title>、<meta name="description"> 这类标签容易漏掉嵌套或属性拼写错误，cheerio 才是稳定选择。它能像 jQuery 一样操作 DOM，且不依赖浏览器环境。

关键点在于：W3C 的 nu-validator 是唯一被广泛验证的合规性检查服务，但它的 API 返回的是 JSON，不是 HTML；需要解析 messages 数组里的 message、line、extract 字段才能定位问题。

• 别把 validator 当成黑盒调用——必须检查 status 是否为 0，否则可能返回空结果或超时错误
• cheerio.load(html, { xmlMode: false, decodeEntities: true }) 中的 xmlMode: false 必须显式设为 false，否则会把 <script> 里带 < 的代码误判为非法标签
• 第三方组件（如 Vue SSR 输出）常生成 <div data-v-xxx>，这类属性默认被 validator 报错，需在请求体中加 {"showsource": false} 并配合白名单过滤

生成可交互的 HTML 看板页面，不是静态表格

单纯用 template 拼接字符串生成报告页，后期维护成本高、样式难统一。真正实用的看板得支持：点击问题跳转到源码行号、按严重等级筛选、对比历史分数趋势。

推荐用 ECharts + 纯前端渲染，后端只提供 JSON 数据接口（比如 /api/report/latest），避免每次生成都写磁盘文件。

立即学习“前端免费学习笔记（深入）”；

• 表格列不要硬编码字段名，比如“触控目标尺寸”这种描述性文字，应映射为 touch_target_size 这样的键名，方便前端做条件渲染和排序
• <meta name="viewport"> 缺失和 <img> 缺 alt 属于不同权重等级，报告里必须区分 error / warning / info 三类，不能全塞进一个 <td>
• 别在 HTML 里内联大量 CSS —— 用 <link rel="stylesheet" href="/static/report.css">，否则 nginx 缓存失效时样式错乱不易排查

用 SQLite 存历史数据，但要注意时间精度陷阱

SQLite 虽轻量，但默认的 DATETIME 类型不带毫秒，而一次扫描可能耗时 850ms，若两轮检查间隔短于 1 秒，就可能覆盖前一条记录。

解决方案是：建表时用 TEXT 存 ISO8601 格式时间（如 "2026-06-30T14:22:18.427Z"），查询时用 strftime('%Y-%m-%d %H:%M', timestamp) 做小时级聚合。

• 别用 datetime.now() 直接插入，Python 的 datetime 对象转字符串时默认不带毫秒，要显式调用 .isoformat()
• 历史对比图如果只取最近 7 条，但某天跑了 3 次扫描，就会漏掉中间那次 —— 应该按日期分组取 MAX(timestamp)，而不是 LIMIT 7
• SQLite 不支持 JSON_EXTRACT，所以检查项明细（如每个页面的 img_without_alt 列表）建议序列化为 JSON 字符串存入 details TEXT 字段，前端再解析

接入 CI/CD 时绕开 Puppeteer 渲染陷阱

官网用了 React 或 Vue，静态爬虫抓到的是空 <div id="root"></div>，必须走 Puppeteer 预渲染。但默认配置下，Puppeteer 启动慢、内存泄漏明显，CI 环境尤其容易失败。

核心调整项只有三个：headless: "new"（启用新版无头模式）、args: ["--no-sandbox", "--disable-setuid-sandbox"]（Docker 容器必需）、timeout: 15000（避免单页卡死拖垮整批任务）。

• 别在每次检查都 new Browser() —— 复用同一个实例，用 browser.newPage() 开新页，否则 20 个页面会启 20 个 Chromium 进程
• 动态内容检测完立刻调 page.close()，否则内存占用持续上涨，CI 机器跑几轮就 OOM
• 移动端适配检查不能只靠 page.emulateMediaFeatures([{name: "prefers-color-scheme", value: "dark"}])，得真实触发 window.innerWidth 变化并等待 document.readyState === "complete"

实际部署时最常被忽略的，是 robots.txt 对爬虫路径的限制 —— 自动化检查脚本默认会遵守它，但企业官网往往把测试页或 CMS 后台路径写进了 Disallow，导致漏检。上线前务必确认检查服务的 User-Agent 不在屏蔽列表里，或者临时绕过 robots 协议。