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

/pdf - 渲染 PDF

最后更新 查看 MarkdownAgent 设置

/pdf 端点指示浏览器使用 Cloudflare 无头 Browser Run 服务生成网页或自定义 HTML 的 PDF。

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

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

端点

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

必填字段

必须提供 url 或 html 之一：

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

常见使用场景

  • 捕获网页的 PDF
  • 直接从 HTML 生成 PDF，如发票、许可证、报告和证书

基本用法

将 URL 转换为 PDF

导航到 https://example.com/ 并注入自定义 CSS 和外部样式表。然后将渲染后的页面作为 PDF 返回。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/pdf' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/",
    "addStyleTag": [
      { "content": "body { font-family: Arial; }" }
    ]
  }' \
  --output "output.pdf"
import Cloudflare from "cloudflare";

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

const pdf = await client.browserRendering.pdf.create({
	account_id: process.env["CLOUDFLARE_ACCOUNT_ID"],
	url: "https://example.com/",
	addStyleTag: [{ content: "body { font-family: Arial; }" }],
});

console.log(pdf);

const content = await pdf.blob();
console.log(content);
interface Env {
	BROWSER: BrowserRun;
}

export default {
	async fetch(request, env): Promise<Response> {
		return await env.BROWSER.quickAction("pdf", {
			url: "https://example.com/",
			addStyleTag: [{ content: "body { font-family: Arial; }" }],
		});
	},
} satisfies ExportedHandler<Env>;

将自定义 HTML 转换为 PDF

如果你有要生成 PDF 的原始 HTML，请使用 html 选项。你仍可以使用 addStyleTag 参数应用自定义样式。

curl -X POST https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/pdf \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
  "html": "<html><body>Advanced Snapshot</body></html>",
	"addStyleTag": [
      { "content": "body { font-family: Arial; }" },
      { "url": "https://cdn.jsdelivr.net/npm/bootstrap@3.3.7/dist/css/bootstrap.min.css" }
    ]
}' \
  --output "invoice.pdf"

高级用法

使用自定义请求头和 viewport 的高级页面加载

导航到 https://example.com，设置额外的 HTTP 请求头并配置页面大小（viewport）。PDF 生成将等待页面在至少 500 毫秒内不超过两个网络连接，或达到最大超时 4500 ms 后，再开始渲染。

goToOptions 参数公开了 Puppeteer API ↗ 的大部分选项。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/pdf' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/",
    "setExtraHTTPHeaders": {
      "X-Custom-Header": "value"
    },
    "viewport": {
      "width": 1200,
      "height": 800
    },
    "gotoOptions": {
      "waitUntil": "networkidle2",
      "timeout": 45000
    }
  }' \
  --output "advanced-output.pdf"

生成 PDF 时阻止图片和样式

选项 rejectResourceTypes 和 rejectRequestPattern 可用于在渲染期间阻止请求。也可以相反操作，使用 allowResourceTypes 和 allowRequestPattern 仅 允许某些请求。

curl -X POST https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/pdf \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://cloudflare.com/",
  "rejectResourceTypes": ["image"],
  "rejectRequestPattern": ["/^.*\\.(css)"]
}' \
  --output "cloudflare.pdf"

自定义页眉和页脚

你可以使用 headerTemplate 和 footerTemplate 选项通过 HTML 模板自定义页眉和页脚。启用 displayHeaderFooter 以在输出中包含它们。此示例生成 A5 PDF，带有品牌页眉、页脚消息和页码。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/pdf' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "pdfOptions": {
      "format": "a5",
      "headerTemplate": "<div style=\"font-size: 10px; text-align: center; width: 100%; padding: 5px;\"><span>brand name</span></div>",
      "displayHeaderFooter": true,
      "footerTemplate": "<div style=\"color: lightgray; border-top: solid lightgray 1px; font-size: 10px; padding-top: 5px; text-align: center; width: 100%;\"><span>This is a test message</span> - <span class=\"pageNumber\"></span></div>",
      "margin": {
        "top": "70px",
        "bottom": "70px"
      }
    }
  }' \
  --output "header-footer.pdf"

包含来自页面 metadata 的动态占位符

你可以在页眉或页脚中包含 title、date、pageNumber 和 totalPages 等动态占位符，以在每页显示 metadata。此示例生成 A4 PDF，带有公司品牌页眉、当前日期和标题，以及页脚页码。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/pdf' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://news.ycombinator.com",
    "pdfOptions": {
      "format": "a4",
      "landscape": false,
      "printBackground": true,
      "preferCSSPageSize": true,
      "displayHeaderFooter": true,
      "scale": 1.0,
      "headerTemplate": "<div style=\"width: 100%; font-size: 10px; padding: 10px; text-align: center;\"><div style=\"border-bottom: 1px solid #ddd;\"><span style=\"color: #666;\">Company Name</span> | <span class=\"date\"></span> | <span class=\"title\"></span></div></div>",
      "footerTemplate": "<div style=\"width: 100%; font-size: 10px; padding: 10px; text-align: center;\"><div style=\"border-top: 1px solid #ddd;\">Page <span class=\"pageNumber\"></span> of <span class=\"totalPages\"></span></div></div>",
      "margin": {
        "top": "100px",
        "bottom": "80px",
        "right": "30px",
        "left": "30px"
      },
      "timeout": 30000
    }
  }' \
  --output "dynamic-header-footer.pdf"

使用自定义字体

如果你的 PDF 需要 Browser Run 环境中未预装的字体，可以使用 addStyleTag 参数加载自定义字体。有关说明和示例，请参阅使用自定义字体。

处理 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 常见问题与故障排除指南。

这篇文档对您有帮助吗？