Facet

facet-check

在真实手机、平板电脑和桌面设备视口中检查网页的响应式设计问题。 它可以通过命令行运行、在 CI 中运行，也可以作为 MCP 服务运行，供 AI 编码 Agent（Claude Code、Cursor、Codex、VS Code）调用。

npx @chandra14/facet-check localhost:3000

也可以通过 npm install -g @chandra14/facet-check 安装一次，然后运行 facet-check localhost:3000。

以下是一个价格表宽度超出手机屏幕的测试页面的输出（已缩短）：

Facet check http://localhost:3000
6 devices · 14 errors · 14 warnings

✗ iPhone 16 393×852 @3x
  error Page scrolls sideways by 267px — The document is 660px wide in a 393px viewport.
  error Extends 267px past the viewport — <table.prices> “SizeWhole beanGroundSubscriptionWholesal”
        html > body > main > table
        fix: Constrain it with max-width: 100%, min-width: 0 on a flex child, overflow-wrap: anywhere, or let it scroll inside its own container.
  error Tap target is 13 × 13px — <input#weekly>
        #weekly
        fix: Targets must be at least 24 × 24px (WCAG 2.5.8); 44 × 44px is comfortable.
  warn  Field text is 14px, so iOS zooms in on focus — <input#email>
        #email
        fix: Give form controls font-size: 16px or larger.
  console Carousel failed to initialise at 393px

! Full HD laptop at 125% (most common) 1536×864 @1.25x
  warn  Text is only 10px — <p#terms> “Prices include tax. Orders placed after ”

每台设备都在无头 Chromium 中进行真实模拟，而不是调整窗口大小。它会使用设备的视口、像素比、触控支持、移动端视口行为和用户代理。如果页面没有 viewport meta 标签，手机上的布局宽度会是 980px，与真实设备上的表现一致。

它是 Facet 的命令行和 Agent 端。Facet 是一个开源浏览器，专为响应式 Web 开发打造。Facet 的设备目录包含 290 多种配置，从 iPhone SE 到 2026 年旗舰机型、折叠屏设备、平板电脑、笔记本电脑和 4K 显示器。

检查内容

在每台设备上检查：

• 水平滚动，以及导致问题的元素（例如表格，而不是表格中的每个单元格）
• 触控设备上小于 24 × 24px 的点击目标（WCAG 2.5.8）
• 小于 12px 的文本，以及被截断但没有省略号的文本
• 小于 16px 的表单字段，这会导致 iOS 在聚焦时放大页面
• Viewport meta 问题：缺失、值不是 device-width，或缩放功能已禁用
• 尺寸远超所需、在高像素密度屏幕上模糊或缺少尺寸信息的图片
• 遮挡小屏幕过多内容的固定页眉和横幅
• 每台设备上的控制台错误、未捕获异常和失败请求。只有一台设备记录到的错误，说明存在特定视口下的 bug。

命令行

npx @chandra14/facet-check <url> [options]

选项
-d, --devices <list>	设备 ID、名称、类似 1024x768 的尺寸，或预设（默认：popular）
-s, --screenshots <dir>	保存每台设备的 PNG 截图
--full-page	捕获整个页面，而不只是首屏
--json	以 JSON 格式输出完整报告
--all	同时列出信息级别的提示
--fail-on <level>	发现级别至少为 error（默认）、warn 或 info 的问题时退出码为 1；never 则始终以 0 退出
--timeout <ms>	页面加载超时时间（默认 30000）
--list-devices [query]	显示预设和设备目录

URL 可以是完整 URL、裸域名（example.com）、本地开发服务器（localhost:3000、:5173），也可以是 HTML 文件路径。

预设：popular（六种最常见的真实设备尺寸）、default（手机、平板电脑、笔记本电脑）、phones、latest、tablets、desktops、apple、foldables、extremes。

npx @chandra14/facet-check localhost:3000 -d phones --screenshots shots
npx @chandra14/facet-check https://example.com -d iphone-17,"Galaxy S26",ipad,1440x900 --json

在 CI 中运行

发现错误时退出码为 1，因此可以用它来阻止拉取请求合并：

- run: npx @chandra14/facet-check http://localhost:4173 --fail-on error

面向 AI Agent 的 MCP 服务

facet-check mcp 会通过 stdio 运行 Model Context Protocol 服务。随后，Agent 可以在多种屏幕尺寸下检查自己所做的 CSS 更改，并查看结果。

Claude Code

claude mcp add facet -- npx -y @chandra14/facet-check mcp

Cursor、VS Code、Claude Desktop 和其他客户端

{
  "mcpServers": {
    "facet": { "command": "npx", "args": ["-y", "@chandra14/facet-check", "mcp"] }
  }
}

工具	功能
check_responsive	在多台设备上加载 URL，并返回各设备上的问题、选择器和修复建议
screenshot	为每台设备返回一张带标签的图片（视口或整页）
compare_element	测量每台设备上的一个元素：尺寸、可见性、字体大小、显示方式、flex 和 grid
audit_accessibility	在一台设备上运行 axe-core，并返回 WCAG 违规项及修复建议
list_devices	列出设备目录和预设

然后可以提出这样的请求：“检查 localhost:3000 在手机上的显示，并修复所有导致横向滚动的问题。”

要求

Node 20 或更高版本，以及基于 Chromium 的浏览器。facet-check 会按以下顺序使用浏览器：FACET_CHROME 指定的浏览器、Playwright 的 Chromium（npx playwright install chromium）、Google Chrome，然后是 Microsoft Edge。大多数机器上已经安装了其中一种浏览器。

限制

• 仅支持 Chromium。 iPhone 配置模拟的是 iPhone 屏幕，而不是 Safari 的 WebKit 引擎。Safari 特有的问题仍需使用 Safari 检查。
• 它会检查页面加载后的状态。命令行无法访问登录后或点击后才能显示的内容。

许可证

MIT