Cloudflare /snapshot 和剪藏,怎么选
2026年11月19日,Cloudflare Browser Run 的更新日志把 /snapshot 扩了一圈:同一次页面加载,除了原来的 HTML(content)、截图、Markdown 和无障碍树,还可以带回 pdf、links、scrape 和 json。几种格式要绑在同一次渲染上时,用这次扩展。如果给 LLM、RAG 或代理的只是某一页干净 Markdown,就改走单独的 /markdown,或者直接剪你已经打开的那个标签。
下面的 Cloudflare 事实于 2026年11月21日(北京时间)核对,来源是 11月19日更新日志、/snapshot 与 /markdown 快速操作页,以及 snapshot API 参考。Web2MD 首页和文中其他产品页同一天重读。
Short answer
一次 Browser Run 加载要同时带回至少两种格式,包括 2026年11月19日新增的 pdf、links、scrape 和 json 时,用 /snapshot。模型只要这一页 Markdown 时,用 /markdown,或剪下已经打开的标签。
11月19日,/snapshot 到底多了哪四种结果?
那条更新的标题是 “Capture PDFs, links, scraped elements, and extracted JSON with /snapshot”。在此之前,/snapshot 只给 HTML、截图、Markdown 和无障碍树。还要 PDF 或结构化数据,就得把同一页再准备一遍。
四种新结果各自沿用原来的单接口字段。pdf 打印页面,pdfOptions 与 /pdf 相同。links 收集链接,visibleLinksOnly 和 excludeExternalLinks 与 /links 相同。scrape 返回 elements 匹配到的元素,载荷与 /scrape 相同,而且必须传 elements。json 用 Workers AI 从页面 HTML 里抽结构化数据,字段与 /json 一样,包括 prompt、response_format 和 custom_ai。更新日志写明:prompt 或 response_format 必须有一个,这次请求会产生 Workers AI 用量。
新旧格式都从 formats 传入。快速操作页的说法是,一个请求代替分别调用各个接口。不传 formats 时,默认是 ["content", "screenshot"]。
这不是站点用 Accept: text/markdown 应答的那套能力。那一篇在Cloudflare Markdown for Agents,本文不重复它的配置。
一次 /snapshot 可以组合哪些格式?
接受的值有八个。至少要两个彼此不同的格式。只要一个,就用对应的单格式接口;只要 Markdown,接口是 /markdown。
| 格式 | 结果字段 | 文档挂上的选项 | 单格式接口 |
| --- | --- | --- | --- |
| content | result.content | HTML | /content |
| screenshot | result.screenshot | screenshotOptions、selector、scrollPage | /screenshot |
| markdown | result.markdown | Markdown | /markdown |
| accessibilityTree | result.accessibilityTree | interestingOnly、root | /accessibilityTree |
| pdf | result.pdf | pdfOptions | /pdf |
| links | result.links | visibleLinksOnly、excludeExternalLinks | /links |
| scrape | result.scrape | 必须有 elements | /scrape |
| json | result.json | Workers AI | /json |
2026年11月21日读到的三页,对 JSON 字段的写法并不一致。更新日志说 prompt 或 response_format 必填。/snapshot 表格把 prompt 标成必填,旁边还有 response_format 和 custom_ai。API 参考把 prompt 和 response_format 标成模式里的可选属性。以你正在对照的那一页为准。
json 会产生 Workers AI 用量。JSON 快照的一个 actionTimeout 覆盖导航、采集、重试和这次 AI 请求,默认 60 秒,最长 120 秒。这几页都没有写出 Workers AI 的价格、速率限制或套餐名称,这里也不另造一个数字。
采集顺序是固定的,不跟 formats 数组走。更新日志写明 PDF 最后打印,因为打印处理可能改变页面。活页面在两次采集之间可能已经变了。任何一种格式失败,整个请求失败。
请求要带 url 或 html。快速操作页写的是 POST https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-run/snapshot,令牌权限为 Browser Run - Edit;Worker 里则是 env.BROWSER.quickAction("snapshot", ...),不需要 API 令牌。API 参考把方法写成 POST /accounts/{account_id}/browser-rendering/snapshot。路径一段是 browser-run,另一段是 browser-rendering。本文不替你选定哪一个。
只想要 Markdown 时,为什么该改用 /markdown?
/markdown 把网页收成 Markdown。文档列出的用途是:给摘要、差异和向量准备文本,存下一篇文章或一份文档,去掉样式和脚本、留下可读内容和链接。路径是 POST https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-run/markdown,或 Worker 里的 env.BROWSER.quickAction("markdown", { url })。同样提供 url 或 html。
JavaScript 很重的页面,两份文档说的是同一件事:默认加载可能是空的,因为浏览器认为页面已经完成,脚本还没画完。两边都指向 gotoOptions.waitUntil 设为 networkidle0 或 networkidle2;如果你知道哪个元素代表内容到了,可以用 waitForSelector。
两边都允许设置 userAgent,也用同一段限制:userAgent 不能绕过机器人防护。Browser Run 的请求始终会被识别为机器人。想识别这些请求的站点,应看不可配置的请求头,而不是 User-Agent 字符串。
所以只要一份 Markdown,调用 /markdown。同一次加载还要另一种已接受的格式,才用 /snapshot。formats 里只放 "markdown",不满足“至少两个”的规则。
什么时候,剪藏才是交给模型的那一页?
Browser Run 在 Cloudflare 的浏览器里打开 URL,并且始终被识别为机器人。剪藏读的是你自己的浏览器里已经渲染好的文档。登录、站点挑战,或这个标签自己的脚本,才是文字出现的原因时,这两份文档往往不是同一份。
2026年11月21日的首页写的是安装扩展、打开页面、点图标、把 Markdown 交给 AI。文档是 Alt+M 或点图标。llms.txt 仍标 “Last verified: 2026-11-14”,快捷键写成 Ctrl+M / Alt+M。首页和价格页的常见问题写 Chrome、Firefox,Edge 在开发,Safari 在计划。文档开头只写 Chrome。
首页的 Send to AI 发给 Claude、ChatGPT、Gemini、Perplexity、Grok 或 DeepSeek。免费每天 3 次,Pro 在首页上没有每日上限。价格页是:免费 0 美元、每天 3 次、资料库最近 50 条;月付 9 美元(划掉 15 美元,标着 40% OFF);年付 49.99 美元,写着每月 4.17 美元;30 天通行证 15 美元;终身 149 美元。首页 Pro 一格是划掉 15 美元后的每月 4.17 美元,对的是年付,不是 9 美元月付。
数据落在哪里,几页互相不一致。首页和价格页说转换都在本地,内容不会上传或存储。llms.txt 说免费档在服务器上转公开页,Pro 在已登录的浏览器里转。更新日志里,v1.8.0(2026年8月17日)用 Privacy Mode 关掉保存,v2.0.0(2026年10月26日)是最新一条:导出 ChatGPT、Claude、Gemini、DeepSeek、Perplexity 的对话,以及浏览器内生成、不限次数且免费的 PDF。
Agent Bridge 给托管抓取看不到的页面。普通公开 URL 用托管接口;登录、挑战或 JavaScript 之后用桥。它沿用你的 Chrome 会话,不绕过身份验证、权限、MFA 或验证码。Chrome 和扩展要开着。agent_convert 一个 URL,agent_batch_convert 最多 50 个。命令是 npm i -g web2md-mcp-server && web2md-mcp-setup。v1.9.3(2026年9月5日)点名 Claude Code、Codex、Cursor、Claude Desktop。
首页自己还写大约少 65% token、1,000+ 安装。llms.txt 说基准测试没有报告 token 百分比。
| | /snapshot | /markdown | 打开标签上的剪藏 |
| --- | --- | --- | --- |
| 拿回什么 | 一次加载的至少两种格式 | 一个 URL 或一段 HTML 的 Markdown | 已经渲染出来的那个标签 |
| 适合喂给模型 | 同时还要 PDF、链接、抓取、JSON、截图、HTML 或无障碍树 | 只要 Markdown,且机器人身份的加载够用 | 你正在看的标签,包括机器人请求带不走的会话 |
| 会话 | 始终是机器人。userAgent 不能绕过防护 | /markdown 页同样如此 | 你的浏览器。Agent Bridge 沿用 Chrome 登录,不绕过它 |
| 额外规则 | 至少两种。scrape 要 elements。JSON 产生 Workers AI 用量 | 不能做成只含一项的 /snapshot | 浏览器和扩展保持打开。没加载过的内容可能缺失 |
| 失败时 | 一种失败则整次失败。PDF 最后打印 | 这一次调用失败,或返回 Markdown | 你只能留下已经渲染的部分 |
这一页要交给 LLM、RAG 或代理时,按什么顺序做?
- 在留下的 Markdown 开头写上 URL 和抓取日期。以后引用的是这份文件,不是下一次加载。
- 只要 Markdown,而且公开 URL 够用,就用
url或html调用/markdown。不要向/snapshot只提交一种格式。 - 同一次加载还要另一种格式,就向
/snapshot提交至少两个不同的formats。scrape带上elements。json以你对照的文档为准:更新日志要prompt或response_format,表格把prompt标成必填。它会产生 Workers AI 用量。PDF 最后打印。一种失败,整次失败。 - 页就在眼前,或只因为你登录了才画出来,就剪藏。首页的路径是点图标,再复制或 Send to AI。代理要保持 Chrome 运行,调用
agent_convert或agent_batch_convert。 - 一包结果,例如 PDF 加链接,或 HTML 加 JSON,留给
/snapshot。模型要引用的那一页,留给剪藏。
选 Web2MD 方案前再看一次价格页。2026年11月21日打开的 Cloudflare 页面没有公布 Browser Run 的价格或速率限制。
这和 Cloudflare Markdown for Agents 是同一件事吗?
不是。Cloudflare Markdown for Agents 讲的是内容协商:客户端发送 Accept: text/markdown,站点所有者在自己的 zone 上打开这项功能。别人网站上的任意一篇文章,这个开关不在你手里。
/snapshot 和 /markdown 是 Browser Run 的快速操作。你提交 url 或 html,Cloudflare 的浏览器去加载,再按你点名的格式返回。剪藏是第三条路:标签已经渲染完,Markdown 从那份文档里取。Accept 头看前一篇。要在多格式快照、只要 Markdown 的渲染、和眼前这一页之间做选择,看这一篇。
哪些说法需要你自己再核对?
下面与 2026年11月21日读到的页面一致。
11月19日 /snapshot 新增了什么?
一次加载中的 pdf、links、scrape、json,加上原有的 HTML(content)、截图、Markdown 和无障碍树。
/snapshot 能只返回 Markdown 吗?
不能。至少两个不同格式。只要 Markdown 就用 /markdown。
scrape 和 json 要什么?
scrape 要 elements。更新日志写 json 要 prompt 或 response_format,表格把 prompt 标为必填。json 走 Workers AI。页面上没有用量价格。
一种格式失败会怎样,PDF 何时生成?
一种失败,整次失败。顺序固定,不看 formats 数组。更新日志把 PDF 放在最后,因为打印可能改页面。
userAgent 能让它像普通浏览器吗?
不能。两页都写 userAgent 不绕过机器人防护,Browser Run 始终被识别为机器人。
什么时候该用剪藏?
要的是已经打开的那一页,包括机器人带不走的登录。Agent Bridge 沿用 Chrome 会话,不绕过验证。公开页只要 Markdown 用 /markdown,一次要多种格式用 /snapshot。