screenshot-local

本地截图 — shot-scraper

概述

使用 shot-scraper 截取本地开发服务器和静态 HTML 文件的截图。shot-scraper 是通过 pipx 安装的 Playwright 封装工具。只要涉及多张图片，就优先使用已提交的 shots.yml，而不是临时命令——仓库可以重新生成的截图会保持最新，而手动截图会在界面发生变化时立刻过时。

安装

pipx install shot-scraper     # brew install pipx / apt install pipx first
shot-scraper install          # downloads Chromium
shot-scraper --version

安装后出现 command not found，说明 pipx 不在 PATH 中：运行 pipx ensurepath，然后重新打开 shell。

命令概览

子命令	用途
shot-scraper URL	截取一张截图
shot-scraper multi shots.yml	根据 YAML 批量截图
shot-scraper pdf URL	导出 PDF
shot-scraper auth URL auth.json	保存登录会话以供重复使用
shot-scraper accessibility URL	将无障碍树导出为 JSON

标志	用途
-o	输出文件名（- 表示标准输出）
-w / -h	视口宽度 / 高度——省略 -h 可截取整页
-s / --selector-all	截取第一个 / 所有匹配的元素
-p	选择器周围的内边距，单位为 px
--retina	2 倍设备像素比
--quality N	以质量等级 N 保存为 JPEG
--wait N / --wait-for "expr"	等待 N 毫秒 / 直到 JS 表达式为真
-j "js"	截图前运行 JS——关闭模态框、预置状态
-a auth.json	复用已保存的身份验证上下文
-i / --devtools	打开浏览器，以交互方式调试截图

所有标志和 YAML 键：reference/COMMAND-REFERENCE.md。上游文档：https://shot-scraper.datasette.io/.

用户未指定尺寸时，使用以下尺寸：

用途	宽度	高度
README 主图	1280	800
文档截图	1200	省略（整页）
社交媒体 / OG 图片	1200	630
手机 / 平板	375 / 768	812 / 1024

示例调用

临时截图：

shot-scraper http://localhost:3000 -o homepage.png
shot-scraper index.html -o preview.png
shot-scraper http://localhost:3000 -w 1200 -h 630 -o og.png
shot-scraper http://localhost:3000 -s ".hero" -p 20 --retina -o [email protected]
shot-scraper http://localhost:3000 --wait-for "document.querySelector('.loaded')" -o app.png

为项目设置截图：读取其路由器配置、页面文件或导航，找出实际路由和开发服务器端口，选择值得记录的状态（内容已填充的页面优于空页面），编写 shots.yml，然后运行 shot-scraper multi shots.yml。首次运行可能需要调整等待时间或选择器——打开生成的图片，确认显示的是预期界面后，再报告任务已完成。

✅ 指定明确尺寸，等待 SPA 加载，将输出保存到目录中，并移除临时浏览器界面元素：

- url: http://localhost:3000
  output: screenshots/homepage.png
  width: 1280
  height: 800

- url: http://localhost:3000/dashboard
  output: screenshots/dashboard.png
  width: 1280
  height: 900
  wait: 2000
  javascript: |
    document.querySelector('.toast-notification')?.remove()

❌ 将加载动画截入一个依赖机器环境自动命名、并输出到仓库根目录的文件：

- url: http://localhost:3000/dashboard

✅ 固定尺寸的 OG 图片——同时设置 -w 和 -h，省略 --retina：

shot-scraper http://localhost:3000 -w 1200 -h 630 -o og.png

❌ 对指定尺寸使用 --retina——会生成 2400×1260 的文件，无法放入需要 1200×630 的位置；直到卡片渲染错误前，这个问题都不会显现：

shot-scraper http://localhost:3000 -w 1200 -h 630 --retina -o og.png

✅ 截取整页文档——有意省略 -h，使高度随内容变化：

shot-scraper http://localhost:3000/docs -w 1200 -o docs.png

❌ 在文档页面上固定设置 -h——会截掉 800px 以下的所有内容，让缺失的章节看起来像是从未写过：

shot-scraper http://localhost:3000/docs -w 1200 -h 800 -o docs.png

各类项目的入门配置——SPA、Storybook、响应式尺寸扫描、静态网站、身份验证：reference/TEMPLATES.md。

故障模式

• “Connection refused” — 没有进程在该端口提供服务。启动开发服务器（npm run dev &），用 curl -I http://localhost:3000 确认，或通过 YAML server: 键将生命周期交给 shot-scraper。
• 空白页面或加载转圈 — 截图时 SPA 尚未完成水合。建议使用 --wait-for "document.querySelector('.content')"，而不是固定的 --wait 3000，因为在性能良好的笔记本电脑上调好的固定等待时间，在较慢的 CI 运行器上会失效。
• 图像为空或元素不对 — 选择器没有匹配到任何内容，或者内容在首屏下方延迟加载。用 -i 重现并检查实时页面，不要靠猜测换另一个选择器。
• 繁重页面超时 — 增大 --timeout 30000。默认超时时间比冷启动的 Next.js 开发服务器首次请求时编译路由所需的时间更短。
• 本地通过，CI 失败 — 运行器从未执行 shot-scraper install，因此没有浏览器引擎。将安装引擎作为独立的 CI 步骤。

注意事项

• shot-scraper install 是第二个独立步骤。 单独执行 pipx install shot-scraper 不会安装浏览器引擎，因此在新机器上首次截图会失败。
• --quality 无论输出扩展名如何，都会将格式切换为 JPEG。 --quality 80 -o hero.png 会将 JPEG 字节写入名为 .png 的文件（已在 1.9.1 中验证）。需要真正的 PNG 时，请省略 --quality。
• --retina 会将输出像素翻倍，而不会改变布局。 -w 1200 --retina 会生成宽 2400px 的文件，这会破坏 1200×630 OG 图像这类固定尺寸的目标。将其用于 README 插图，而不是规格指定的尺寸。
• shots.yml 中每次截图单独设置的 auth: 键会被静默忽略 — 截图仍会成功，只是处于未登录状态，因此看起来像是页面损坏，而不是缺少身份验证。请改为向整个批次传递身份验证信息：shot-scraper multi shots.yml -a auth.json。
• 省略 -h 会使高度随内容变化，因此同一路由的两次截图尺寸可能不同。对前后对比截图，请设置明确的 -h。
• YAML server: 进程会贯穿整个 multi 运行过程，并在结束时关闭（--leave-server 会使其保持运行）。一个 server: 条目即可覆盖整个批次；在每次截图中重复设置不会启动更多服务。
• 整页截图会掩盖小缺陷。 从宽 1200px 的图像中判断 12px 标签、对比度问题或被裁切的单元格，只能靠猜。使用 -s <selector>（加上 -p 内边距）截取区域，或在查看前裁剪 PNG — 模型近距离查看局部区域时，视觉判断效果最好。
• 截图不适合直接做差异比较。 抗锯齿和字体渲染会使 PNG 差异充满噪点，因此应将 shot-scraper 用于文档素材；如果目标是设置回归检查，则应使用 Percy、Chromatic 或 Playwright 的 toHaveScreenshot。

CI

在源代码变更时，通过 GitHub Actions 工作流重新生成截图并提交回仓库 — 完整工作流、成本控制和 server: 键模式详见：reference/CI-INTEGRATION.md。