必须用https://validator.w3.org/nu/验证HTML5代码，旧版会误报<dialog>等合法元素；需粘贴含<!DOCTYPE html>和根标签的完整文档结构，避免行号、单引号、本地地址等干扰。
怎么用 ECharts 渲染 HTML 质量评分趋势图
直接复用 ECharts 的 line 图是最稳妥的选择，别用 bar 或 pie ——它们没法表达时间维度上的连续波动。重点不是画得好看，而是让开发和 QA 一眼看出某次上线后 SEO score 是否断崖下跌。
关键配置项必须设对： xAxis.type 得是 'time'， series.data 每个点要带 timestamp 和数值，比如 [1719734400000, 82.4]（毫秒时间戳）。漏掉时间戳，图表就变成按数组索引排布的无序折线，历史对比完全失效。
- 数据源建议从 SQLite 的
quality_history表查，字段至少含scan_time、overall_score、error_count - 避免在前端做时间格式转换，后端返回 ISO 字符串（如
"2026-06-28T09:30:00Z"）更可靠 - 加个
markLine标出 80 分阈值线，低于它自动标红，比纯数字提醒更直观
如何把 W3C 验证错误定位到具体 HTML 行号
nu-validator API 返回的错误结构里，lastLine 和 lastColumn 是唯一能精准锚定问题的位置信息。但注意：它返回的是原始 HTML 经服务器解析后的行号，不是你本地文件的物理行号——尤其当页面含服务端 include 或模板变量时，偏差可能达 10 行以上。
真正可用的方案是让爬取阶段保存原始 HTML 快照，并在分析阶段用 cheerio.load(html, { xmlMode: false }) 同步解析 DOM，再结合 nu-validator 的 message 和 extract 字段做上下文匹配。比如报错 "Element div must not have attribute data-v-xxxx"，就用正则在快照里找最近的 <div data-v- 片段，往前推 3 行确认是否在 Vue SFC 编译产物里。
立即学习“前端免费学习笔记（深入）”；
- 别依赖
nu-validator的source字段——它常为空或截断 - 动态渲染页（如 React SSR）必须走 Puppeteer 预渲染后再校验，否则
cheerio解析的是骨架 HTML，大量错误漏检 - 第三方组件生成的标签（如 antd 的
<div class="ant-btn"）建议加白名单规则，避免刷屏式误报
为什么移动端适配检查总在 CI 里失败
根本原因是 CI 环境没模拟真实设备视口。用 puppeteer.launch({ headless: true }) 默认启动的是桌面 UA，viewport 宽度是 800px，根本触发不了媒体查询里的 @media (max-width: 768px)。必须显式设置设备参数：
const browser = await puppeteer.launch({
headless: 'new',
args: ['--no-sandbox', '--disable-setuid-sandbox']
});
const page = await browser.newPage();
await page.emulateMediaType('screen');
await page.emulateViewport({ width: 375, height: 812, deviceScaleFactor: 2 });
这里 deviceScaleFactor: 2 关键——它决定 window.devicePixelRatio 值，而很多响应式 JS 逻辑（比如图片 srcset 切换）就靠它判断高清屏。漏掉这行，检测结果和真机完全不一致。
- 别用
page.setViewport()替代emulateViewport()，前者不改 UA，后者会同步注入设备特征 - 触控目标尺寸检查（如按钮
min-width: 48px）必须在 emulated viewport 下运行，否则 CSS 计算基于错误的视口宽度 - CI 中启用
--disable-gpu参数反而会导致某些 CSS transform 渲染异常，建议关闭
邮件报告里怎么让开发一眼找到修复入口
邮件正文里只放摘要没用，开发最需要的是「点击即跳转」。方案是：在报告生成阶段，为每个问题生成唯一 URL，形如 https://monitor.example.com/report/20260628-1542?issue=seo-title-dup。这个链接背后路由到前端页面，用 history.state 携带问题 ID，页面加载后自动滚动到对应 DOM 节点并高亮。
实现要点在于后端生成报告时，把 page_url、selector（如 "head title"）、line_number 打包进 URL 的 query 参数。前端用 document.querySelector(selector) 定位，失败则 fallback 到 document.body 并弹窗提示「选择器失效，请检查是否为动态渲染内容」。
- URL 里别传原始 HTML 片段——长度超限且有 XSS 风险
- Git 仓库路径（如
src/pages/home.html）要和 CI 构建时的 workspace 路径严格一致，否则 VS Code Remote 插件无法一键打开 - 邮件客户端对长 URL 支持差，用
bit.ly类服务做二次缩短前，务必测试 Outlook 和企业微信的解析兼容性
