Browser4 使用教程：动态页面采集、结果查询与失败恢复

动态页面采集出错时，先区分三个状态：浏览器有没有打开正确页面，页面数据是否已渲染，以及查询读的是当前 DOM 还是先前保存的快照。把这些状态混在一起，会出现“浏览器显示新价格，程序却一直读旧值”的问题。

本文通过 Browser4 CLI 读取公开动态名言列表，保存文本、作者与来源，再说明怎样迁移到动态详情页、批量执行与补查失败来源。主线使用确定性读取，不需要配置模型。

准备输入地址

先在浏览器找到下列页面并确认内容，再从地址栏复制完整地址。服务或仓库地址从相应账户设置、官方项目的接入说明或克隆菜单取得。不要从示例输出中反推真实地址。

QUOTES_LIST_URL：Quotes to Scrape 的 JavaScript 列表入口，路径为 /js/。
QUOTES_PAGE_2_URL：同一练习站的第二页，路径为 /js/page/2/。

在执行后续命令的同一个 Bash/WSL 终端中设置：

export QUOTES_LIST_URL='<paste-the-actual-quotes-list-url>'
export QUOTES_PAGE_2_URL='<paste-the-actual-quotes-page-2-url>'

下文 JSON 或任务参数中的 <变量名> 是待替换标记，提交前填写刚复制的实际值；JSON 不会自动展开环境变量。结果示例中的 example.16yun.cn 只表示来源字段的形状，不是本文部署的演示站。

安装 CLI 与配套运行时

准备 Node.js 与系统支持的 Chrome/Chromium。执行：

npm install -g browser4-cli
browser4-cli install
browser4-cli --help

CLI 安装和 runtime 下载是两步。仅 npm 安装成功，不代表后端运行时已经准备好。安装器会选择匹配的运行时，保存实际版本；升级时把 CLI 与配套 runtime 一起考虑。环境与命令说明见 Browser4 官方项目。

本文使用 CLI，不猜测一个跨版本通用的 REST 端点。extract、summarize、agent 等 AI 命令另需模型配置，不能把它们与基础 DOM 读取混用。

打开动态列表并确认当前状态

执行：

browser4-cli open --headed "$QUOTES_LIST_URL"
browser4-cli snapshot
browser4-cli get text title

snapshot 用于看当前页面与交互引用，get text 读取指定元素。先确认标题、地址和名言列表。如果页面仍在加载，就等待目标内容出现后再次 snapshot，而不是立即把零条记录解释为站点没有数据。

要读属性时需明确属性名，例如：

browser4-cli get attr 'li.next a' href

属性结果可能是相对地址，不能把它直接当成跨站来源 URL。需要组合下一页时以当前页面为基准解析。

用一段完整表达式读取相关字段

创建 read_page.js，内容如下。这个文件是本次 CLI 查询表达式，正文完整提供，不需要下载项目：

(() => {
  const rows = [...document.querySelectorAll('.quote')].map(card => ({
    text: card.querySelector('.text')?.textContent?.trim() ?? null,
    author: card.querySelector('.author')?.textContent?.trim() ?? null,
    tags: [...card.querySelectorAll('.tags .tag')].map(tag => tag.textContent.trim())
  }));
  if (!rows.length) throw new Error('目标列表尚未出现或选择器失效');
  if (rows.some(row => !row.text || !row.author)) {
    throw new Error('名言文本或作者缺失');
  }
  return { source_url: location.href, title: document.title, rows };
})()

运行并保存 CLI 输出：

browser4-cli eval --file read_page.js > page-1.txt

表达式返回对象，而不是仅执行 console.log。eval 的结果来自返回值，页面控制台输出是另一条诊断通道。page-1.txt 是命令输出留存，不应在未经确认时把它当成某个固定 SDK response schema。

需要程序消费时，可使用该版本的 eval --json 输出方式，先检查实际外层结构与类型，再提取业务对象。不要从日志行中截出第一个花括号，就宣布得到了合法 JSON。

再读第二页，核对来源不同

打开明确的第二页地址，重复状态检查和读取：

browser4-cli goto "$QUOTES_PAGE_2_URL"
browser4-cli snapshot
browser4-cli eval --file read_page.js > page-2.txt

检查两个结果的 source_url 与至少两条正文，确认内容确实改变。任务应得到两份页面结果，不只统计两次 eval 调用。

迁移到动态商品详情时，把 rows 的选择器与字段合同换成目标商品区域，并明确价格含义、币种和业务标识。作者与名言之间的关联来自同一 .quote 容器；商品字段也应保持同样的对象内关联，不能把全页标题数组和价格数组按位置盲目拼起来。

实时查询与 HTML 快照的选择

eval 查询当前 DOM。需要保存页面材料时可以执行：

browser4-cli htmlsnapshot export --file page-2.html

默认的实时快照读取会捕获当前页面；设置 expires 缓存窗口后可能读取存储副本。因此浏览器显示新内容、提取却旧时，要检查是否显式使用了缓存读取，不只是刷新标签。

snapshot 的交互引用与 htmlsnapshot 的内容提取用途不同。前者帮助操作页面，后者用于结构化查询与材料保存。不要把旧引用当成稳定选择器。

批量命令与失败恢复

已有明确操作顺序时，可以先试一组遇错停止的命令：

browser4-cli batch --bail   "goto $QUOTES_LIST_URL"   'snapshot'   'get text title'

如果使用 batch --json，则从标准输入传入非空命令数组：

[
  ["goto", "<QUOTES_LIST_URL>"],
  ["snapshot"],
  ["get", "text", "title"]
]

把数组保存为 commands.json 后执行 browser4-cli batch --json < commands.json。这里的 --json 指批量输入模式，不能简单理解成“让任意位置参数输出 JSON”。

检查每步结果，而不是只看进程是否结束。可能出现某个步骤成功、后一步失败的部分完成；保存失败来源和步骤，修复后只重做尚未正确保存的来源。这个流程是应用侧补查，不声称 CLI 自动提供跨崩溃恢复的业务队列。

检查、关闭与常见问题

结果至少应包含当前来源、标题与每条文本—作者关系。下面只示意一条记录形状：

{"text":"页面实际名言","author":"对应作者","tags":["页面标签"]}

完成后执行 browser4-cli close。关闭会话不等于删除 ~/.browser4 中所有配置或 Profile 数据；需要清理时先确认数据归属。

open 报错。 检查 runtime 安装、浏览器与服务启动日志。还没打开页面时，不先调字段选择器。

eval 输出 null。 确认表达式确实返回业务值，未只执行 console.log；若是选择器没命中，应抛出或返回明确缺失状态，不让 null 混成成功记录。

对象读取总是旧值。 核对实时 DOM、存储快照、缓存窗口与当前标签是不是同一来源。不要把另一 URL 的快照挂到当前页名下。

批量 JSON 被拒绝。 检查输入是不是数组、是否有命令、是否又混入位置参数，以及子命令 token 是否正确。

页面变动后点击失效。 重新 snapshot 取得当前引用；读取字段时优先使用有明确业务含义的稳定规则。

第二页文件与第一页相同。 比较 URL、页面身份和列表内容，确认导航成功、数据就绪。文件名不同并不代表取得了不同页面。

把打开、观察、读取和保存分开检查，能让动态页面采集的问题落到具体一步，而不是每次都重装整个工具。