Cloudflare 本周把 Kitesurf 以 Apache 2.0 开源。这篇按官方仓库说明,在自己的机器上把它跑起来、用 Puppeteer 连上去截一张图,并给出部署前必须装好的认证护栏与六个真实会卡住的坑。
自托管 Kitesurf:把智能体浏览器跑在本地的完整步骤
这篇教程解决什么
2026 年 11 月 13 日,Cloudflare 把 Kitesurf 以 Apache 2.0 许可开源。它是一个跑在 Workers 上的无状态浏览器引擎:不启动 Chromium、不用浏览器容器,自己解析 HTML、套用 CSS、执行页面脚本并渲染截图,对外说的是 Chrome DevTools Protocol(CDP)——所以 Puppeteer 这类现成客户端可以直接连上来。
这篇要做的事很具体:在你自己的机器上把它跑起来,并用程序连上去截一张图。读完你会得到一条能照做的命令序列、每一步「看到什么算成功」的判据,以及一份把引擎部署出去之前必须装好的护栏清单。
先说清不覆盖什么:不做效果评测,不与其他浏览器引擎横比,不给具体金额;也不替你决定「该不该让智能体碰真实账号」。官方把 Kitesurf 写成实验性项目、仍在补网页兼容性,本文只覆盖本地跑通与接入,不把它写成生产就绪方案。事件本身见 Cloudflare 开源 Kitesurf 快讯。
一个容易先搞混的点:这里说的「智能体浏览器」是给智能体用的引擎,不是让模型看图点鼠标的那套动作循环。后者是模型提议动作、由你的代码执行,属于另一种架构,Computer Use 沙箱那篇教程 讲的是那条线。本文解决的是「浏览器端跑在哪、怎么被连上」。
开始前的准备
按官方仓库说明逐条对齐,缺一条后面某一步就会卡住:
- Bazelisk,且命令名要能用 bazel 调到。整个构建由 Bazel 负责,它会自行拉取固定版本的 Bazel、Rust 工具链、wasm-bindgen 与 binaryen。
- Node.js 22 或更新,以及 pnpm 9.15.4(仓库在 package.json 里固定了版本)。没有 pnpm 时,官方给的安装方式是 npm install --global pnpm@9.15.4。
- macOS 需要 GNU tar,官方示例是 brew install gnu-tar;Linux 与 Windows 无此条。
- Rust / rustup 只在要修改仓库内自带的依赖补丁时才需要,纯跑通不必装。
- 本地端口 8787 空闲。被占用时官方支持换端口。
- 本地开发走 wrangler dev。官方说明里,把 Kitesurf 部署到 Cloudflare 账户需要 Dynamic Workers,而这属于 Workers 付费套餐;本地跑通与上线是两件事,别在一开始就去开通。
- 成本与授权认知:本地运行不涉及调用计费;部署到自有账户时会产生 Workers 资源消耗,套餐与额度以官网为准。引擎自身不带认证,这一条在进阶用法里会展开。
一句话概括前提:本地跑通只需要工具链,部署才涉及套餐与账户权限。先把工具链对齐,比先研究配置更快。
步骤详解
第 1 步:核对工具链
做什么:依次确认 Node、pnpm 与 Bazelisk 可用。
node -v
pnpm -v
bazel --version
看到什么算成功:Node 主版本不低于 22,pnpm 显示 9.15.4,Bazelisk 正常返回版本信息。pnpm 缺失时按官方给的方式单独安装,不要用别的包管理器替代——仓库用冻结锁文件安装,换工具会破坏依赖一致性。
第 2 步:取回官方仓库
做什么:克隆仓库并进入目录。
git clone https://github.com/cloudflare/kitesurf.git
cd kitesurf
看到什么算成功:目录下有 packages 等子目录与锁文件。仓库按 Apache 2.0 许可发布,自带的字体、数据与依赖仍各自保留原许可,官方用 NOTICE 文件列出第三方声明——打算二次分发前值得先看一眼。
第 3 步:安装依赖
做什么:用冻结锁文件安装。
pnpm install --frozen-lockfile
看到什么算成功:依赖安装结束且没有锁文件冲突报错。这里不要加会改写锁文件的参数,否则后面构建拿到的是另一套依赖,排错会无从下手。
第 4 步:构建并启动本地引擎
做什么:一条命令完成构建与启动。
pnpm run dev
看到什么算成功:命令先用 Bazel 构建 WebAssembly 模块与页面、渲染器包,再启动 wrangler dev,最后本地引擎监听在 http://127.0.0.1:8787。
这一步最容易出错的地方是「等」:首次构建要编译 Rust 核心与其自带的依赖,耗时明显长于后续构建;之后 Bazel 复用缓存会快很多,不要把它当成卡死而中断。
第 5 步:确认引擎真的在跑
做什么:访问健康检查地址。
curl http://127.0.0.1:8787/health
看到什么算成功:健康检查有响应。再用浏览器打开 http://127.0.0.1:8787/,官方的根路径是一个落地页:里面有输入网址的表单、示例页面,以及给智能体与其他客户端用的 CDP 端点清单。端口被占用时,按官方说明用 KITESURF_PORT 换端口:
KITESURF_PORT=8799 pnpm run dev
换了端口之后,落地页、健康检查、WebSocket 端点与 chrome://inspect 里填的地址都要跟着换。
第 6 步:用 DevTools 打开一个页面
做什么:在落地页表单里填一个网址,或直接访问带参数的地址。
http://127.0.0.1:8787/?url=https://example.com
http://127.0.0.1:8787/?inspect=1
看到什么算成功:DevTools 在标签页里打开,能看到目标页面的检查结果;带 inspect 参数的地址会开一个空白页。也可以用 Chrome 自带的 chrome://inspect/#devices:勾选 Discover network targets,在 Configure 里加上 127.0.0.1:8787,然后在 Remote Target 下点 kitesurf 旁的 inspect。这个地址要手动输进地址栏,网页里点不开它。
第 7 步:用程序连上去
做什么:在要控制它的项目里装 puppeteer-core,连到浏览器 WebSocket 端点。官方给的示例结构是:用 connect 传入 ws://127.0.0.1:8787/devtools/browser,随后 newPage、goto、screenshot,最后 disconnect。
import puppeteer from "puppeteer-core";
const browser = await puppeteer.connect({
browserWSEndpoint: "ws://127.0.0.1:8787/devtools/browser",
});
const page = await browser.newPage();
await page.goto("https://example.com/");
await page.screenshot({ path: "page.png" });
await browser.disconnect();
看到什么算成功:脚本结束后本地多出一张截图。官方还提供 HTTP 发现地址 http://127.0.0.1:8787/json/version,客户端可以先查它再决定连哪个端点;换了端口时,WebSocket 地址与发现地址都要跟着换。
第 8 步:把地址交给智能体
做什么:把 CDP 端点交给你的智能体框架或自动化脚本,让它自己建会话、开页面、执行动作。官方的原话是智能体喜欢 CDP——这一步不需要额外的模型侧改造,因为它对外就是一个 CDP 端点。
看到什么算成功:智能体能在它打开的页面里完成导航与读取,且每一轮动作都能在你这一侧的日志里对上。做这步时建议同时把可访问主机、超时上限与失败重试写进自己的配置,别让引擎直接对着开放互联网无约束地跑;这类边界的具体做法可参考 MCP 参考服务器的权限加固教程。
常见坑与排错
首次构建时间过长。 官方明确说第一次会编译 Rust 核心与自带的依赖,之后复用 Bazel 缓存。判断方法是看构建进程是否仍在推进,而不是看等待了多久;中断后重跑会重新走一部分编译。
默认构建不含 DevTools 前端。 官方说明:默认构建用的是 Google 托管的 DevTools 前端。首次连接时 Chrome 会询问是否允许该站点访问本机应用,需要选允许;如果你拒绝了,DevTools 会显示 WebSocket 已断开,需要点地址栏左侧的站点信息图标重新允许再重连。这个托管前端只能连 127.0.0.1,因此不适用于已部署的引擎。
端口冲突没有统一报错。 8787 被别的本地服务占着时,用 KITESURF_PORT 换端口;换了之后落地页、健康检查、WebSocket 端点与 chrome://inspect 里填的地址都要同步改,漏改一个就会出现「页面能开但连不上」。
它不是完整的 Chrome。 官方写得很直白:Kitesurf 提供的是 CDP 端点,不是完整的 Chrome 实现,部分 DevTools 功能尚不可用,兼容性还在补。Puppeteer 脚本里依赖某些高级 DevTools 域的部分可能跑不通,遇到时先回到「导航、读取、截图」这条最小路径验证,别急着怀疑自己的连接配置。
chrome://inspect 连不了 HTTPS 引擎。 Chrome 用明文 HTTP 与 WebSocket 发现目标,所以这套流程只对本地引擎有效;已部署的 HTTPS 引擎请用部署包自带的 DevTools 前端。
部署出去之前没加认证。 这是后果尤其重的一条:官方警告引擎自身不带任何认证,workers.dev 地址默认是公开的,而且命名有规律。别人拿到地址就能通过你的引擎打开 DevTools 浏览网页、连上 CDP 客户端、以你的 Cloudflare 账户发起出站请求,并消耗你付费的 CPU 与 Dynamic Workers 资源。解决顺序写在进阶用法里。
进阶用法
让 DevTools 前端跟着项目走。 官方提供 --config=devtools 这一 Bazel 选项,把 Chrome DevTools 前端一起构建进项目,由引擎自己的源站提供,从而摆脱托管前端的授权弹窗与仅本机地址的限制。首次带这个选项的构建会下载前端,官方提示体积不小;部署构建默认就带它,本地不需要额外配置。
部署到自己的 Cloudflare 账户。 官方给的顺序是:先在账户层面为所有 Workers 打开 Access,再从仓库根目录执行 pnpm run deploy,随后立刻为 Worker 地址配置 Cloudflare Access 保护,最后才在浏览器里登录打开落地页。之所以强调「先开保护再部署」,是因为部署完成到配置保护之间存在一段引擎公开可用窗口;官方还给了两个降低风险的命令:pnpm run deploy --dry-run 只构建不上传,pnpm run deploy:preview 上传版本但不切流量(版本地址同样是公开的,也要一并保护)。部署命令用 wrangler 的登录态,或账户 ID 与 API 令牌环境变量;不加 --name 时默认 Worker 名是 kitesurf。
让 CDP 客户端穿过 Access。 Access 会拦住没有浏览器会话的 CDP 客户端。官方流程是创建 Access 服务令牌、加一条 Service Auth 策略放行它,然后在 Puppeteer 的 connect 里带上 CF-Access-Client-Id 与 CF-Access-Client-Secret 两个请求头,端点换成你自己的 Worker 域名下的 wss 地址。这个令牌等同于已登录用户的权限,务必按密钥管理,不要写进代码库。
接入自己的可观测与边界。 引擎跑起来只是第一步。把 CDP 会话数、失败率与出站主机记进日志,给智能体侧配可访问主机清单与单轮超时,比事后排查更省事;观测侧的做法可对照 把智能体追踪接进 OTLP,来访身份分级可看 站点智能体访问分级教程。
常见问题
本地跑通需要开通付费套餐吗?
按官方说明,本地开发用 wrangler dev,工具链齐了就能跑;付费套餐的要求出现在「把 Kitesurf 部署到 Cloudflare」这一步,因为引擎要用 Dynamic Workers 为每个页面与渲染器创建隔离 Worker。也就是说,本地验证与云端部署是两笔账。套餐范围、额度与当期计费以官网为准,本文不转述金额。
它和直接用 Puppeteer 启动 Chromium 有什么不同?
同样是 CDP 客户端连上来,差别在浏览器那一侧:Kitesurf 不启动 Chromium、不用浏览器容器,而是用一组编译到 WebAssembly 的 Rust 组件完成 HTML 解析、CSS 计算、页面脚本执行与截图渲染,目标是让智能体用的浏览器更轻、能按需在 Workers 网络上扩展。代价是它不是完整的 Chrome 实现,官方明确说部分 DevTools 功能还不可用、兼容性仍在补齐。所以它是给智能体的一条新路线,不是 Chromium 的等价替换。
可以直接部署成团队共用的公网浏览器吗?
不建议在没加认证的情况下这么做,官方对此有明确警告。引擎自身没有认证,workers.dev 地址默认公开且命名可预测,拿到地址的人能以你的账户浏览网页、连 CDP 客户端、发起出站请求并消耗付费资源。要部署,就按官方顺序先在账户层面打开 Access,部署后立刻保护 Worker 地址与版本地址;程序化客户端走服务令牌与 Service Auth 策略。这一步不是可选项。
DevTools 打开后显示连接断开怎么办?
先按官方说明排查托管前端:默认构建用的是 Google 托管的 DevTools 前端,首次连接会询问是否允许访问本机应用,拒绝后就会出现 WebSocket 断开,需要在地址栏左侧的站点信息里重新允许并重连。若仍不行,确认你连的是 127.0.0.1——托管前端只能连本机地址,已部署的引擎要用自带的 DevTools 前端。另外检查端口是否与 KITESURF_PORT 的设置一致,以及引擎是否还在运行。
智能体该怎么接进去?
把它当成一个 CDP 端点即可:本地是 ws://127.0.0.1:8787/devtools/browser,部署后是受 Access 保护的 wss 地址。你的智能体框架或自动化脚本负责建会话、开页面、执行动作,Kitesurf 负责浏览器引擎这一层。注意这与「模型看截图再提议点击」是两套东西:后者需要模型侧的动作循环,可参考 Computer Use 沙箱教程;给智能体补联网检索的另一条思路见 给智能体接实时搜索。
相关工具与内容
本周事件见 Cloudflare 开源 Kitesurf 快讯;同属智能体执行侧的两篇判断是 给智能体接实时搜索 与 成品答案与原始结果怎么选。身份与边界方面可看 可信智能体委托、站点智能体访问分级教程 与 MCP 参考服务器的权限加固。
同批的 决策模型怎么选 讲的是判断层怎么选,与本文的浏览器执行层互补。按类目浏览可进 AI智能体 与 AI编程工具;站内已核实的编排工具 Dify、n8n、Claude Code 分别对应自建、自动化与编码侧三种接法。
相关内容
编码助手换模型怎么验收:从基线到弃用期的八步
11 月 16 日 Copilot 三款模型下线,11 月 17 日 Copilot Evals 进入公开预览。这篇教程给一套可照做的验收流程:盘点写死模型名的地方、建样本集、写判据、跑基线、双跑对比、归因失败,最后挂成变更门禁。
Cloudflare 更新 Clairic 并开放权重:新增 PDF 提取与轻量版 Clairic-flash
Cloudflare 于 2026 年 11 月 18 日宣布两款提取模型的开放权重版本:重新设计的 Clairic 与更轻量的 Clairic-flash。新版加强了对图片与 PDF 的字段提取、表格与日期处理以及答案溯源,单次请求可包含最多四个图片或 PDF 页面;两款模型在 Workers AI 上的接口标识与预览期保持一致。官方同时把完整权重发布在 Hugging Face。文中涉及的单价与促销期口径本站不转述,以官网为准。
llama.cpp v1.0.0 升级实操:迁移清单与服务加固
llama.cpp 本周发了 v1.0.0:移除一批弃用 API、加 FP8 KV 缓存与语音端点、集中修服务端安全问题。这篇按官方 Release 与文档,把「从旧版本升上来」做成 9 步可照做的迁移与验收清单,附 9 个真实会卡住的坑。
继续阅读:AI 智能体碰钱怎么授权:代付与只读两条路线的取舍 · llama.cpp v1.0.0 升级实操:迁移清单与服务加固