页面抽取接口返回了 JSON,字段类型正确,测试也通过了,但这些值可能根本不是从页面里提取出来的。
Cloudflare 在 2026 年 11 月 13 日宣布,Browser Run Quick Actions 支持本地开发。官方 RSS 将该公告的发布时间标为 UTC 18:00,对应北京时间 11 月 14 日 02:00,距本文写作约 32 小时。现在,在 npx wrangler dev 下调用浏览器绑定的 .quickAction(),可以使用本机 Chrome。
这对截图、页面内容处理等开发流程很实用。不过,本地 json 动作仍是模拟:它返回符合 schema 的占位数据,并不调用真实抽取模型。如何区分“接口接通了”和“内容提取对了”,是这次更新最值得注意的地方。
背景:把常见浏览器操作放进本地开发循环
Quick Actions 将截图、获取 HTML、生成 PDF、提取 Markdown 等常见浏览器任务封装为简单接口。开发者既可以使用 REST API,也可以通过 Worker 的浏览器绑定调用。
此前,公告所述的本地调用会因未实现 quickAction 方法而失败,需要切到远端模式。此次更新让这些调用能进入本地调试流程,不必只为验证每一处接口调整就依赖远端浏览器。
这里应区分两条路径:Worker 代码在哪里运行,以及浏览器操作由哪里执行。开启本地开发并不意味着所有相关服务都在本机实现;本地浏览器能够打开页面,也不意味着依赖 AI 的动作已经具备本地推理能力。
技术边界:真实浏览器与模拟抽取同时存在
官方 Quick Actions 文档说明,本地模式使用本机 Chrome,但 json 与 Kitesurf 有例外。
json 的占位结果按 response_format.json_schema 生成。字段指定 const、enum 或 default 时,会使用相应值,枚举采用首项;其他字段可能得到空字符串、零、false 或空数组等值。Wrangler 也会输出警告。
假设一个产品页面的 schema 包含以下字段:
| 字段设计 | 本地结果可能表达什么 | 不能证明什么 |
|---|---|---|
| 普通字符串标题 | 用空字符串走通解析流程 | 页面标题已被识别 |
| 布尔型库存状态 | 用 false 检查数据类型和分支 |
产品确实缺货 |
| 带枚举的分类 | 用第一项检查枚举处理逻辑 | 模型判断产品属于该类 |
这些是根据官方占位规则构造的说明性例子,并非本文运行得到的结果。
另一个限制是 Kitesurf 暂不支持本地模拟。如果传入 browser: "kitesurf",本地调用会报错。不能把这类失败直接归因于目标页面,也不能因为 Chrome 路径通过,就认为另一种浏览器路径已验证。
启用方式:检查绑定,也检查兼容日期
通过 Worker 使用该能力,需要配置浏览器绑定。官方要求 .quickAction() 的兼容日期为 2026-03-24 或更晚。
对已有项目,应先核对当前兼容日期和 Wrangler 配置,而不是把文档示例整份覆盖进去。为一个接口调整日期,也可能同时采用其他运行时行为,仍需按项目测试流程验证。
如果需要真实的 json 抽取结果,或要在开发阶段使用 Kitesurf,文档给出的方式是将浏览器绑定设为远端:
1 | { |
这只是绑定配置片段,不是完整项目文件,也不是本文已经执行的部署。已有绑定包含其他选项时,应保留并合并。
远端模式改变了浏览器操作的执行位置,验证时应确认目标页面可达、账户配置可用,并关注实际服务用量。使用受保护页面时,也应明确哪些内容允许发送到远端,不把本地测试数据未经检查地搬过去。
实践启示:结构测试和质量测试各自负责什么
本地占位并非没有价值。它可以帮助检查字段解析、序列化、返回结构以及业务代码对空值的处理。例如,标题为空时界面是否崩溃,空数组是否触发异常,布尔值是否被错误当成字符串。这些测试不需要模型真实理解页面。
但占位值会让某些测试显得过于顺利。假如分类字段的枚举首项恰好是测试期望值,仅比较分类结果就可能得到一个没有实际意义的成功。测试应该明确标记数据来源,不要让模拟路径参与抽取准确率统计。
下面是本文建议的分层验证方法,不是平台自动执行的验收:
- 本地阶段检查请求构造、schema、结果解析和错误处理,主动覆盖空值及不完整数据。
- 远端阶段使用少量可公开访问或获准使用的固定样本,比较字段内容与人工确定的预期值。
- 上线前检查实际目标页面的加载时机、登录条件和失败处理,不只判断请求是否成功。
真实的 /json 接口允许通过 prompt 或 JSON schema 描述预期输出。schema 能约束数据形状,仍不能证明内容正确。标题取错区域、库存状态理解错误,即便结果符合类型定义,也属于需要单独发现的问题。
对 JavaScript 动态页面,还应确认所需内容已经渲染。官方抽取文档提供等待页面或指定元素的选项,但等待条件要根据页面设计,不能把某一种等待策略当成所有站点的通用答案。
把模拟结果留在测试边界内
开发环境的占位数据不应默默进入正式索引、业务数据库或对外报告。可以在测试流水线中明确区分本地模拟与远端抽取,并为质量验收保留样本、预期结果和执行模式。
同时,不应仅凭空字符串或 false 判断“这一定是模拟”。真实页面也可能缺少字段,真实模型也可能提取失败。更可靠的办法是记录测试时的配置与执行环境,再检查结果,而不是通过结果猜测运行路径。
本文只核对了官方公告、RSS 和文档,没有安装浏览器、执行 Quick Actions、调用付费抽取服务或修改生产配置。因此,上面的步骤属于实施建议,不代表已完成的实测结论。
结语
本地 Quick Actions 缩短了浏览器任务的开发反馈路径,但本地通过的含义需要说清楚:有时验证的是程序能否处理一份 JSON,有时验证的才是网页信息是否抽取准确。
把这两类测试分开,既能利用本地模拟提高开发效率,也能避免把一个格式正确的占位结果当成上线依据。
参考来源
- Cloudflare:Browser Run Quick Actions now work in local development;官方 RSS。近期公告及发布时间依据。
- Browser Run:Quick Actions 与本地测试。绑定、兼容日期、占位规则及远端模式。
- Browser Run:JSON 结构化抽取。真实抽取输入、输出与动态页面处理背景。
- Browser Run:Wrangler 配置。浏览器绑定配置参考。