[博客与指南](https://openscreenshot.app/zh-cn/blog/) · 开发者与智能体

# 为 CI 和发布审查截取网站截图

用 OpenScreenShot CLI 生成可重复的 PNG 产物，并了解截图在构建流水线中能验证什么。

作者 [OpenScreenShot](https://github.com/pghqdev/OpenScreenShot)

在 CI 中使用 OpenScreenShot CLI，把运行中应用的 PNG 保存下来供审查。准备一个 Chrome 兼容浏览器，启动应用，等它就绪，然后截取固定的 URL 和视口。用 CI 服务商的产物机制上传生成的文件。

## 让环境可重复

对于已经使用 pnpm 的项目，请把 CLI 添加为开发依赖，并提交由此产生的清单文件和锁文件更改：

```
pnpm add -D -E openscreenshot
```

在 CI 中使用项目的冻结锁文件安装依赖。该软件包使用 `puppeteer-core`，不会下载浏览器，因此运行器还需要 Chrome 或 Chromium。如果可执行文件不在受支持的默认位置，请设置 `CHROME_PATH`。

比较截图时，请保持浏览器版本、字体、视口、应用数据和软件包版本稳定。即使应用代码没有变化，字体或浏览器渲染器的变化也可能改变图片。

## 在应用就绪后截图

用项目自己的命令启动开发服务器或预览服务器。运行以下示例前，请等待路由及其依赖就绪；端口 4321 只是示例，必须与你的应用一致：

```
mkdir -p artifacts
pnpm exec openscreenshot shot http://127.0.0.1:4321 --out artifacts/desktop.png --width 1440 --height 900
pnpm exec openscreenshot shot http://127.0.0.1:4321 --out artifacts/narrow.png --width 390 --height 844
```

这些命令生成视口截图。如需审查整个页面，请加上 `--full`。把 `artifacts/` 目录交给 CI 的产物上传步骤，审查者就能在拉取请求或发布旁打开这些文件。

CLI 在页面导航时会等待网络空闲，但这不能保证应用特有的工作已经完成。它没有可配置的选择器等待，也不能注入设置脚本。当普通路由包含动画、可变内容或身份验证时，请使用专门的、稳定的审查路由，并配以确定性的数据。

## 截到图片不等于通过视觉测试

命令可能在截下服务器错误或加载界面后仍成功退出。请把 PNG 当作审查产物。视觉回归系统还需要基准图、图像比较方法、阈值，以及接受预期变更的流程；OpenScreenShot 的 CLI 不提供这些部分。

窄屏截图是有用的响应式版式检查，但它不是移动设备模拟。同样，截图也无法验证交互、无障碍或 API 行为。请把应用的相关检查与截图步骤一起保留。

## 排查流水线问题

**找不到 Chrome：** 确认运行器镜像包含浏览器，并且 `CHROME_PATH` 指向其可执行文件。

**导航失败或超时：** 确认截图进程能访问服务器，服务器使用预期的端口，并在截图开始前已就绪。页面导航的超时时间为 30 秒。

**出现意外的登录页面：** CLI 会启动全新的浏览器会话。它不会复用你的本地配置文件，也不提供 Cookie 注入。

**输出文件缺失：** 创建输出目录，检查命令的退出状态，并检查相对于 CI 工作目录的产物路径。

[CLI 参考指南](https://openscreenshot.app/zh-cn/blog/screenshot-cli/)介绍了参数和退出码。如果需要由人或智能体决定接下来检查哪个页面，请使用 [MCP 截图流程](https://openscreenshot.app/zh-cn/blog/screenshot-mcp-server/)。

## 继续阅读

[阅读文档](https://openscreenshot.app/zh-cn/docs/)、[浏览所有指南](https://openscreenshot.app/zh-cn/blog/)，或[获取截图帮助](https://openscreenshot.app/zh-cn/support/)。

---

Canonical page: https://openscreenshot.app/zh-cn/blog/screenshots-for-ci/