Kitesurf — Cloudflare 的 AI Agent 浏览器

When to Use

用户要抓网页/截图/转 markdown/PDF/结构化 JSON/链接/爬全站,且机器本地浏览器太重太慢
用户提到 Kitesurf / Cloudflare Browser Run / 轻量浏览器 / AI Agent 浏览器
批量网页任务需要省 CPU/内存、省成本,或用 CDP/MCP 做浏览器自动化

官方文档:https://developers.cloudflare.com/browser-run/kitesurf/ Kitesurf 是无状态、可高度扩展的浏览器,完全跑在 Cloudflare Workers 上。不是 Chromium 精简版,是给 AI 模型当用户设计的引擎(省 token、省 CPU/内存,放弃标签页/主题/扩展/像素级渲染)。

什么时候用 / 什么时候不用

用:

抓 HTML / 截图 / PDF / markdown / 结构化 JSON / 链接 / 爬全站
批量、突发的 AI 驱动任务(轻量、便宜、隔离)
需要 CDP 会话的自动化(Puppeteer / Playwright / MCP)

别用(Kitesurf 做不到):

播放视频 / WebGL 渲染
真实 TLS 指纹过 bot 挑战(反爬严的站会挂)
需要持久登录状态的长会话

不确定站点兼容性 → 先丢 playground 试:https://kitesurf.cloudflare.app/

前置条件

Cloudflare 账号
API Token,权限 Browser Rendering - Edit: https://dash.cloudflare.com/profile/api-tokens → Create Token → 自定义模板
Account ID:dash.cloudflare.com 首页右侧可见

建议把凭证存到环境变量或密钥管理工具(不要写进技能文件):

CF_ACCOUNT_ID=<account_id>
CF_API_TOKEN=<token>

1. Quick Actions(REST,一键任务,最常用)

端点格式统一,加 ?browser=kitesurf 切换引擎:

POST https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/browser-run/<action>?browser=kitesurf
-H "Authorization: Bearer <TOKEN>"
-H "Content-Type: application/json"
-d '{"url":"https://example.com"}'

| action | 用途 | 响应 | |---|---|---| | content | 抓 HTML | text/html | | markdown | 网页转 markdown(喂 LLM 首选) | text/markdown | | screenshot | 截图 | PNG | | pdf | 渲染 PDF | application/pdf | | links | 提取所有链接 | JSON | | scrape | 按 CSS 选择器抓元素 | JSON | | accessibilityTree | 无障碍树(结构洞察) | JSON | | json | 用 AI 提取结构化数据 | JSON | | snapshot | 多种格式一次抓 | 多部分 | | crawl | 爬全站(仅 REST) | 增量结果 |

常用示例:

# markdown(喂给 LLM 最省 token)
curl -s -X POST "https://api.cloudflare.com/client/v4/accounts/$CF_ACCOUNT_ID/browser-run/markdown?browser=kitesurf" \
  -H "Authorization: Bearer $CF_API_TOKEN" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","gotoOptions":{"waitUntil":"networkidle2"}}'

# 截图
curl -s -X POST "https://api.cloudflare.com/client/v4/accounts/$CF_ACCOUNT_ID/browser-run/screenshot?browser=kitesurf" \
  -H "Authorization: Bearer $CF_API_TOKEN" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}' --output screenshot.png

2. CDP 端点(长会话 / 交互式自动化)

wss://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/browser-run/devtools/browser?browser=kitesurf

现有 Puppeteer / Playwright / chrome-remote-interface 代码不用改,把 endpoint 换成上面的就行
HTTP 生命周期端点(免 WebSocket):
- 创建会话: POST /devtools/browser
- 列表签: GET /devtools/browser/{session_id}/json/list
- 开新签: PUT /devtools/browser/{session_id}/json/new
- 关签: DELETE /devtools/browser/{session_id}/json/close/{target_id}
- 关会话: DELETE /devtools/browser/{session_id}

Puppeteer 示例

const browser = await puppeteer.connect({
  browserWSEndpoint:
    `wss://api.cloudflare.com/client/v4/accounts/${accountId}/browser-run/devtools/browser?browser=kitesurf`,
  headers: { Authorization: `Bearer ${apiToken}` },
});

Playwright 示例

const browser = await chromium.connectOverCDP(endpoint, {
  headers: { Authorization: `Bearer ${apiToken}` },
});

3. MCP 接入(Hermes / Claude 直接调)

给 MCP client 配置:

{
  "mcpServers": {
    "kitesurf": {
      "type": "local",
      "command": ["npx", "-y", "chrome-devtools-mcp@latest",
        "--wsEndpoint=wss://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/browser-run/devtools/browser?browser=kitesurf",
        "--wsHeaders={\"Authorization\":\"Bearer <TOKEN>\"}"],
      "enabled": true
    }
  }
}

装好后 AI 就能用 MCP 工具导航、点击、填表、截图。

性能对比(官方基准,14-URL 语料)

| 指标 | Kitesurf | Chromium(暖池) | 相对 | |---|---|---|---| | CPU:截图 | 380 ms | 1,173 ms | 省 3.1× | | CPU:HTML 提取 | 229 ms | 877 ms | 省 3.8× | | 内存:截图 | 57.8 MiB | 271 MiB | 省 4.7× | | 内存:HTML 提取 | 39.4 MiB | 273.7 MiB | 省 7.0× | | 墙钟:截图 | 1,148 ms | 637 ms | 慢 1.8× | | 墙钟:HTML 提取 | 820 ms | 472 ms | 慢 1.7× |

要点:省的是烧钱项(CPU/内存 3-7×),慢的是墙钟(冷软件渲染器 vs 暖 JIT)。批量任务、省成本用 Kitesurf;要快、要像素级、要过反爬用 Chromium。

标准符合度(WPT 测试,23.5 万+ 子测试通过)

DOM 97% · HTML 96% · Selection 99% · SVG 97% · Encoding 99% · CORS 95% · XHR 95% · URL 83%

Pitfalls

token 权限:必须 Browser Rendering - Edit,只有 Read 会 403
URL 里 account_id 后面别漏斜杠:/accounts/{id}/browser-run/...
视频/WebGL 站(B站、3D 站)直接黑屏 → 换 Browser Run 默认 Chromium(去掉 ?browser=kitesurf)
反爬严的站(需要真实 TLS 指纹)Kitesurf 过不去 → 用本地浏览器或默认引擎
长会话:无状态设计,别指望保持登录态;需要持久状态用 CDP 会话(但 Kitesurf 官方注明"尚不支持 long-running authenticated session")
兼容性不确定的站,先 playground 试再写代码
beta 期间免费;收费模式看 Browser Run 定价页

验证

# 1. 环境变量在不在
[ -n "$CF_ACCOUNT_ID" ] && [ -n "$CF_API_TOKEN" ] && echo OK

# 2. 真跑一次 markdown 提取
curl -s -X POST "https://api.cloudflare.com/client/v4/accounts/$CF_ACCOUNT_ID/browser-run/markdown?browser=kitesurf" \
  -H "Authorization: Bearer $CF_API_TOKEN" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}' | head -20