mcpField
F
full-page-screenshot

full-page-screenshot

github.com/alirezarezvani生产力29.0k565 次安装今天更新
代码仓库

关于 full-page-screenshot

通过 Chrome DevTools Protocol 将完整网页捕获为 PNG 的 Node.js 技能。支持已打开标签页和 URL，并处理动态内容及超长页面。

主要功能

  1. 01将完整网页保存为 PNG
  2. 02捕获已打开标签页或 URL
  3. 03扩展滚动容器
  4. 04触发延迟加载内容
  5. 05分块并拼接超长截图
  6. 06发现 Chrome 调试端口

适用场景

  1. 01将长篇文章保存为图片
  2. 02从已登录标签页捕获页面
  3. 03留存动态仪表板供审阅

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/alirezarezvani/claude-skills --skill full-page-screenshot

安装后在 Claude Code 中输入/full-page-screenshot确认已加载。

附带文件scripts/full-page-screenshot.mjs

详细介绍

整页截图

通过 Chrome DevTools Protocol 对任意网页进行整页截图。生成单个 PNG 文件，包含全部内容，即使是需要滚动才能看到的部分也包括在内。除 Node.js 22+ 和已启用远程调试的 Chrome 外，没有其他外部依赖。

前置条件

  • Node.js 22+（使用内置的 WebSocket）
  • 已启用远程调试的 Chrome/Chromium

检查环境是否就绪：

node "${SKILL_DIR}/scripts/full-page-screenshot.mjs" --check

如果 Chrome 检查失败，请指导用户打开 chrome://inspect/#remote-debugging，并启用 "Allow remote debugging for this browser instance"。

工作流程

方式 A：截取已打开的标签页（推荐用于需要登录的页面）
  1. 列出可用的标签页：
node "${SKILL_DIR}/scripts/full-page-screenshot.mjs" --list
  1. 根据标题/URL 确定目标，然后截图：
node "${SKILL_DIR}/scripts/full-page-screenshot.mjs" <targetId> /tmp/screenshot.png --width 1200 --dpr 1
方式 B：截取 URL（打开后台标签页，截图后关闭）
node "${SKILL_DIR}/scripts/full-page-screenshot.mjs" --url "https://example.com" /tmp/screenshot.png --width 1200 --dpr 1 --wait 15000

注意： --url 模式会创建后台标签页。需要身份验证的页面（SSO、登录墙）应改用方式 A。

参数
参数说明默认值
output输出 PNG 文件路径/tmp/screenshot.png
--width视口宽度（CSS 像素）（文章：1200，仪表板：1440-1920）1200
--dpr设备像素比（2 为 Retina，但文件大小为 4 倍）1
--wait页面加载超时时间（毫秒，仅适用于 --url 模式）15000
--css截图前注入的自定义 CSS（例如隐藏元素）—
验证输出
# macOS
sips -g pixelWidth -g pixelHeight /tmp/screenshot.png

# Linux
file /tmp/screenshot.png

核心功能

  1. SPA 滚动容器展开 — 检测 overflow-y: auto/scroll 容器，滚动浏览以触发懒加载，然后移除溢出限制（包括 Tailwind h-[calc(...)]），使所有内容在一次渲染中完成显示。

  2. DOM 稳定性检测 — 在 readyState=complete 之后，监控 DOM 元素数量直至其趋于稳定。这可确保 SPA 框架完成动态内容的渲染。

  3. 懒加载触发 — 逐步滚动视口以触发 IntersectionObserver 回调，然后等待所有 <img> 元素加载完成。

  4. 超高页面分块截图 — 超过 16,000px 的页面会以 8,000px 为单位分块截图，并使用 Python PIL 自动拼接。若 PIL 不可用，则回退为单独保存各分块文件。

  5. Chrome 自动发现 — 读取 DevToolsActivePort 文件以查找调试端口。若失败，则回退为探测端口 9222、9229、9333。

  6. CDP 代理回退 — 当 CDP 代理占用浏览器 WebSocket 时，脚本会回退到代理 API 端点（/eval、/screenshot、/scroll）进行截图。

工作原理

1. Discover Chrome debugging port
2. Connect via WebSocket (CDP)
3. Attach to target / create background tab
4. Set viewport width via Emulation domain
5. Wait: readyState + DOM stability
6. Detect & expand scroll containers
7. Scroll through page (trigger lazy-load)
8. Wait for images to complete
9. Measure final content height
10. Page.captureScreenshot (or tiled capture)
11. Stitch tiles if needed (PIL)
12. Restore viewport, detach, clean up

反模式

请勿应当
在高度超过 10,000px 的页面上使用 --dpr 2使用 --dpr 1 以避免 Chrome 内存问题
对需要身份验证或 SSO 的页面使用 --url在用户已登录的标签页上使用 --list 与 targetId
对 SPA 将 --wait 设置为低于 5000SPA 需要时间获取数据并渲染；请使用 10000-15000
未先检查 --check 就进行截图始终先确认 Chrome 调试功能可用
为所有页面硬编码视口宽度文章使用 1200，仪表板/表格使用 1440 及以上
跳过输出验证截图后始终使用 sips 或 file 命令进行验证

故障排查

现象原因解决方法
"Cannot find Chrome debugging port"未启用远程调试打开 chrome://inspect/#remote-debugging 并启用它
"WebSocket connection timeout"CDP 代理占用了连接脚本会自动回退到代理 API
截图空白或全白页面尚未加载完成增大 --wait 的值
底部被截断滚动容器未展开脚本会自动处理此问题；若问题持续，请提交 issue
内存不足页面极高且 DPR 较高将 --dpr 降至 1，和/或减小 --width
"PIL not available for stitching"未安装 Python Pillow使用 pip3 install Pillow 安装，或接受单独的分块文件

交叉引用

评论

支持 Markdown