如何为文档自动生成产品截图

作者: Fraser Hardy

一个显示应用仪表盘的浏览器窗口,图表面板被相机取景框的四角框住,旁边堆叠着拍好的截图文件

您挪动了一个按钮。现在有 14 篇帮助文章显示的还是旧布局,而且得有人去登录、找到正确的演示账户、调整窗口大小,再把每张图重拍一遍。没人想干这个活,所以它就没人做,文档也就悄悄地开始说谎了。

解决办法是别再手动拍产品截图。要自动生成产品截图,请编写一个脚本:登录到预置了数据的演示账户,在固定尺寸的无头浏览器中访问每个页面,以 2 倍分辨率捕获特定元素(而不是整个屏幕),遮盖每次运行之间会变化的内容,并用固定的文件名保存每张图片。 然后每当界面发生变化时,在 CI 里运行这个脚本。Playwright 用大约 60 行代码就能完成这一切。

下面是我们实际会用的脚本、让输出保持一致的细节,以及仍然需要人来处理的部分。

为什么手动拍的产品截图会过时

手工制作的截图,失败的原因都很平淡:

截图自动化彻底解决了前三个问题,也让第四个问题有了解决的可能。如果您的文档整体都在偏离现状(而不只是图片),这个问题更宽泛的版本,已在每周发布版本时如何让文档保持最新中讲过。

动手写代码之前需要准备什么

要让自动化的文档截图可靠,需要三样东西。缺任何一样,输出都会不稳定、不好看。

1. 预置数据的演示账户

您的脚本需要登录一个永远看起来一样的账户:同样的公司名称、同样的 12 个项目、同样名字听上去合理的虚拟队友。编写一个种子脚本(scripts/seed-demo.ts,或任何适合您技术栈的名称),用来清空并重建这个账户。真实感很重要:满是“Test Project 1”和“asdf”的仪表盘,放在帮助文章里看起来像是坏了。

2. 为要捕获的元素设置稳定的选择器

您要对元素截图,所以需要一种可靠的方式来找到它们。来自 Tailwind 或 CSS-in-JS 的 CSS 类名经常变化。改为添加一个专用的属性:

<section data-docs="billing-summary">...</section>

它不花任何成本,能经受住重构,还能告诉每一位工程师:“这个元素出现在文档里,删除之前请三思。”

3. 一份截图清单

一份纯文本的清单,列出您文档中用到的每一张图片:哪个页面、哪个元素、要遮盖什么,以及输出的文件名。把它和脚本放在一起,保存在代码里。之后遇到“哪些截图展示了账单页面?”这个问题,这份清单也就是答案。

一份可用的 Playwright 截图脚本

Playwright 是目前做这件事的最佳工具。它驱动真实的 Chromium、Firefox 或 WebKit,可以只对单个元素截图,并且内置了遮罩和冻结动画的选项。

首先,登录一次并保存会话,这样每次截图运行都从已登录状态开始:

// scripts/docs-login.mjs
import { chromium } from 'playwright';

const BASE_URL = process.env.BASE_URL ?? 'http://localhost:3000';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto(`${BASE_URL}/login`);
await page.getByLabel('Email').fill(process.env.DEMO_EMAIL);
await page.getByLabel('Password').fill(process.env.DEMO_PASSWORD);
await page.getByRole('button', { name: 'Sign in' }).click();
await page.waitForURL('**/dashboard');
await page.context().storageState({ path: '.auth/demo.json' });
await browser.close();

然后是截图脚本本身:

// scripts/docs-screenshots.mjs
import { chromium } from 'playwright';
import { mkdir } from 'node:fs/promises';

const BASE_URL = process.env.BASE_URL ?? 'http://localhost:3000';
const OUT_DIR = 'docs/images';

const shots = [
  {
    name: 'dashboard-overview',
    path: '/dashboard',
    element: '[data-docs="overview-panel"]',
    mask: ['[data-docs="last-synced"]', '[data-docs="avatar"]'],
  },
  {
    name: 'billing-summary',
    path: '/settings/billing',
    element: '[data-docs="billing-summary"]',
  },
  {
    name: 'invite-teammate-dialog',
    path: '/settings/team',
    element: '[role="dialog"]',
    before: (page) => page.getByRole('button', { name: 'Invite teammate' }).click(),
  },
];

const browser = await chromium.launch();
const context = await browser.newContext({
  storageState: '.auth/demo.json',
  viewport: { width: 1280, height: 800 },
  deviceScaleFactor: 2,
  colorScheme: 'light',
  locale: 'en-US',
  timezoneId: 'America/New_York',
  reducedMotion: 'reduce',
});
const page = await context.newPage();

// Every "Updated 3 minutes ago" and date picker now shows the same moment.
await page.clock.setFixedTime(new Date('2026-03-02T10:00:00'));

await mkdir(OUT_DIR, { recursive: true });

for (const shot of shots) {
  await page.goto(BASE_URL + shot.path);
  if (shot.before) await shot.before(page);

  const target = page.locator(shot.element);
  await target.waitFor({ state: 'visible' });

  await target.screenshot({
    path: `${OUT_DIR}/${shot.name}.png`,
    animations: 'disabled',
    caret: 'hide',
    mask: (shot.mask ?? []).map((selector) => page.locator(selector)),
    maskColor: '#e3d4ff',
    // Hide things that should never appear in docs.
    style: '#chat-widget, .cookie-banner, .dev-toolbar { display: none !important; }',
  });

  console.log(`saved ${shot.name}.png`);
}

await browser.close();

对着您本地的应用,或者已预置演示账户的预发布环境副本,运行 node scripts/docs-login.mjs && node scripts/docs-screenshots.mjs。您会得到一个文件夹,里面是清晰的 PNG 图片,文件名与截图清单完全一致。

截图自动化流水线的四个阶段:预置演示数据,定义截图清单,在合并时或每晚于 CI 中运行,变化的图片会以可审阅的差异对比形式出现在文档中

让截图保持一致的设置

大部分价值都在少数几个选项里。下面解释每个选项为什么存在。

固定视口。1280x800 意味着布局每次都在相同的位置发生断点变化。选定一个尺寸,并在所有图片中坚持使用,这样您的帮助中心看上去才不会像一幅拼贴画。

deviceScaleFactor: 2。 这会以视网膜屏的密度渲染,因此 600 像素宽的元素会变成 1200 像素宽的图片。它在现代笔记本电脑和手机上看起来很清晰,在文章里则可以按一半大小显示。文件会变大;如果您在意这一点,可以用 oxipng 之类的优化工具处理,或转换成 WebP。

元素截图,而不是整页。 只截取账单摘要卡片的截图,能告诉读者该看哪里;整页截图则让他们去找。这也意味着侧边栏的改动不会影响您的账单图片,所以您只需要重新审阅真正发生变化的部分。

遮盖动态内容。 任何在两次运行之间、代码没有变化却不同的内容,都是噪音:相对时间戳、实时计数器、“3 人在线”、随机的头像颜色、轮换的每日小贴士。Playwright 的 mask 选项会在这些元素上盖一个纯色方块。优先从源头修正数据(预置的姓名、冻结的时钟),只遮盖您无法控制的部分。

冻结时钟、区域设置和时区。page.clock.setFixedTime 固定 Date.now(),因此“2 天后到期”永远显示同样的内容。区域设置和时区则能避免另一个区域的 CI 运行器把 3/2/2026 渲染成 02/03/2026。

关闭动画,隐藏光标。 一个渐入到一半的动画,或一个闪烁的光标,会在某次运行里出现,下一次又消失。

对比图:左边是原始截图,带有实时时间戳、真实的邮箱地址和随机头像;右边是同一张截图,这些区域已被遮盖,邮箱换成了演示数据

在 CI 中重新运行截图

一个需要您记得去运行的脚本,只比手动做稍好一点。把它放进 CI。

最简单的版本是:每次合并到 main(如果您的测试套件很慢,就改成每晚运行),启动应用,预置演示账户,运行脚本,如果有任何图片发生了变化,就创建一个拉取请求。Git 在 GitHub 上会并排显示图片的差异,所以审阅者只需扫一眼“billing-summary.png 已更改”,就能确认这是有意为之的变更。

# .github/workflows/docs-screenshots.yml
name: Docs screenshots
on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  capture:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npm run seed:demo
      - run: npm run start &
      - run: npx wait-on http://localhost:3000
      - run: node scripts/docs-login.mjs && node scripts/docs-screenshots.mjs
        env:
          DEMO_EMAIL: ${{ secrets.DOCS_DEMO_EMAIL }}
          DEMO_PASSWORD: ${{ secrets.DOCS_DEMO_PASSWORD }}
      - uses: peter-evans/create-pull-request@v6
        with:
          branch: docs/screenshots
          title: "Update docs screenshots"
          add-paths: docs/images

有一个实话实说的提醒:字体在 macOS 和 Linux 上的渲染略有差异。如果一些截图来自您的笔记本电脑,另一些来自 CI,那么每次运行都会“更改”那些其实没有变化的图片。只在一个地方生成它们(CI,或者在本地使用官方的 Playwright Docker 镜像),差异对比才会保持平静。

脚本化截图仍然不足的地方

这种方法很好,但仍然需要投入工作。请务实地看待它:

还有其他选择。Cypress 有 cy.screenshot(),如果您的团队本来就在用 Cypress,那就很好用。Puppeteer 层级更低,专注于 Chromium。shot-scraper 是 Playwright 的一个好用的命令行封装,适合您更愿意维护一份 YAML 文件而不是脚本的情况。对于一次性的营销截图,用 CleanShot X 这样的手动工具并保持一致的窗口大小,说实话也完全可以。当需要保持最新的图片超过几十张时,脚本化的路线才开始物有所值。

无需编写脚本,自动生成截图

这正是我们打造 Ellie Docs 要替您分担的部分。您连接一个 GitHub 代码仓库,Ellie 读取代码,梳理出您的功能和面向用户的页面。然后它在沙盒中运行您的应用,以测试用户身份登录,捕获已登录产品的真实截图,并直接放进它起草的帮助文章里。

Ellie Docs 文章编辑器,显示一篇已发布的“入门”文章,其中嵌入了自动捕获的应用新手引导页面截图,另有“截图”面板列出已捕获的图片

由于每篇文章都与它所描述的功能相关联,因此当某个合并的 PR 修改了其中一项功能时,就会针对相应的文章被标记出来,而您会在任何内容上线之前,先审阅建议的更新。您不需要维护截图清单或选择器文件。

一篇已发布的帮助中心文章,嵌入了产品“连接您的收件箱”页面的截图

如果您享受自己掌控 Playwright 脚本的过程,就继续保留它,这是个很好的配置。如果您更愿意让截图、围绕截图的文章以及后续维护都由别人替您处理,那就是 Ellie 所做的事。为这些图片配上文字,本身也是一门手艺,请参阅如何撰写人们真正会用的帮助中心文章。

常见问题

文档截图应该用什么分辨率? 在大约 1280 像素宽的固定视口中,以 2 倍(deviceScaleFactor: 2)捕获,然后按一半大小显示。这样既能在视网膜屏上得到清晰的图片,又不会让版面变得过大。

应该截整个页面,还是只截一部分? 通常只截一部分。裁剪到该步骤所涉及的元素,并保留少量周边背景,方便读者找到它。整页截图要少用,只用在“这是整体布局”的时刻。

如何避免截图里出现真实的客户数据? 永远不要从生产账户截图。使用预置了虚构姓名和 example.com 邮箱的演示账户,并遮盖您无法预置的内容,比如第三方小组件。

自动截图应该多久运行一次? 如果运行很快,就在每次合并到 main 时运行;如果不快,就每晚运行。关键在于,没人需要去记着它。

如果您希望由我们替您完成这件事,免费试用 Ellie Docs。连接一个代码仓库,您就能得到一个带有应用真实截图的帮助中心,无需绑定银行卡。