Screenshot — 截图

何时使用 当任务需要截取桌面应用、浏览器页面、模拟器、区域、窗口或全屏截图，特别是用于调试、QA、文档、发布说明、错误报告、视觉审查或之前/之后比较时。这个技能是关于可靠地截取正确的截图，而不是在事后编辑图像。

工具选择 上下文 最佳默认值 为什么 macOS 桌面或窗口截图 screencapture 内置、可靠、支持静默、交互、区域和窗口捕获 iOS 模拟器 xcrun simctl io booted screenshot 比通用桌面捕获更可靠，用于模拟器输出 Linux Wayland grim + slurp X11 工具在 Wayland 上经常失败或行为异常 Linux X11 / headless CI scrot 或浏览器原生捕获 在最小或虚拟显示环境中可用 Windows 桌面捕获 nircmd savescreenshot 或 Pillow ImageGrab 比冗长的 PowerShell 屏幕 API 更容易 网页或网页应用 Playwright 最适合稳定的视口、元素、全页、遮罩和回归截图 视觉差异/截图测试 Playwright 具有固定视口 更好地控制动画、caret、遮罩和可重复性 默认情况下，首先选择最本地的捕获路径。当确定性、遮罩、元素捕获或视觉回归比便利性更重要时，转到浏览器原生工具。

核心规则

• 通过工件选择捕获路径，而不是通过习惯

桌面 UI 截图通常需要操作系统原生工具。网页和网页应用通常需要浏览器原生捕获，而不是桌面截图。模拟器截图应该尽可能来自模拟器工具。使用区域、窗口或元素捕获当局部时；仅当全局上下文很重要时，才使用全屏或全页捕获。

• 在捕获之前稳定目标

动态页面应该在捕获之前稳定：等待网络空闲或特定元素，然后给字体和过渡一个短暂的时间来完成。不要在实际渲染状态存在之前截取截图。对于浏览器捕获，尽可能优先使用显式准备就绪而不是盲等待。如果页面永远不会真正空闲，请等待您需要的确切 UI 状态，而不是追求完美的静止。

• 冻结视口、缩放、缩放和主题以实现可重复性

如果视口、缩放级别、主题或设备缩放发生变化，截图比较将毫无意义。对于浏览器捕获，在截取基线或之前/之后图像之前固定视口。视网膜和 HiDPI 显示器可以产生比预期更多的像素；决定您是否想要物理像素或 CSS 缩放输出并保持一致的选择。如果暗/亮模式很重要，请故意捕获两者，而不是意外地混合它们。

• 捕获最小有用的范围

元素、区域或窗口截图通常比全屏截图更好。全页截图对审计和存档很有用，但长页面变得难以阅读和比较。对于浏览器工作，元素截图或剪裁区域通常会产生比全页输出更干净的差异。如果截图是证据，请保留足够的周围上下文，以便用户可以理解他们正在看什么。

• 在捕获之前删除噪音

隐藏或避免不稳定的 UI，当它不是主题：光标、caret、toast、聊天小部件、通知、加载旋转器、时间戳和随机内容。捕获之前，屏蔽或避免机密、个人数据、令牌和内部 URL。对于 Playwright 风格的浏览器捕获，当视觉稳定性很重要时，禁用动画、隐藏 caret 和屏蔽等功能很有用。如果噪音是 bug，请保留它；否则请删除它。

• 使用正确的输出格式

PNG 是截图、UI、代码、终端和文本密集型捕获的默认格式。JPEG 适用于摄影内容，而不是正常截图。WebP 适用于共享或存储，当兼容性是可以接受的，但如果消费者期望普通 PNG 文件，请不要默认使用它。除非用户明确想要更小的有损输出，否则避免通过 JPEG 管道重新压缩截图。

• 使自动化和 CI 捕获可调试

在失败时，立即在重试或继续之前保存截图。使用稳定的文件名作为基线，并使用时间戳作为 ad hoc 或批量捕获。在 CI 中，相同的视口和确定状态比原始截图量更重要。无头运行应优先使用浏览器原生截图而不是尝试截取主机显示。

• 验证截图实际上是有用的

检查重要细节是否可见、可读且未被裁剪。验证机密是否不再出现在选项卡、侧边栏、URL、通知或测试数据中。之前/之后比较应使用相同的视口、缩放、主题和状态。截图不良如果从技术上讲是正确的，但对于需要它的人来说是无用的。

高价值模式 macOS：screencapture -x out.png 用于静默捕获，-i 用于交互式选择，-R x,y,w,h 用于固定区域。 iOS 模拟器：xcrun simctl io booted screenshot ...