screenshot-local

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Screenshot Local - Capture Project Screenshots with shot-scraper

本地截图工具 - 使用shot-scraper捕获项目截图

Overview

概述

Capture screenshots of local development projects using shot-scraper installed globally via pipx. Turn localhost URLs and local HTML files into PNGs, JPEGs, and PDFs for documentation, READMEs, and design reviews.

Core principle: Screenshots should be reproducible from a single command or YAML config, not manual screen captures. Version-control your screenshot configs alongside your code.

通过pipx全局安装的shot-scraper工具，捕获本地开发项目的截图。将localhost网址和本地HTML文件转换为PNG、JPEG和PDF格式，用于文档编写、README制作和设计评审。

核心原则： 截图应通过单一命令或YAML配置可重复生成，而非手动截图。将截图配置与代码一起进行版本控制。

When to Use

适用场景

Use this skill when:

Capturing screenshots of a local dev server for docs or README
Generating screenshots of multiple pages/states in batch
Documenting UI changes or new features visually
Creating before/after comparisons during refactoring
Automating screenshot generation in CI/CD

Avoid when:

Recording terminal/CLI output (use
```
record-tui
```
with VHS instead)
Capturing non-web content (use native screenshot tools)
Scraping third-party websites (shot-scraper can do it, but this skill focuses on local projects)

在以下场景使用本技能：

为文档或README捕获本地开发服务器的截图
批量生成多个页面/状态的截图
通过截图记录UI变更或新功能
在重构过程中创建前后对比图
在CI/CD中自动化截图生成

避免在以下场景使用：

录制终端/CLI输出（请使用VHS搭配
```
record-tui
```
）
捕获非Web内容（使用原生截图工具）
爬取第三方网站（shot-scraper支持此功能，但本技能聚焦本地项目）

Prerequisites

前置条件

Install shot-scraper globally via pipx:

bash

undefined

通过pipx全局安装shot-scraper：

bash

undefined

Install pipx if needed

若需要先安装pipx

brew install pipx # macOS

or: apt install pipx / pip install pipx

或：apt install pipx / pip install pipx

Install shot-scraper globally

全局安装shot-scraper

pipx install shot-scraper

Install the browser engine (Chromium by default)

安装浏览器引擎（默认Chromium）

shot-scraper install


**Verify:** `shot-scraper --version`

**Alternative browsers:**
```bash
shot-scraper install -b firefox
shot-scraper install -b webkit

shot-scraper install


**验证安装：** `shot-scraper --version`

**可选浏览器：**
```bash
shot-scraper install -b firefox
shot-scraper install -b webkit

Phase 1: Plan the Screenshots

阶段1：规划截图

Before capturing, answer these questions:

What are you capturing? — localhost URL, local HTML file, or built static site
Which pages/states? — Single page, multiple routes, or specific UI states
What dimensions? — Match your target display context
Any interaction needed? — Click buttons, fill forms, dismiss modals before capture

Recommended dimensions by use case:

Use Case	Width	Height	Format
README hero image	1280	800	PNG
Docs screenshot	1200	auto	PNG
Social/OG image	1200	630	PNG
Mobile viewport	375	812	PNG
Tablet viewport	768	1024	PNG
Full page capture	1280	(omit)	PNG

捕获前，请先明确以下问题：

要捕获什么内容？ —— localhost网址、本地HTML文件，或构建后的静态站点
要捕获哪些页面/状态？ —— 单个页面、多个路由，或特定UI状态
截图尺寸？ —— 匹配目标展示场景
是否需要交互？ —— 捕获前点击按钮、填写表单、关闭弹窗

按场景推荐尺寸：

使用场景	宽度	高度	格式
README首图	1280	800	PNG
文档截图	1200	自动	PNG
社交/OG图片	1200	630	PNG
移动端视口	375	812	PNG
平板端视口	768	1024	PNG
整页捕获	1280	（留空）	PNG

Phase 2: Capture Screenshots

阶段2：捕获截图

Single Screenshot

单张截图

Capture a localhost page:

bash

shot-scraper http://localhost:3000 -o homepage.png

Capture a local HTML file:

bash

shot-scraper index.html -o preview.png

With custom dimensions:

bash

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

Retina (2x resolution):

bash

shot-scraper http://localhost:3000 --retina -o homepage-retina.png

Capture a specific element:

bash

shot-scraper http://localhost:3000 -s ".hero-section" -o hero.png
shot-scraper http://localhost:3000 -s "#main-nav" --padding 10 -o nav.png

Wait for dynamic content:

bash

undefined

捕获localhost页面：

bash

shot-scraper http://localhost:3000 -o homepage.png

捕获本地HTML文件：

bash

shot-scraper index.html -o preview.png

自定义尺寸：

bash

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

视网膜分辨率（2x）：

bash

shot-scraper http://localhost:3000 --retina -o homepage-retina.png

捕获特定元素：

bash

shot-scraper http://localhost:3000 -s ".hero-section" -o hero.png
shot-scraper http://localhost:3000 -s "#main-nav" --padding 10 -o nav.png

等待动态内容加载：

bash

undefined

Wait fixed time (ms)

固定等待时长（毫秒）

shot-scraper http://localhost:3000 --wait 2000 -o page.png

Wait for JS condition

等待JS条件满足

shot-scraper http://localhost:3000 --wait-for "document.querySelector('.loaded')" -o page.png


**Execute JS before capture (dismiss modals, set state):**
```bash
shot-scraper http://localhost:3000 \
  -j "document.querySelector('.cookie-banner')?.remove()" \
  -o clean-homepage.png

shot-scraper http://localhost:3000 --wait-for "document.querySelector('.loaded')" -o page.png


**捕获前执行JS（关闭弹窗、设置状态）：**
```bash
shot-scraper http://localhost:3000 \
  -j "document.querySelector('.cookie-banner')?.remove()" \
  -o clean-homepage.png

Essential Options

核心参数选项

Flag	Example	Purpose
`-o`	`-o hero.png`	Output filename
`-w`	`-w 1280`	Viewport width (default: 1280)
`-h`	`-h 800`	Viewport height (omit for full page)
`-s`	`-s ".card"`	CSS selector to capture
`--selector-all`	`--selector-all ".card"`	All matching elements
`-p`	`-p 10`	Padding around selector (px)
`--retina`	`--retina`	2x device pixel ratio
`--quality`	`--quality 80`	Save as JPEG with quality
`--wait`	`--wait 2000`	Wait ms after page load
`--wait-for`	`--wait-for "expr"`	Wait until JS returns true
`-j`	`-j "js code"`	Execute JS before screenshot
`-b`	`-b firefox`	Browser (chromium/firefox/webkit)
`--omit-background`	`--omit-background`	Transparent background (PNG)
`--timeout`	`--timeout 10000`	Failure timeout (ms)

For the complete flag reference, see Command Reference.

参数	示例	用途
`-o`	`-o hero.png`	指定输出文件名
`-w`	`-w 1280`	视口宽度（默认：1280）
`-h`	`-h 800`	视口高度（留空则捕获整页）
`-s`	`-s ".card"`	要捕获的CSS选择器
`--selector-all`	`--selector-all ".card"`	捕获所有匹配元素
`-p`	`-p 10`	选择器元素的内边距（像素）
`--retina`	`--retina`	2x设备像素比
`--quality`	`--quality 80`	以指定质量保存为JPEG
`--wait`	`--wait 2000`	页面加载后等待时长（毫秒）
`--wait-for`	`--wait-for "expr"`	等待JS表达式返回true
`-j`	`-j "js code"`	截图前执行JS代码
`-b`	`-b firefox`	指定浏览器（chromium/firefox/webkit）
`--omit-background`	`--omit-background`	透明背景（仅PNG格式）
`--timeout`	`--timeout 10000`	失败超时时间（毫秒）

完整参数参考，请查看**命令参考文档**。

Batch Screenshots with YAML

使用YAML批量截图

Create a

shots.yml

for capturing multiple pages:

yaml

undefined

创建

shots.yml

配置文件，实现多页面批量捕获：

yaml

undefined

shots.yml

url: http://localhost:3000 output: screenshots/homepage.png width: 1280 height: 800
url: http://localhost:3000/about output: screenshots/about.png width: 1280
url: http://localhost:3000/dashboard output: screenshots/dashboard.png width: 1280 height: 900 wait: 2000 javascript: | document.querySelector('.loading-spinner')?.remove()
url: http://localhost:3000 output: screenshots/mobile-home.png width: 375 height: 812


**Run the batch:**
```bash
shot-scraper multi shots.yml

url: http://localhost:3000 output: screenshots/homepage.png width: 1280 height: 800
url: http://localhost:3000/about output: screenshots/about.png width: 1280
url: http://localhost:3000/dashboard output: screenshots/dashboard.png width: 1280 height: 900 wait: 2000 javascript: | document.querySelector('.loading-spinner')?.remove()
url: http://localhost:3000 output: screenshots/mobile-home.png width: 375 height: 812


**执行批量截图：**
```bash
shot-scraper multi shots.yml

Advanced YAML Keys

高级YAML配置项

yaml

- url: http://localhost:3000/form
  output: screenshots/form-filled.png
  width: 1200
  javascript: |
    document.querySelector('#name').value = 'Jane Doe';
    document.querySelector('#email').value = 'jane@example.com';
  wait: 500
  selector: ".form-container"
  padding: 20
  retina: true

Supported YAML keys:

url

output

width

height

quality

wait

wait_for

selector

selectors

selector_all

padding

javascript

js_selector

retina

omit_background

yaml

- url: http://localhost:3000/form
  output: screenshots/form-filled.png
  width: 1200
  javascript: |
    document.querySelector('#name').value = 'Jane Doe';
    document.querySelector('#email').value = 'jane@example.com';
  wait: 500
  selector: ".form-container"
  padding: 20
  retina: true

支持的YAML配置项：

url

output

width

height

quality

wait

wait_for

selector

selectors

selector_all

padding

javascript

js_selector

retina

omit_background

Phase 3: Smart Config Generation

阶段3：智能配置生成

When asked to generate a screenshot config for a project, follow this process:

当需要为项目生成截图配置时，请遵循以下流程：

Step 1: Analyze the Project

步骤1：分析项目

Read the project to understand:

Routes/pages — Check router config, page files, or navigation
Key UI states — Loading, empty, populated, error states
Important components — Hero sections, dashboards, forms
Port — What port does the dev server run on

了解项目的以下信息：

路由/页面 —— 查看路由配置、页面文件或导航菜单
关键UI状态 —— 加载中、空状态、已填充、错误状态
重要组件 —— 首屏区域、仪表盘、表单
端口 —— 开发服务器运行的端口

Step 2: Generate shots.yml

步骤2：生成shots.yml

Build a YAML config covering the project's key screens:

bash

undefined

构建覆盖项目关键页面的YAML配置：

bash

undefined

Validate by running

运行命令验证配置

shot-scraper multi shots.yml

undefined

shot-scraper multi shots.yml

undefined

Step 3: Iterate

步骤3：迭代优化

Review screenshots, adjust timing and selectors, re-run.

查看截图效果，调整等待时长和选择器，重新执行截图。

Phase 4: Optimize Output

阶段4：优化输出

File Size Reduction

文件体积压缩

Use JPEG for photos/complex UIs:

bash

shot-scraper http://localhost:3000 --quality 85 -o page.jpg

Use PNG for UI with text/sharp edges (default).

Transparent backgrounds (for overlaying on docs):

bash

shot-scraper http://localhost:3000 -s ".component" --omit-background -o widget.png

针对照片/复杂UI使用JPEG格式：

bash

shot-scraper http://localhost:3000 --quality 85 -o page.jpg

针对含文字/锐利边缘的UI使用PNG格式（默认）。

透明背景（用于文档叠加）：

bash

shot-scraper http://localhost:3000 -s ".component" --omit-background -o widget.png

Consistency Tips

保持一致性技巧

Always set explicit
```
width
```
— default 1280 is fine but be intentional
Omit
```
height
```
for full-page captures, set it for fixed viewport
Use
```
--retina
```
for README images viewed on high-DPI screens
Add
```
--wait
```
for SPAs that hydrate client-side
Use
```
javascript
```
to dismiss cookie banners, tooltips, or modals
Use
```
selector
```
+
```
padding
```
to capture specific components cleanly

始终显式设置
```
width
```
—— 默认1280即可，但需按需调整
捕获整页时留空
```
height
```
，固定视口时设置该参数
针对高DPI屏幕查看的README图片，使用
```
--retina
```
参数
针对客户端渲染的SPA，添加
```
--wait
```
参数
使用
```
javascript
```
参数关闭Cookie弹窗、提示框或模态框
结合
```
selector
```
+
```
padding
```
参数，干净地捕获特定组件

Phase 5: CI/CD Integration

阶段5：CI/CD集成

GitHub Actions

GitHub Actions示例

yaml

name: Update Screenshots
on:
  push:
    branches: [main]
    paths: ["src/**", "shots.yml"]

jobs:
  screenshots:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install shot-scraper
        run: |
          pip install shot-scraper
          shot-scraper install

      - name: Capture screenshots
        run: |
          npm ci && npm run dev &
          sleep 5
          shot-scraper multi shots.yml

      - name: Commit updated screenshots
        uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "docs: update screenshots"
          file_pattern: "screenshots/*.png"

Tip: Use the

server

key in YAML to auto-start a dev server — see Templates.

yaml

name: Update Screenshots
on:
  push:
    branches: [main]
    paths: ["src/**", "shots.yml"]

jobs:
  screenshots:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install shot-scraper
        run: |
          pip install shot-scraper
          shot-scraper install

      - name: Capture screenshots
        run: |
          npm ci && npm run dev &
          sleep 5
          shot-scraper multi shots.yml

      - name: Commit updated screenshots
        uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "docs: update screenshots"
          file_pattern: "screenshots/*.png"

提示： 在YAML中使用

server

配置项自动启动开发服务器 —— 查看**模板文档**。

Examples

示例

Good: Well-Structured Screenshot Config

规范示例：结构清晰的截图配置

<Good>

yaml

undefined

<Good>

yaml

undefined

shots.yml — explicit dimensions, proper waits, organized output

shots.yml —— 明确尺寸、合理等待、输出有序

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/settings output: screenshots/settings.png width: 1280 selector: ".settings-panel" padding: 20
url: http://localhost:3000 output: screenshots/mobile-home.png width: 375 height: 812


</Good>

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/settings output: screenshots/settings.png width: 1280 selector: ".settings-panel" padding: 20
url: http://localhost:3000 output: screenshots/mobile-home.png width: 375 height: 812


</Good>

Bad: Common Mistakes

反例：常见错误配置

<Bad>

yaml

undefined

<Bad>

yaml

undefined

No output specified — shot-scraper auto-names from URL, messy results

未指定输出文件名 —— shot-scraper自动从URL命名，结果混乱

url: http://localhost:3000

url: http://localhost:3000

No width — relies on default, inconsistent across machines

未指定宽度 —— 依赖默认值，不同机器结果不一致

url: http://localhost:3000/about output: about.png

url: http://localhost:3000/about output: about.png

No wait for SPA — captures loading spinner instead of content

SPA未设置等待 —— 捕获到加载动画而非实际内容

url: http://localhost:3000/dashboard output: dashboard.png

url: http://localhost:3000/dashboard output: dashboard.png

Screenshot directory not organized

截图目录未规划 —— 文件分散

url: http://localhost:3000/settings output: settings.png


</Bad>

url: http://localhost:3000/settings output: settings.png


</Bad>

Good: Capturing Specific Components

规范示例：捕获特定组件

<Good>

bash

undefined

<Good>

bash

undefined

Hero section with padding for breathing room

首屏区域添加内边距，预留呼吸空间

shot-scraper http://localhost:3000 -s ".hero" -p 20 -o docs/hero.png

Navigation in retina for crisp text

导航栏使用视网膜分辨率，保证文字清晰

shot-scraper http://localhost:3000 -s "nav" --retina -o docs/nav.png

Form with pre-filled data via JS

通过JS预填充表单数据后捕获

shot-scraper http://localhost:3000/contact
-j "document.querySelector('#name').value = 'Jane Doe'"
-s ".contact-form" -p 10 -o docs/form.png


</Good>

shot-scraper http://localhost:3000/contact
-j "document.querySelector('#name').value = 'Jane Doe'"
-s ".contact-form" -p 10 -o docs/form.png


</Good>

Bad: Component Capture Anti-Patterns

反例：组件捕获的不良实践

<Bad>

bash

undefined

<Bad>

bash

undefined

No selector — captures entire page when you only need one section

未指定选择器 —— 仅需单个区域却捕获了整页

shot-scraper http://localhost:3000 -o hero.png

No padding — element cropped tight, looks cramped in docs

未设置内边距 —— 元素被紧密裁剪，在文档中显得拥挤

shot-scraper http://localhost:3000 -s ".hero" -o hero.png

No wait — dynamic component hasn't rendered yet

未设置等待 —— 动态组件尚未渲染完成

shot-scraper http://localhost:3000 -s ".chart" -o chart.png


</Bad>

shot-scraper http://localhost:3000 -s ".chart" -o chart.png


</Bad>

Troubleshooting

故障排查

Problem: Screenshot shows blank page or loading spinner

问题：截图显示空白页面或加载动画

Cause: SPA hasn't hydrated or async data hasn't loaded.

Solution:

bash

undefined

原因： SPA未完成渲染或异步数据未加载。

解决方案：

bash

undefined

Fixed wait

固定等待时长

shot-scraper http://localhost:3000 --wait 3000 -o page.png

Wait for specific element

等待特定元素出现

shot-scraper http://localhost:3000 --wait-for "document.querySelector('.content')" -o page.png

undefined

shot-scraper http://localhost:3000 --wait-for "document.querySelector('.content')" -o page.png

undefined

Problem: "Connection refused" on localhost

问题：localhost连接被拒绝

Cause: Dev server isn't running or is on a different port.

Solution:

Start your dev server first:
```
npm run dev &
```
Verify the port:
```
curl -I http://localhost:3000
```
Or use the
```
server
```
key in YAML to auto-start it

原因： 开发服务器未启动或端口不一致。

解决方案：

先启动开发服务器：
```
npm run dev &
```
验证端口：
```
curl -I http://localhost:3000
```
或在YAML中使用
```
server
```
配置项自动启动服务器

Problem: Screenshot dimensions don't match expectations

问题：截图尺寸不符合预期

Cause: Height omitted (captures full page) or retina not accounted for.

Solution:

Set explicit
```
-h
```
for fixed viewport
Omit
```
-h
```
intentionally for full-page capture
```
--retina
```
doubles pixel dimensions (1280w becomes 2560px image)

原因： 留空了height（捕获整页）或未考虑视网膜分辨率。

解决方案：

为固定视口设置显式
```
-h
```
参数
若需捕获整页，有意留空
```
-h
```
```
--retina
```
参数会将像素尺寸翻倍（1280宽度变为2560px图片）

Problem: shot-scraper command not found

问题：shot-scraper命令未找到

Cause: Not installed or pipx PATH not configured.

Solution:

bash

pipx install shot-scraper
pipx ensurepath      # Add pipx bin to PATH
shot-scraper install # Install browser engine

原因： 未安装或pipx路径未配置。

解决方案：

bash

pipx install shot-scraper
pipx ensurepath      # 将pipx的bin目录添加到PATH
shot-scraper install # 安装浏览器引擎

Problem: Elements missing from screenshot

问题：截图中缺少元素

Cause: CSS selector wrong, element behind a modal, or lazy-loaded content.

Solution:

bash

undefined

原因： CSS选择器错误、元素被模态框遮挡，或为懒加载内容。

解决方案：

bash

undefined

Use --interactive to debug visually

使用--interactive参数可视化调试

shot-scraper http://localhost:3000 -i

Use --devtools for inspector

使用--devtools参数打开调试器

shot-scraper http://localhost:3000 --devtools

undefined

shot-scraper http://localhost:3000 --devtools

undefined

Integration

技能搭配

This skill pairs with:

record-tui — For terminal app recordings (use VHS for CLIs, shot-scraper for web UIs)
track-session — Track screenshot iteration progress
git-worktree — Compare screenshots across branches

Useful alongside:

shot-scraper — The screenshot tool
shot-scraper-template — GitHub Actions template
pipx — Global Python app installer

本技能可与以下技能搭配使用：

record-tui —— 录制终端应用（CLI使用VHS，Web UI使用shot-scraper）
track-session —— 跟踪截图迭代进度
git-worktree —— 对比不同分支的截图

相关工具：

shot-scraper —— 截图工具
shot-scraper-template —— GitHub Actions模板
pipx —— Python应用全局安装工具

Quick Reference

快速参考

bash

undefined

bash

undefined

Single screenshot

单张截图

shot-scraper http://localhost:3000 -o page.png

With dimensions

指定尺寸

shot-scraper http://localhost:3000 -w 1280 -h 800 -o page.png

Specific element

捕获特定元素

shot-scraper http://localhost:3000 -s ".hero" -p 10 -o hero.png

Retina

视网膜分辨率

shot-scraper http://localhost:3000 --retina -o page@2x.png

Local HTML file

本地HTML文件

shot-scraper index.html -o preview.png

Batch from YAML

YAML批量截图

shot-scraper multi shots.yml

Interactive debugging

交互式调试

shot-scraper http://localhost:3000 -i

PDF export

导出PDF

shot-scraper pdf http://localhost:3000 -o page.pdf

undefined

shot-scraper pdf http://localhost:3000 -o page.pdf

undefined

Deep Reference

深度参考

For detailed guides, load these files when needed:

Command Reference — All shot-scraper commands, flags, and subcommands
Templates — Copy-paste YAML configs for common project types

Only load these when specifically needed to save context.

如需详细指南，请查看以下文档：

命令参考文档 —— shot-scraper的所有命令、参数和子命令
模板文档 —— 可直接复制的常见项目YAML配置

仅在需要时加载这些文档，以节省上下文资源。

References

参考链接

shot-scraper — Official repository
shot-scraper documentation — Full docs
shot-scraper-template — GitHub Actions template
pipx — Global Python app installer
Simon Willison's blog — Author's posts on shot-scraper

shot-scraper —— 官方仓库
shot-scraper官方文档 —— 完整文档
shot-scraper-template —— GitHub Actions模板
pipx —— Python应用全局安装工具
Simon Willison的博客 —— 作者关于shot-scraper的文章