# Screenshot Local - 使用 shot-scraper 捕获项目屏幕截图 ## 概述使用通过 pipx 在全球安装的 [shot-scraper]() 捕获本地开发项目的屏幕截图。将本地主机 URL 和本地 HTML 文件转换为 PNG、JPEG 和 PDF，以用于文档、自述文件和设计评审。 **核心原则：** 屏幕截图应该可以从单个命令或 YAML 配置中重现，而不是手动屏幕截图。对屏幕截图配置和代码进行版本控制。 ## 何时使用 **在以下情况下使用此技能：** * 捕获本地开发服务器的屏幕截图以用于文档或自述文件 * 批量生成多个页面/状态的截图 * 直观地记录 UI 更改或新功能 * 在重构期间创建前后比较 * 在 CI/CD 中自动生成屏幕截图 **避免以下情况：** * 录制终端/CLI 输出（使用带有 VHS 的 `record-tui` 代替） * 捕获非网页内容（使用原生截图工具） * 抓取第三方网站（shot-scraper可以做到，但这个技能主要针对本地项目） ## 先决条件 **通过 pipx 全局安装 shot-scraper:** # 如果需要安装pipx 酿造安装 pipx # macOS # 或者：apt install pipx / pip install pipx # 全局安装 shot-scraper pipx 安装 shot-scraper # 安装浏览器引擎（默认为Chromium）快照刮刀安装 **验证：** `shot-scraper --version` **替代浏览器：** shot-scraper 安装 -b firefox shot-scraper 安装 -b webkit ## 第 1 阶段：规划屏幕截图在捕获之前，请回答以下问题： 1. **您要捕获什么？** — 本地主机 URL、本地 HTML 文件或构建的静态站点 2. **哪些页面/状态？** — 单页面、多路由或特定 UI 状态 3. **什么尺寸？** — 匹配您的目标显示环境 4. **需要任何交互吗？** — 在捕获之前单击按钮、填写表单、关闭模态框 **按使用案例推荐的尺寸：** 使用案例|宽度|身高|格式 ---|---|---|--- 自述文件英雄形象 | 1280 | 1280 800 |巴布亚新几内亚文档截图 | 1200 | 1200汽车 |巴布亚新几内亚社交/OG图像| 1200 | 1200 630 | 630巴布亚新几内亚移动视口 | 375 | 375 812 | 812巴布亚新几内亚平板电脑视口 | 768 | 768 1024 | 1024巴布亚新几内亚全页捕获 | 1280 | 1280 （省略）|巴布亚新几内亚 ## 第 2 阶段：捕获屏幕截图 ### 单张截图 **捕获本地主机页面：** shot-scraper http://localhost:3000 -o homepage.png **捕获本地 HTML 文件：** shot-scraper index.html -o Preview.png **具有自定义尺寸：** shot-scraper http://localhost:3000 -w 1200 -h 800 -o homepage.png **视网膜（2 倍分辨率）：** shot-scraper http://localhost:3000 --retina -o homepage-retina.png **捕获特定元素：** shot-scraper http://localhost:3000 -s ".hero-section" -o Hero.png shot-scraper http://localhost:3000 -s "#main-nav" --padding 10 -o nav.png **等待动态内容：** # 等待固定时间(ms) shot-scraper http://localhost:3000 --wait 2000 -o page.png # 等待JS条件 shot-scraper http://localhost:3000 --wait-for "document.querySelector('.loaded')" -o page.png **在捕获之前执行JS（关闭模态，设置状态）：** shot-scraper http://localhost:3000 \ -j "document.querySelector('.cookie-banner')?.remove()" \ -o 干净主页.png ### 基本选项旗帜|示例|目的 ---|---|--- `-o` | `-o 英雄.png` |输出文件名 `-w` | `-w 1280` |视口宽度（默认：1280） `-h` | `-h 800` |视口高度（整页省略） `-s` | `-s ".card"` |要捕获的 CSS 选择器 `--selector-all` | `--selector-all ".card"` |所有匹配元素 `-p` | `-p 10` |选择器周围的填充（px） `--视网膜` | `--视网膜` | 2 倍设备像素比 `--质量` | `--质量80` |保存为 JPEG 质量 `--等待` | `--等待 2000` |页面加载后等待毫秒 `--等待` | `--等待“expr”` |等待JS返回true `-j` | `-j "js 代码"` |截图前执行JS `-b` | `-b 火狐` |浏览器（铬/火狐/webkit） `--省略背景` | `--省略背景` |透明背景（PNG） `--超时` | `--超时 10000` |失败超时（毫秒）有关完整的标志参考，请参阅 **[命令参考]()**。 ### 使用 YAML 批量截图创建一个用于捕获多个页面的“shots.yml”： # 镜头.yml - 网址：http://localhost:3000 输出：截图/homepage.png 宽度：1280 高度：800 - 网址：http://localhost:3000/about 输出：截图/about.png 宽度：1280 - 网址：http://localhost:3000/dashboard 输出：截图/dashboard.png 宽度：1280 身高：900 等待：2000 javascript: | document.querySelector('.loading-spinner')?.remove() - 网址：http://localhost:3000 输出：截图/mobile-home.png 宽度：375 身高：812 **运行批处理：** shot-scraper 多镜头.yml ### 高级 YAML 键 - 网址：http://localhost:3000/form 输出：截图/form-filled.png 宽度：1200 javascript: | document.querySelector('#name').value = 'Jane Doe'; document.querySelector('#email').value = 'jane@example.com'; 等待：500 选择器：“.form-container” 填充：20 视网膜：真实 **支持的 YAML 键：** `url`、`output`、`width`、`height`、`quality`、`wait`、`wait_for`、`selector`、`selectors`、`selector_all`、`padding`、`javascript`、`js_selector`、`retina`、`omit_background` ## 第 3 阶段：智能配置生成当要求为项目生成屏幕截图配置时，请按照以下过程操作： ### 第 1 步：分析项目阅读该项目以了解： * **路由/页面** — 检查路由器配置、页面文件或导航 * **关键 UI 状态** — 正在加载、为空、已填充、错误状态 * **重要组件** - 英雄部分、仪表板、表单 * **端口** — 开发服务器运行在什么端口上 ### 步骤2：生成shots.yml 构建涵盖项目关键屏幕的 YAML 配置： # 运行验证 shot-scraper 多镜头.yml ### 第 3 步：迭代查看屏幕截图，调整时间和选择器，重新运行。 ## 第 4 阶段：优化输出 ### 减少文件大小 **对照片/复杂 UI 使用 JPEG：** shot-scraper http://localhost:3000 --quality 85 -o page.jpg **对带有文本/锐边的 UI 使用 PNG（默认）。** **透明背景（用于覆盖文档）：** shot-scraper http://localhost:3000 -s ".component" --omit-background -o widget.png ### 一致性提示 * 始终设置明确的“宽度”——默认 1280 就可以，但要有意为之 * 省略整页捕获的“高度”，将其设置为固定视口 * 使用 `--retina` 来查看在高 DPI 屏幕上查看的自述文件图像 * 为 SPA 添加 `--wait` 来补充客户端 * 使用 `javascript` 关闭 cookie 横幅、工具提示或模式 * 使用 `selector` \+ `padding` 干净地捕获特定组件 ## 第五阶段：CI/CD 集成 ### GitHub 操作名称：更新截图于：推：分支：[主要] 路径：[“src / **”，“shots.yml”] 职位：截图：运行：ubuntu-latest 步骤： - 使用：actions/checkout@v4 - 名称：安装Python 使用：actions/setup-python@v5 与： python-版本：“3.12” - 名称：安装 shot-scraper 运行：| pip 安装 shot-scraper 快照刮刀安装 - 名称：捕获屏幕截图运行：| npm ci && npm run dev & 睡5 shot-scraper 多镜头.yml - 名称：提交更新的截图使用：stefanzweifel/git-auto-commit-action@v5 与： commit_message:“文档：更新屏幕截图” file_pattern: "截图/*.png" **提示：** 使用 YAML 中的 `server` 键自动启动开发服务器 - 请参阅 **[模板]()**。 ## 示例 ### 好：结构良好的屏幕截图配置 # shot.yml — 明确的尺寸、适当的等待、有组织的输出 - 网址：http://localhost:3000 输出：截图/homepage.png 宽度：1280 高度：800 - 网址：http://localhost:3000/dashboard 输出：截图/dashboard.png 宽度：1280 身高：900 等待：2000 javascript: | document.querySelector('.toast-notification')?.remove() - 网址：http://localhost:3000/settings 输出：截图/settings.png 宽度：1280 选择器：“.settings-panel” 填充：20 - 网址：http://localhost:3000 输出：截图/mobile-home.png 宽度：375 身高：812 ### 不好：常见错误 # 没有指定输出——来自 URL 的 shot-scraper 自动命名，结果混乱 - 网址：http://localhost:3000 # 无宽度 - 依赖于默认值，跨机器不一致 - 网址：http://localhost:3000/about 输出：about.png # 无需等待 SPA — 捕获加载旋转而不是内容 - 网址：http://localhost:3000/dashboard 输出：仪表板.png # 截图目录未整理 - 网址：http://localhost:3000/settings 输出：设置.png ### 好：捕获特定组件 # 英雄部分带有填充以提供喘息空间 shot-scraper http://localhost:3000 -s ".hero" -p 20 -o docs/hero.png # 在视网膜中导航以获得清晰的文本 shot-scraper http://localhost:3000 -s "nav" --retina -o docs/nav.png # 通过 JS 预先填充数据的表单 shot-scraper http://localhost:3000/contact \ -j "document.querySelector('#name').value = 'Jane Doe'" \ -s“.contact-form”-p 10 -o docs/form.png ### 不好：组件捕获反模式 # 无选择器 — 当您只需要一个部分时捕获整个页面 shot-scraper http://localhost:3000 -o Hero.png # 无填充 - 元素剪得很紧，在文档中看起来很拥挤 shot-scraper http://localhost:3000 -s ".hero" -o Hero.png # 不用等待 — 动态组件尚未渲染 shot-scraper http://localhost:3000 -s ".chart" -o Chart.png ## 故障排除 ### 问题：屏幕截图显示空白页面或加载微调器 **原因：** SPA 尚未水合或异步数据尚未加载。 **解决方案：** # 固定等待 shot-scraper http://localhost:3000 --wait 3000 -o page.png # 等待特定元素 shot-scraper http://localhost:3000 --wait-for "document.querySelector('.content')" -o page.png ### 问题：本地主机上的“连接被拒绝” **原因：** 开发服务器未运行或位于不同端口。 **解决方案：** 1. 首先启动你的开发服务器：`npm run dev &` 2.验证端口：`curl -I http://localhost:3000` 3.或者使用YAML中的`server`键来自动启动它 ### 问题：屏幕截图尺寸与预期不符 **原因：** 忽略高度（捕获整页）或未考虑视网膜。 **解决方案：** * 为固定视口设置显式的“-h” * 有意省略“-h”以捕获整页 * `--retina` 将像素尺寸加倍（1280w 变为 2560px 图像） ### 问题：未找到 shot-scraper 命令 **原因：** 未安装或未配置 pipx PATH。 **解决方案：** pipx 安装 shot-scraper pipx Ensurepath # 将 pipx bin 添加到 PATH shot-scraper install # 安装浏览器引擎 ### 问题：屏幕截图中缺少元素 **原因：** CSS 选择器错误、模式后面的元素或延迟加载的内容。 **解决方案：** # 使用 --interactive 进行可视化调试 shot-scraper http://localhost:3000 -i # 使用 --devtools 作为检查器 shot-scraper http://localhost:3000 --devtools ## 整合 **此技能搭配：** * **record-tui** — 用于终端应用程序录制（对于 CLI 使用 VHS，对于 Web UI 使用 shot-scraper） * **track-session** — 跟踪屏幕截图迭代进度 * **git-worktree** — 比较各个分支的屏幕截图 **与以下有用：** * [shot-scraper]() — 截图工具 * [shot-scraper-template]() — GitHub Actions 模板 * [pipx]() — 全局 Python 应用程序安装程序 ## 快速参考 # 单张截图 shot-scraper http://localhost:3000 -o page.png # 有尺寸 shot-scraper http://localhost:3000 -w 1280 -h 800 -o page.png # 具体元素 shot-scraper http://localhost:3000 -s ".hero" -p 10 -o Hero.png # 视网膜 shot-scraper http://localhost:3000 --retina -o page@2x.png # 本地 HTML 文件 shot-scraper index.html -o Preview.png # 来自 YAML 的批处理 shot-scraper 多镜头.yml # 交互式调试 shot-scraper http://localhost:3000 -i # PDF 导出 shot-scraper pdf http://localhost:3000 -o page.pdf ## 深度参考如需详细指南，请在需要时加载这些文件： * **[命令参考]()** — 所有 shot-scraper 命令、标志和子命令 * **[Templates]()** — 复制粘贴常见项目类型的 YAML 配置 _仅在特别需要保存上下文时加载这些。_ ## 参考文献 * [shot-scraper]() — 官方存储库 * [shot-scraper 文档]() — 完整文档 * [shot-scraper-template]() — GitHub Actions 模板 * [pipx]() — 全局 Python 应用程序安装程序 * [Simon Willison 的博客]() — 作者在 shot-scraper 上的帖子

本地截图

包含技能