跳转到内容
搜索文档
↵选择
↑↓导航
ESC关闭

/screenshot - 捕获屏幕截图

最后更新 查看 MarkdownAgent 设置

/screenshot 端点通过处理 HTML 和 JavaScript 渲染网页，然后捕获完整渲染页面的屏幕截图。

可通过两种方式使用此端点：

更多信息请参阅 Quick Actions：开始之前。

端点

https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot

必填字段

必须提供 url 或 html 之一：

  • url（字符串）
  • html（字符串）

常见使用场景

  • 为网站、仪表板或报告生成预览
  • 为自动化测试、QA 或视觉回归捕获屏幕截图

基本用法

从自定义 HTML 截取屏幕截图

将页面 HTML 内容设置为 Hello World!，然后截取屏幕截图。omitBackground 选项隐藏默认白色背景，允许捕获带透明度的屏幕截图。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "html": "Hello World!",
    "screenshotOptions": {
      "omitBackground": true
    }
  }' \
  --output "screenshot.png"
import Cloudflare from "cloudflare";

const client = new Cloudflare({
	apiToken: process.env["CLOUDFLARE_API_TOKEN"],
});

const screenshot = await client.browserRendering.screenshot.create({
	account_id: process.env["CLOUDFLARE_ACCOUNT_ID"],
	html: "Hello World!",
	screenshotOptions: {
		omitBackground: true,
	},
});

console.log(screenshot.status);
interface Env {
	BROWSER: BrowserRun;
}

export default {
	async fetch(request, env): Promise<Response> {
		return await env.BROWSER.quickAction("screenshot", {
			html: "Hello World!",
			screenshotOptions: {
				omitBackground: true,
			},
		});
	},
} satisfies ExportedHandler<Env>;

从 URL 截取屏幕截图

使用以下 curl 命令通过 REST API 从 URL 截取屏幕截图：

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com"
  }' \
  --output "screenshot.png"

有关控制最终屏幕截图的更多选项，如 clip、captureBeyondViewport、fullPage 等，请查看端点参考。

高级用法

截取需要身份验证的页面屏幕截图

某些网页在查看内容前需要身份验证。Browser Run 支持三种身份验证方法，适用于所有 Quick Actions 端点。有关所有方法的快速参考，请参阅如何使用 Quick Actions 渲染需要身份验证的页面？。

提供有效的会话 cookie 以访问需要登录的页面：

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/protected-page",
    "cookies": [
      {
        "name": "session_id",
        "value": "your-session-cookie-value",
        "domain": "example.com",
        "path": "/"
      }
    ]
  }' \
  --output "authenticated-screenshot.png"

HTTP Basic Auth（HTTP 基本认证）

对使用 HTTP Basic Authentication 保护的页面，使用 authenticate 参数：

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/protected-page",
    "authenticate": {
      "username": "user",
      "password": "pass"
    }
  }' \
  --output "authenticated-screenshot.png"

基于 Token 的身份验证

使用 setExtraHTTPHeaders 添加自定义 authorization 请求头：

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/protected-page",
    "setExtraHTTPHeaders": {
      "Authorization": "Bearer your-token"
    }
  }' \
  --output "authenticated-screenshot.png"

导航并捕获整页屏幕截图

导航到 https://cloudflare.com/，更改页面大小（viewport），等待没有活动的网络连接（waitUntil）或最多 4500ms（timeout），然后捕获 fullPage 屏幕截图。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://cloudflare.com/",
    "screenshotOptions": {
       "fullPage": true
    },
    "viewport": {
      "width": 1280,
      "height": 720
    },
    "gotoOptions": {
      "waitUntil": "networkidle0",
      "timeout": 45000
    }
  }' \
  --output "advanced-screenshot.png"

改善模糊屏幕截图的分辨率

如果设置了较大的视口宽度和高度，屏幕截图可能看起来模糊或像素化。这可能是因为浏览器的默认 deviceScaleFactor（默认为 1）对于该视口来说不够高。

要解决此问题，请增大 deviceScaleFactor 的值。

{
  "url": "https://cloudflare.com/",
  "viewport": {
    "width": 3600,
    "height": 2400,
    "deviceScaleFactor": 2
  }
}

自定义 CSS 并嵌入自定义 JavaScript

指示浏览器访问 https://example.com，嵌入自定义 JavaScript（addScriptTag）并添加额外样式（addStyleTag），包括内联（addStyleTag.content）和加载外部样式表（addStyleTag.url）。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/",
    "addScriptTag": [
      { "content": "document.querySelector(`h1`).innerText = `Hello World!!!`" }
    ],
    "addStyleTag": [
      {
        "content": "div { background: linear-gradient(45deg, #2980b9  , #82e0aa  ); }"
      },
      {
        "url": "https://cdn.jsdelivr.net/npm/bootstrap@3.3.7/dist/css/bootstrap.min.css"
      }
    ]
  }' \
  --output "screenshot.png"

使用 selector 选项捕获特定元素

要捕获网页上特定元素的屏幕截图，请使用带有效 CSS 选择器的 selector 选项。你还可以配置 viewport 以控制渲染期间的页面尺寸。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "selector": "#example_element_name",
    "viewport": {
      "width": 1200,
      "height": 1600
    }
  }' \
  --output "screenshot.png"

还有许多其他选项，例如使用 authenticate 设置 HTTP 凭据、设置 cookies，以及使用 gotoOptions 控制页面加载行为 — 查看端点参考了解所有可用参数。

处理 JavaScript 密集型页面

对于 JavaScript 密集型页面或单页应用（SPA），默认的页面加载行为可能返回空或不完整的结果。这是因为浏览器在 JavaScript 完成渲染内容之前就认为页面已加载完毕。

最简单的解决方案是将 gotoOptions.waitUntil 参数设置为 networkidle0 或 networkidle2：

{
	"url": "https://example.com",
	"gotoOptions": {
		"waitUntil": "networkidle0"
	}
}

如需更快响应，高级用户可使用 waitForSelector 等待特定元素，而非等待所有网络活动停止。这需要了解哪个 CSS 选择器表示所需内容已加载。更多详情，请参阅 Quick Actions 超时。

设置自定义 User Agent

可在 JSON 请求体的顶层传入 userAgent 参数，在页面级别更改 user agent。当目标网站根据 user agent 返回不同内容时很有用。

故障排除

如有疑问或遇到错误，请参阅 Browser Run 常见问题与故障排除指南。

这篇文档对您有帮助吗？