用途:Google 采用移动优先索引,页面的移动渲染是排名依据。本模块检查页面在小视口下是否可用,并指出影响移动可用性的布局问题(这类问题常表现为 CLS,可对照 references/cwv-thresholds.md)。
输入:依据 dispatch envelope 中指定的 PageSnapshot,从 <run_dir>/pages/<slug>.json 读取 parsed(metas[] 中的 viewport 标签),当 render.used 不为 none 时读取 parsed_rendered(布局/几何检查需要它);用 Grep 在 pages/<slug>.html 中查找逐字证据;站点产物位于 <run_dir>/site/{robots.json,sitemaps.json,discovery.json}。audit.mjs 已产出的确定性发现列在 <run_dir>/findings.deterministic.json,不要重复输出这些 id,只补充模型判断的发现。若直接以 URL/路径调用且无快照,先运行 node "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.mjs" <target> --out "${CLAUDE_PLUGIN_DATA}/runs",再使用打印出的快照路径。
审计项:viewport 元标签需存在且含 width=device-width 与 initial-scale=1,标记缺失、固定宽度(width=1024)或阻止缩放(user-scalable=no、maximum-scale=1,后者也损害无障碍);无横向滚动,检测迫使视口宽于设备(约 360px 小视口下内容溢出)的固定宽度容器或过大绝对宽度;点击目标尺寸,交互元素(链接、按钮、表单控件)应足够大且间距合理,避免误触;基础字号可读,正文不应使用仅适合桌面的小字号而迫使移动端捏合缩放;内容一致性,移动 DOM 必须包含与桌面相同的主要内容、标题、结构化数据和链接,隐藏或剥离移动内容存在排名风险。
修复:AUTO(fixable: auto)在缺失时向 <head> 注入 <meta name="viewport" content="width=device-width, initial-scale=1">,确定性、增量、可验证,以 diff 形式输出。ADVISORY(fixable: advisory)针对固定宽度/溢出布局、点击目标尺寸、基础字号和一致性缺口,因其依赖 CSS、设计系统与 JS,破坏风险高,工具只诊断和排序,不自动改布局代码;不要臆造断点值或像素尺寸,只报告观测值或留明确标记的 TODO。
验证:方法 dom_assert,对快照断言(viewport 元标签存在与内容、计算宽度、目标几何)。离线复现确定性部分:node "${CLAUDE_PLUGIN_ROOT}/scripts/parse-html.mjs" --snapshot <pages/<slug>.json>(或 --url <u> / --file <path>),检查 head_hygiene.viewport。点击目标/溢出几何是对渲染快照的 manual_review。当只有 raw_html_path 且无法解析布局时,状态为 needs_api,绝不误判为通过。
发现项:按 schema/finding.schema.json 输出,例如 M7b.viewport.missing(status fail,severity 3,fixable: auto,axis search,confidence established)、M7b.viewport.user_scalable_no(warn,severity 3,advisory,established)、M7b.layout.horizontal_scroll(fail,severity 3,advisory,directional)、M7b.taptarget.too_small(warn,severity 3,advisory,directional)。每条发现需 evidence.observed 引用页面内容(meta 标签字符串、溢出选择器/宽度、目标几何),verification.reproduce 为上述可运行命令,expected_impact 分档并标注置信度,不给出裸百分比。
诚实性:移动友好性是可用性基线,不是强正向排名杠杆;添加 viewport 标签不会给快速、构建良好的纯桌面站点带来排名提升,只是消除可用性负担,应把修复表述为消除风险而非获取排名。Google 已停用独立的 Mobile-Friendly Test 工具和页面体验徽章,不存在可“赢得”的单一移动友好排名标志。存在 viewport 元标签并不证明布局真正响应式,需用渲染快照确认,不能仅凭标签推断。