每晚生成商品页的内部验收报告,运营需要两样东西:页面截图和当时显示价格的正文。搜索系统另外想从页面提取结构化字段。旧实现先截图,再发一个请求提取 JSON。如果正好碰到促销换档,报告便会出现图片里写着旧价、表格里写着新价的情况。把几个格式放进同一次调用可以减少重复打开页面,但这个问题并不会自动消失。另一个不太容易察觉的变化是,原本可选的一项抽取失败,现在可能让整份报告连截图都拿不到。
Cloudflare 在 2026 年 11 月 19 日扩展了 Browser Run 的 /snapshot,让一次页面加载可返回 PDF、链接、选择器抓取结果和 Workers AI 抽取结果。下文把这项能力用于一个可复现的验收场景:什么时候把必需格式放在一起,什么时候先把证据保存下来,什么时候必须承认两样东西不是同一次观测所得。这里的证据是产品团队用于定位问题的页面产物,不是法定存证,也不是对真实交易的授权。
一次加载,仍有多个读取时点
先看一个不需要涉及模型的例子。浏览器打开商品页,服务端渲染出当日售价,随后前端根据地区重新取价。正文捕获若发生在第二次请求返回前,而截图发生在返回后,两份产物即使来自同一页面实例,也可能对应不同状态。页面顶部的主标题不变,比较标题发现不了问题。类似地,PDF 受打印样式和打印事件影响;它与截图不应默认像素一致,即使正文确实没变。
端点文档明确列出八种格式。省略格式时默认是 content 和 screenshot;显式指定至少需要两个不同的格式,只要一种就用对应的单格式端点。格式按服务既定顺序采集,不按数组顺序。发布说明特别说 PDF 放在最后,因为打印处理器可能修改页面。所以把 PDF 挪到数组开头不是一种冻结方法,也不要利用未公开的其余格式相对顺序推断业务状态。页面脚本可能推进,远端数据可能刷新,等待策略只能降低撞到窗口的概率,不能消灭窗口。
还有两种看起来相同、实际证据不同的状态。第一种是同一捕获中的两个产物:它们共享一次打开页面的背景,但不天然共享一个业务版本。第二种是先截图,第二次导航再抽取:即使 URL 相同,第二次也应有另一个观测 ID。即便两个 HTML 摘要恰巧一样,也只能说明被哈希的字节相同,不证明外链字体、图片请求、浏览器环境或像素相同。若只需要确定商品名,这个差别可能无关紧要;若要判断截图里究竟是哪档价格,它就直接决定证据能不能合并。
先定义验收报告必须留下什么
我会把交付拆成必需产物和派生产物。必需产物由负责复核的人决定:比如可读截图和一份用于核对价格的 HTML。遇到必须同时产出的场景,可用默认的正文加截图组合作为一个必需束,但把业务版本号放进页面可见区域和正文标记,让复核能发现不一致。价格卡片加载完毕后设置明确的就绪标记;仅等待首个价格元素出现可能拿到占位值。对于本来一直刷新的实时页面,最好给验收环境一个不可变的发布版本或可冻结的数据视图,而不是盲目增加等待。
结构化商品信息是派生产物。后端应先存必需结果,再用异步任务从这份固定输入抽取,抽取失败时报告仍可查看。如果网页已带可靠的内嵌结构化数据,优先用确定性的解析器检查字段,省掉一次模型调用。数据需要模型才能解释时,把保存的文本或经验证的最小证据作为模型输入,并为字段做类型和业务校验。若只好对原 URL 再运行浏览器,得到的也是另一项观测;可以放在旁边供复核,不能冒充第一次截图的附属结果。
有一种情况适合直接把 JSON 与正文一起请求:缺少任一结果时业务本来就不能继续,页面受控且每次加载的准备成本很高,又愿意承受整束一起失败。这时省去的导航可能比拆开处理有价值。反过来,用于质量回归的截图并不因为可选摘要失败而失效,此时把它们绑在一起就人为扩大了故障面。这里谈的是调用返回值耦合,不是事务回滚。API 报错既不表示浏览器没加载过页面,也不表示服务给调用者保留了失败前的部分产物;不要基于其中任一个假设继续。
一个不依赖云账号的版本实验
将下列代码存为 capture-lab.mjs,用 Node.js 24 执行 node capture-lab.mjs。只用标准库,临时绑定本机回环接口和随机空闲端口;每次打开同一个 URL 都交付一个新的版本号。源响应是公开演示数据;不需要账户、令牌、云服务或额外依赖。代码里的对象存储是内存 Map,抽取超时是注入的失败,不是一次慢网络请求。这样可以把要验证的断言控制在应用流程本身。
import { createServer } from 'node:http';
import { createHash, randomUUID } from 'node:crypto';
import assert from 'node:assert/strict';
let rev = 0;
const server = createServer((req, res) => {
res.writeHead(200, { 'content-type': 'text/html; charset=utf-8',
'cache-control': 'no-store' });
res.end('<!doctype html><p data-rev="' + (++rev) + '">Public demo</p>');
});
await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
const url = 'http://127.0.0.1:' + server.address().port;
const digest = bytes => createHash('sha256').update(bytes).digest('hex');
const objects = new Map();
const revision = html => {
const match = html.match(/data-rev="(\d+)"/);
if (!match) throw new Error('missing revision');
return Number(match[1]);
};
async function observe() {
const res = await fetch(url, { signal: AbortSignal.timeout(2000) });
if (!res.ok) throw new Error(String(res.status));
const bytes = Buffer.from(await res.arrayBuffer());
const hash = digest(bytes);
objects.set(hash, bytes);
return { captureId: randomUUID(), hash };
}
function derive(ref, injectFailure = false) {
const bytes = objects.get(ref.hash);
if (!bytes || digest(bytes) !== ref.hash) throw new Error('source mismatch');
if (injectFailure) throw new Error('simulated optional timeout');
return { sourceCaptureId: ref.captureId, sourceHash: ref.hash,
revision: revision(bytes.toString('utf8')) };
}
try {
const a = await observe();
assert.throws(() => derive(a, true), /simulated optional timeout/);
assert.equal(derive(a).revision, 1);
const b = await observe();
assert.notEqual(a.captureId, b.captureId);
assert.notEqual(a.hash, b.hash);
assert.equal(derive(b).revision, 2);
assert.equal(derive(a).revision, 1);
assert.throws(() => derive({ ...a, hash: 'missing' }), /source mismatch/);
console.log('7 assertions passed');
} finally {
await new Promise((resolve, reject) =>
server.close(err => err ? reject(err) : resolve()));
}
在 Node.js 24.22.3 上实际运行,输出 7 assertions passed。第一次抓取的必需输入保存后,模拟可选抽取超时并不会让它消失。下一次读取同一 URL 得到版本二,两个观测 ID 和两个内容哈希不同,而重跑第一次的派生任务仍然得到版本一。最后一项测试拒绝不存在的哈希,避免了拿不到原对象时悄悄从当前页面补数据。这个实验不启动真实浏览器,不验证截图、打印或 Workers AI,也不能从模拟失败推算上线超时率。示例的正则只识别实验自己生成的标记,泛用页面应改用受维护的 HTML 解析器和明确的提取规则。
如果想在获准使用的 Cloudflare 账户中做后续验证,可使用 POST https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-run/snapshot,准备账户 ID 及具有相应权限的服务端令牌。先用下面的请求体测必需束,再在单独一次对照中加 JSON;地址换成自己可公开访问、无账号或敏感信息的受控验收页面。本机回环地址只给上面的 Node 演示使用,云浏览器不能访问你的本机回环。令牌不要送入前端,也不要打印到测试输出。
{
"url": "https://example.com/",
"formats": ["content", "screenshot", "json"],
"prompt": "Return a JSON object containing only the page title and the visible revision label, or null if absent.",
"actionTimeout": 60000
}
先检查 HTTP 与响应的成功标记,再记录实际返回的字段;没拿到必需字段要报错,而不是填空字符串。示例地址没有我们的版本标记,本身只适合检查请求形状。包含 JSON 的快照使用 Workers AI,导航、采集、重试和模型请求共同消耗一份 actionTimeout,官方文档说明默认六十秒、最高一百二十秒,并非为每项格式各分配六十秒。公告允许提示或响应定义,端点选项表则把提示标为必需;直接提供明确的提示可以避免把文档差异当成兼容性承诺。上述 HTTP 请求仅按一手文档给出,未在账户中执行。
上线前用四组证据验收
第一组用不可变页面。页面同时输出可见版本和可解析的版本属性,固定视口、语言、色彩设置和外链素材版本。要求截图可人工读到版本,正文中也匹配。若测试发现截图少了关键内容,先看浏览器等到了什么:默认的导航完成不代表页面完成自己的异步渲染,按页面已知标记等待通常比盲设固定睡眠更有意义。不要用无限长等待来遮住页面永远无法到达就绪状态的问题。
第二组用会更新的页面。让页面在首次数据就绪后更换价格,记录两次输出上的业务版本。结果相同只能证明这个样本未捕获到分歧,不能推导端点原子化了页面。如果页面不能提供版本字段,界面就标注「同次捕获,内容版本未核实」。浏览器截到的是当时视口,HTML 可包含隐藏节点或模板,因此字段抽取还要定义“页面上可见”的验证方式。凭 HTML 和截图各自出现了一次数字,不够确定它们指向同一商品与计价条件。
第三组是必需格式失败。给调用侧注入失败响应或移除结果字段,确认没有半成品以「已核验」发布。旧报告可以保留供查看,但标注为上一次成功,别覆盖当前任务的失败原因。一次捕获超时后重新导航时产生新的观测 ID,业务任务 ID 可以沿用。固化 URL 对重试有帮助,但即使 URL 带版本,也需确认后端、素材和地区条件确实受版本约束,否则它只是长得像固定版本。
第四组让可选抽取失败。先从审计视图打开已保存的必需截图和正文;派生状态应保持待复核或失败。修复抽取规则后,只重放已保存的输入,并核对返回结果中的来源 ID、输入哈希和抽取器版本。不要每次从目前的页面抽取再填回旧报告。如果源对象因保留期过期而不可用,要么明确标记无可重放输入,要么生成新的报告观测。除非业务明确允许,否则不能把重新抓取解释成修复旧证据。
让存储、重试和界面说同一种话
最小清单需要业务任务 ID、捕获 ID、捕获开始和完成时间、来源 URL、页面业务版本(可能未知)、请求参数版本、必需文件各自的哈希,以及派生成果的模型或规则版本和来源哈希。捕获时间是区间,不是所有产物共同发生的某个点。若浏览器所在地区、认证方式或视口会影响结果,保留非敏感配置的版本即可,不要把会话 Cookie 和令牌写入清单。HTML 和截图也可能有地址或内部账号等信息;面向业务人员展示前要明确访问权限、保留期和可否外发。
持久化时先写对象与清单,再把状态置为可查看。若对象和数据库无法同事务提交,可以让重复写入按哈希幂等,并让恢复程序查清楚哪些清单引用尚未写齐的对象;孤儿对象另走清理,不让页面把待提交当作完成。抽取任务的去重键可以组合来源捕获 ID、输入哈希与抽取器版本:内容相同但观测不同的记录不会被误串,用新规则跑旧输入也不会覆盖先前的证据。倘若两个产物真的需要并排对比,界面优先依据可验证的版本字段,而不是排序恰好相邻或任务号相同。
日志也要分开统计两段:必需捕获的成功率和耗时、可选抽取的成功率和等待时间。如果截图的响应体过大,先限制视口、页高和数据保留,对大图避免前端一次性解析。这通常比单纯加长云调用超时更容易解释成本。用场景算一笔账:十次截图都成功但有两次抽取超时,绑定调用会让两份截图随着整束失败而无法由应用交付;拆开后可以保留十份可用截图并标明其中两份缺少摘要。这只是故障影响的算例,不是 Browser Run 的性能实测。拆分也不是免费午餐:它需要额外对象存储、派生队列,还涉及删除与回放策略。稳定静态页、所有格式同等重要时,一次调用仍可能是更便宜的选择。
最后不要把被抓取的页面内容直接插进运营后台的可执行文档。显示片段可转义或隔离,结构化结果按白名单模式验证;网页上的文字也不是抽取服务的授权指令。接收任务时限制目标为事先配置的受控页面,不接受任意地址和客户提供的凭据;否则采集器会越过原本的网络、会话和数据边界。能够控制页面时,最好把一个明确的版本标记在源头提供出来。在不控制页面的情况下,宁可让报告说清哪些字段没有同版本证据,也不要让一次成功响应替你承诺它从未提供过的一致性。
评论
暂无评论。