如何为文档自动生成产品截图
您挪动了一个按钮。现在有 14 篇帮助文章显示的还是旧布局,而且得有人去登录、找到正确的演示账户、调整窗口大小,再把每张图重拍一遍。没人想干这个活,所以它就没人做,文档也就悄悄地开始说谎了。
解决办法是别再手动拍产品截图。要自动生成产品截图,请编写一个脚本:登录到预置了数据的演示账户,在固定尺寸的无头浏览器中访问每个页面,以 2 倍分辨率捕获特定元素(而不是整个屏幕),遮盖每次运行之间会变化的内容,并用固定的文件名保存每张图片。 然后每当界面发生变化时,在 CI 里运行这个脚本。Playwright 用大约 60 行代码就能完成这一切。
下面是我们实际会用的脚本、让输出保持一致的细节,以及仍然需要人来处理的部分。
为什么手动拍的产品截图会过时
手工制作的截图,失败的原因都很平淡:
- 重做的成本高,所以人们一拖再拖。一次涉及侧边栏的改版,就可能让帮助中心里的每张图同时失效。
- 它们不一致。 有的是在 13 英寸笔记本上拍的,有的是在 4K 显示器上,有的是深色模式,有的角落里还露着浏览器扩展的图标。
- 它们会泄露真实数据。 某个人真实的收件箱、客户姓名、头像菜单里的真实邮箱地址。
- 没人知道哪些已经过时。“我们改了账单页面”和“这五张图展示的是账单页面”之间,没有任何关联。
截图自动化彻底解决了前三个问题,也让第四个问题有了解决的可能。如果您的文档整体都在偏离现状(而不只是图片),这个问题更宽泛的版本,已在每周发布版本时如何让文档保持最新中讲过。
动手写代码之前需要准备什么
要让自动化的文档截图可靠,需要三样东西。缺任何一样,输出都会不稳定、不好看。
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 图片,文件名与截图清单完全一致。
让截图保持一致的设置
大部分价值都在少数几个选项里。下面解释每个选项为什么存在。
固定视口。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 镜像),差异对比才会保持平静。
脚本化截图仍然不足的地方
这种方法很好,但仍然需要投入工作。请务实地看待它:
- 总得有人维护截图清单。 新增一个功能,就要有人为它添加截图、编写选择器,并决定要遮盖什么。删掉一个页面,脚本就会失败,直到有人把这一条移除。
- 它不知道图片该放在哪里。 脚本会更新
billing-summary.png,但它不知道哪些文章用到了这张图,也不知道图片周围的步骤是否仍然正确。 - 身份验证会很麻烦。 仅支持 SSO 的登录、魔法链接、双重验证,以及与第三方服务的 OAuth 连接,都需要变通的办法(通常的答案是一个仅用于测试的登录路由)。
- 它捕获的是状态,而不是故事。 多步骤的流程更适合用一段短视频来展示。我们在如何制作产品演示视频中讲了这一点。
还有其他选择。Cypress 有 cy.screenshot(),如果您的团队本来就在用 Cypress,那就很好用。Puppeteer 层级更低,专注于 Chromium。shot-scraper 是 Playwright 的一个好用的命令行封装,适合您更愿意维护一份 YAML 文件而不是脚本的情况。对于一次性的营销截图,用 CleanShot X 这样的手动工具并保持一致的窗口大小,说实话也完全可以。当需要保持最新的图片超过几十张时,脚本化的路线才开始物有所值。
无需编写脚本,自动生成截图
这正是我们打造 Ellie Docs 要替您分担的部分。您连接一个 GitHub 代码仓库,Ellie 读取代码,梳理出您的功能和面向用户的页面。然后它在沙盒中运行您的应用,以测试用户身份登录,捕获已登录产品的真实截图,并直接放进它起草的帮助文章里。

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

如果您享受自己掌控 Playwright 脚本的过程,就继续保留它,这是个很好的配置。如果您更愿意让截图、围绕截图的文章以及后续维护都由别人替您处理,那就是 Ellie 所做的事。为这些图片配上文字,本身也是一门手艺,请参阅如何撰写人们真正会用的帮助中心文章。
常见问题
文档截图应该用什么分辨率?
在大约 1280 像素宽的固定视口中,以 2 倍(deviceScaleFactor: 2)捕获,然后按一半大小显示。这样既能在视网膜屏上得到清晰的图片,又不会让版面变得过大。
应该截整个页面,还是只截一部分? 通常只截一部分。裁剪到该步骤所涉及的元素,并保留少量周边背景,方便读者找到它。整页截图要少用,只用在“这是整体布局”的时刻。
如何避免截图里出现真实的客户数据?
永远不要从生产账户截图。使用预置了虚构姓名和 example.com 邮箱的演示账户,并遮盖您无法预置的内容,比如第三方小组件。
自动截图应该多久运行一次? 如果运行很快,就在每次合并到 main 时运行;如果不快,就每晚运行。关键在于,没人需要去记着它。
如果您希望由我们替您完成这件事,免费试用 Ellie Docs。连接一个代码仓库,您就能得到一个带有应用真实截图的帮助中心,无需绑定银行卡。