web-quality-audit

Web 质量审计

全面的质量审查，结合实时浏览器证据与源代码检查。涵盖性能、无障碍、SEO、最佳实践和 Agent 式浏览，不把综合评分当作质量证明。

Lighthouse 13+。 Performance 类别现在在 Lighthouse 和 DevTools Performance 面板中使用共享的 Performance Insights（公告）。请遵循当前的洞察名称和证据。不要要求已移除的审计 ID，也不要自动重新创建相关建议；其中一些审计因噪声过多、无法采取行动或容易导致过度建议而被弃用。

工作原理

1. 确定审计目标：有代表性的 URL、重要状态和用户流程、公开访问还是身份验证访问，以及移动端/桌面端范围。
2. 如果页面可以运行，请阅读测量工作流，并在广泛搜索代码库之前收集最小化的实时基线。
3. 根据运行时故障确定源代码检查范围。将测量所得的发现与仅在代码中发现的假设分开。
4. 按用户影响和可信度分类，然后提出或建议具体的修复措施。
5. 重新运行等效的自动化检查和受影响的手动流程。报告哪些内容已验证，哪些仍需实地或人工验证。

工具选择

使用当前可用的最佳能力；不要因可选设置而阻碍审计。

需求	首选方式	备用方式
性能和 Core Web Vitals	录制浏览器性能跟踪并分析重点洞察；使用 Chrome DevTools MCP 时，调用 performance_start_trace，然后调用 performance_analyze_insight	Lighthouse CLI 或 PageSpeed Insights 实验室数据
真实用户性能	当前 DevTools 跟踪摘要中包含的 CrUX 数值	PageSpeed Insights/CrUX Vis；只有在已有密钥或需要自动化时才直接调用 CrUX API
无障碍、SEO、最佳实践、Agent 式浏览	运行实时 Lighthouse 审计；使用 Chrome DevTools MCP 时，调用 lighthouse_audit	针对特定类别运行 Lighthouse CLI 审计并进行手动检查
渲染后的语义结构和交互	检查无障碍树并操作 UI；使用 Chrome DevTools MCP 时，调用 take_snapshot 和有针对性的 evaluate_script	浏览器/手动测试
源码冒烟测试	scripts/analyze.sh <path>	直接检查源代码

Chrome DevTools MCP 的 lighthouse_audit 会有意排除性能审计。其导航模式会重新加载页面；如果需要保留当前身份验证状态或用户创建的状态，请使用快照模式。静态分析器是快速冒烟测试，不能替代渲染页面审计。

审计类别

性能

Core Web Vitals — 页面体验良好必须满足以下指标：

• LCP（最大内容绘制）< 2.5s。 最大的可见元素必须快速呈现。优化图片、字体和服务器响应时间。
• INP（交互到下一次绘制）< 200ms。 用户交互必须感觉即时响应。缩短 JavaScript 执行时间，并拆分长任务。
• CLS（累积布局偏移）< 0.1。 内容不得跳动。为图片、嵌入内容和广告设置明确的尺寸。

资源优化：

• 压缩图片。 使用 WebP/AVIF，并提供后备格式。通过 srcset 提供尺寸合适的图片。
• 尽量减少 JavaScript。 移除未使用的代码。使用代码拆分。延迟加载非关键脚本。
• 优化 CSS。 提取关键 CSS。移除未使用的样式。避免使用 @import。
• 高效使用字体。 使用 font-display: swap。预加载关键字体。仅保留所需字符。

加载策略：

• 预连接到源站。 为第三方域名添加 <link rel="preconnect">。
• 预加载关键资源。 LCP 图片、字体和首屏上方的 CSS。
• 延迟加载首屏下方的内容。 图片、iframe 和大型组件。
• 有效缓存。 为静态资源设置较长的缓存 TTL。为带哈希的文件使用不可变缓存。

无障碍

可感知：

• 文本替代。 每个 <img> 都应有含义明确的 alt 文本。装饰性图片使用 alt=""。
• 颜色对比度。 正常文本至少为 4.5:1，大号文本至少为 3:1（WCAG AA）。
• 不要仅依赖颜色。 在颜色指示之外，同时使用图标、图案或文本。
• 字幕和文字稿。 视频应有字幕。音频应有文字稿。

可操作：

• 支持键盘操作。 所有功能都可通过键盘使用。不得出现键盘陷阱。
• 焦点可见。 所有交互元素都应有清晰的焦点指示。
• 跳转链接。 为键盘用户提供“跳转到主要内容”链接。
• 提供充足时间。 用户可以延长时间限制。不得在没有控制选项的情况下自动推进内容。

易于理解：

• 页面语言。 在 <html> 上设置 lang 属性。
• 导航一致。 各页面使用相同的导航结构。
• 错误识别。 清楚描述表单错误，并将其与对应字段关联。
• 标签和说明。 所有表单输入项都应有关联的标签。

稳健：

• 有效的 HTML。 不得有重复的 ID。正确嵌套元素。
• 正确使用 ARIA。 优先使用原生元素。ARIA 角色应与实际行为相符。
• 名称、角色和值。 交互元素应有无障碍名称和正确的角色。

SEO

可抓取性：

• 有效的 robots.txt。 不得屏蔽重要资源。
• XML 站点地图。 列出所有重要页面。提交到 Search Console。
• 规范 URL。 避免重复内容问题。
• 重要页面不得设置 noindex。 检查 meta robots 和响应头。

页面内 SEO：

• 标题标签具有唯一性。 为每个标题撰写描述准确且简洁的内容；不同设备和搜索结果类型的截断方式可能有所不同。
• 元描述。 撰写实用且针对特定页面的摘要；搜索引擎可能会选择不同的摘要片段。
• 标题层级。 主标题应描述清晰，结构应符合逻辑；不得仅因使用了多个 <h1> 就判定有效的 HTML 不合格。
• 链接文本应描述明确。 不要使用“点击此处”或“阅读更多”。

技术 SEO：

• 适合移动设备。 采用响应式设计。点击目标 ≥ 48px。
• HTTPS。 必须使用安全连接。
• 页面体验信号。 使用实测 Core Web Vitals 作为依据，但不要承诺排名会因此变化。
• 结构化数据。 使用 JSON-LD 提供丰富摘要（文章、产品、常见问题等）。

最佳实践

安全性：

• 全站使用 HTTPS。 不要混合内容。启用 HSTS。
• 不使用存在漏洞的库。 保持依赖项为最新版本。
• 设置 CSP 标头。 使用内容安全策略防止 XSS。
• 不暴露源映射文件。 在生产构建中不暴露。

现代标准：

• 不使用已弃用的 API。 替换 document.write、同步 XHR 等。
• 使用有效的 doctype。 使用 <!DOCTYPE html>。
• 声明字符集。 将 <meta charset="UTF-8"> 作为 <head> 中的第一个元素。
• 不出现浏览器错误。 保持控制台干净。避免 CORS 问题。

UX 模式：

• 不使用侵入式插页。 尤其是在移动设备上。
• 明确请求权限。 仅在需要时请求，并说明原因。
• 不使用误导性按钮。 按钮的实际功能应与其说明一致。

Agentic 浏览

使用 Lighthouse Agentic Browsing 结果作为技术信号，判断助手理解并与渲染页面交互的能力。

• 提供可访问的交互界面。 语义化 HTML、标签、名称、角色和状态必须在无障碍树中呈现有意义的控件。
• 存在 WebMCP 集成时，其有效性应得到验证。 检查已注册的工具、架构和表单覆盖情况；不要仅为提高审计分数而添加 WebMCP。
• llms.txt 是可选的。 有效文件或许能帮助兼容的工具发现经过整理的内容，但 Lighthouse 审计通过并不能证明搜索或 AI 产品会收录、排名或引用该文件。
• 将此类别与 SEO 声明区分开来。 Agentic 可浏览性并不能证明搜索排名或 AI 可见度。

严重级别

级别	说明	操作
严重	安全漏洞、完全失效	立即修复
高	Core Web Vitals 不通过、严重的无障碍障碍	发布前修复
中	性能优化机会、SEO 改进	在当前迭代周期内修复
低	细微优化、代码质量问题	方便时修复

审计输出格式

执行审计时，请按以下结构整理发现：

## Audit results

### Evidence
| Signal | Scope/conditions | Result | Source |
|--------|------------------|--------|--------|
| LCP | URL, phone, p75/28 days | 3.1s (needs improvement) | CrUX |
| Accessibility | URL, mobile navigation | 92 | Lighthouse |

### Critical issues (X found)
- **[Category]** Issue description. File: `path/to/file.js:123`
  - **Impact:** Why this matters
  - **Evidence:** Measured failure, runtime observation, or source hypothesis
  - **Fix:** Specific code change or recommendation

### High priority (X found)
...

### Summary
- Performance: measured status and X findings
- Accessibility: automated status, X findings, manual checks pending/passed
- SEO: X findings
- Best Practices: X findings
- Agentic Browsing: X findings or not available

### Recommended priority
1. First fix this because...
2. Then address...
3. Finally optimize...

### Verification
- Re-run results under the same conditions
- Manual checks completed
- Field validation still pending

快速检查清单

每次部署前

• Core Web Vitals 通过
• 无无障碍错误（axe/Lighthouse）
• 无控制台错误
• HTTPS 正常工作
• 元标签已设置

每周检查

• 在 Search Console 中检查问题
• 查看 Core Web Vitals 趋势
• 更新依赖项
• 使用屏幕阅读器进行测试

每月深入检查

• 执行完整的 Lighthouse 审计
• 进行性能分析
• 与真实用户一起进行无障碍审计
• 检查 SEO 关键词

参考资料

特定领域的详细指南：

• 性能优化
• Core Web Vitals
• 无障碍
• SEO
• 最佳实践