scrapfly-screenshot

Scrapfly 截图

使用 Scrapfly Screenshot API，结合 JavaScript 渲染和反机器人绕过功能，捕获高质量网页截图。

适用场景

• 捕获网站的整页或视口截图
• 通过 CSS 选择器/XPath 截取特定页面元素
• 渲染受反机器人保护的页面，以便进行视觉捕获
• 生成不同格式的截图（JPG、PNG、WebP、GIF）
• 在不同屏幕分辨率下测试页面

设置

pip install scrapfly-sdk

必须通过环境变量 SCRAPFLY_API_KEY 提供 API 密钥，或直接传递给客户端。

API 参考

端点： GET https://api.scrapfly.io/screenshot

ScrapflyClient

from scrapfly import ScrapflyClient, ScreenshotConfig
import os

client = ScrapflyClient(key=os.environ["SCRAPFLY_API_KEY"])

ScreenshotConfig 参数

参数	类型	默认值	说明
url	str	必填	要截取的目标 URL
format	str 或 Format	"jpg"	图像格式："jpg"、"png"、"webp"、"gif"（Format 枚举）
capture	str	"viewport"	捕获范围："viewport"、"fullpage"，或 CSS 选择器/XPath
resolution	str	None	屏幕尺寸，例如 "1920x1080"、"375x812"
country	str	None	代理国家/地区（ISO 3166-1 alpha-2，例如 "us"、"de"）
proxy_pool	str	None	代理池："basic"（数据中心代理，关闭 Unblocker）、"unblocker"（住宅代理和 Unblocker）、"unblocker_ultra"（同上，且这是目标网站或收费反机器人保护唯一接受的代理池），或 "auto"（API 在请求前根据目标网站的配置文件选择代理池：在数据中心代理上启用 Unblocker，或选择目标网站所需的代理池；所有目标网站均接受）。Screenshot API 仅接受这四种值，其他值均会被忽略；未设置时，使用 API 的截图默认值。所有代理池的截图价格相同。scrapfly-sdk 0.12.0 之后发布的版本中的 ScreenshotConfig 支持此参数
timeout	int	None	请求总超时时间，单位为毫秒
rendering_wait	int	1000	页面加载后、捕获前的等待时间，单位为毫秒
wait_for_selector	str	None	等待此 CSS/XPath 选择器可见后再捕获
options	list[str] 或 list[Options]	None	截图行为标记，例如 "load_images"、"dark_mode"、"block_banners"、"print_media_format"（Options 枚举）
auto_scroll	bool	False	捕获前滚动到底部，以触发延迟加载
js	str	None	捕获前执行的原始 JavaScript（SDK 会进行 base64 编码；最大 16KB）
cache	bool	None	为此截图请求启用响应缓存
cache_ttl	bool 或 int	None	缓存 TTL（生存时间）；仅在 cache=True 时生效
cache_clear	bool	None	在 cache=True 时，清除此 URL 的现有缓存条目
vision_deficiency	str 或 VisionDeficiency	None	模拟视力障碍，用于无障碍测试，例如 "deuteranopia"、"protanopia"、"achromatopsia"（VisionDeficiency 枚举）
webhook	str	None	用于接收异步截图完成回调的 Webhook 名称
raise_on_upstream_error	bool	True	如果上游页面返回错误状态，则引发异常

示例

基本视口截图

from scrapfly import ScrapflyClient, ScreenshotConfig
import os

client = ScrapflyClient(key=os.environ["SCRAPFLY_API_KEY"])

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
))

# Save the screenshot image
with open("screenshot.jpg", "wb") as f:
    f.write(result.image)

PNG 格式的整页截图

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    format="png",
    capture="fullpage",
    auto_scroll=True,
))

with open("fullpage.png", "wb") as f:
    f.write(result.image)

截取特定元素

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/product/1",
    rendering_wait=5000,
    format="png",
    capture="div.features" # CSS selector
))

with open("element.png", "wb") as f:
    f.write(result.image)

自定义分辨率（移动设备）

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    resolution="375x812",  # iPhone viewport
))

with open("mobile.jpg", "wb") as f:
    f.write(result.image)

屏蔽横幅并启用深色模式的截图

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    options=["block_banners", "dark_mode"],
    rendering_wait=2000,
))

with open("clean_dark.jpg", "wb") as f:
    f.write(result.image)

捕获前等待动态内容加载

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    wait_for_selector="div.products",
    rendering_wait=3000,
))

with open("fully_loaded_screenshot.jpg", "wb") as f:
    f.write(result.image)

使用地理定位的截图

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    country="de",
    resolution="1920x1080",
))

with open("german_version.jpg", "wb") as f:
    f.write(result.image)

截图前执行 JavaScript

在截图前运行自定义 JS（例如移除导航栏、Cookie 弹窗或侧边栏）。将选择器替换为与目标页面匹配的选择器——在 DevTools 中检查页面以找到它们。

import base64

# Example: remove navbar (adjust selector for your page: nav, header, .navbar, etc.)

js_code = "var el = document.querySelector('.navbar-collapse'); if (el) el.remove();"
js_code = base64.urlsafe_b64encode(js_code.encode('utf-8')).decode('utf-8')

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    js=js_code, # remove the nav bar
    rendering_wait=1000,
))

with open("clean.jpg", "wb") as f:
    f.write(result.image)

错误处理

from scrapfly.errors import ScrapflyError

try:
    result = client.screenshot(ScreenshotConfig(url="https://web-scraping.dev/products"))
    with open("screenshot.jpg", "wb") as f:
        f.write(result.image)
except ScrapflyError as e:
    print(f"Screenshot failed: {e.message}")

重要说明

• 响应中的 image 属性包含原始二进制图像数据
• 浏览器会捕获 JPEG，因此 "jpg"（默认格式）是唯一不会重新编码的格式；"png"、"webp" 和 "gif" 都是从该截图转换而来，并非像素级准确的源图像
• 对于 capture="fullpage"，建议设置 auto_scroll=True，以触发延迟加载的图像
• block_banners 会移除 Cookie 同意横幅和覆盖层弹窗
• rendering_wait 默认值为 1000ms；对于 JS 密集型页面，请增大该值
• js 参数内容必须进行 base64 编码，且大小不得超过 16KB
• 截图由 Scrapfly 存储，可通过响应标头 X-Scrapfly-Screenshot-Url 中的 URL 获取
• 如果目标网站或反机器人保护机制需要额外付费，proxy_pool="basic" 和 "unblocker" 会返回 ERR::PROXY::UNBLOCKER_ULTRA_REQUIRED（HTTP 422，不收费）：请使用 proxy_pool="unblocker_ultra" 再次发送截图请求