Stagehand AI 浏览器自动化实战：一个脚本跑通网页数据采集全流程

Stagehand AI 浏览器自动化实战：一个脚本跑通网页数据采集全流程

【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand

Stagehand 是一个 AI 浏览器自动化 SDK，用 act、extract、observe 三个原语驱动浏览器，让你不写选择器就能完成点击、填表和抓取。本文用本地浏览器搭一条完整的网页数据采集链路：打开列表页，观察可操作元素，点击进入详情页，最后把结构化数据提取出来。

🎯 场景：从电商页采集商品数据

假设你需要从一个商品列表页批量抓取商品名和价格，再交给下游程序处理。手写选择器很脆弱：站点一改版，脚本就失效。用 Stagehand 的 AI 浏览器自动化，你只用自然语言描述意图，元素定位交给模型。跟完下面几步，你会得到一个在本机跑通的自动化脚本。

📦 动手准备：3 条命令装好 Stagehand

本地运行需要 Node.js 22.18+ 和已安装的 Chrome。初始化项目并安装 SDK：

mkdir my-stagehand-app && cd my-stagehand-app pnpm init -y pnpm install @browserbasehq/stagehand zod

🛠 分步实现

1. 启动本地浏览器并创建实例

先用localBrowser在本机启动一个 Chrome，再把它交给Stagehand.create()。开发阶段用headless: false，你能直接看到浏览器每一步动作，方便排查：

import { localBrowser, Stagehand } from "@browserbasehq/stagehand"; import { z } from "zod/v4"; const browser = await localBrowser.launch({ headless: false }); const stagehand = await Stagehand.create({ browser }); const [page] = await browser.context.pages(); await page.goto("https://example-store.com");

2. 用 observe 预览页面上能做什么

动手前先"侦查"：observe返回当前页面上可执行的操作列表。返回的Action对象之后可以直接回放，不再触发模型推理，这是 Stagehand 省钱提速的核心模式：

const { data: actions } = await stagehand.observe("Find all product links"); console.log(actions.map((a) => a.actionDescription)); // 侦查满意后，执行第一个动作 await stagehand.act("click the first product link");

3. extract 提取结构化数据

进入详情页后，用extract配 Zod schema 取值。Stagehand 会先按 schema 校验再返回，你拿到的是强类型数据，直接落盘或写入数据库：

const { data } = await stagehand.extract( "extract the product name and price", z.object({ name: z.string(), price: z.number() }), ); console.log(data); // { name: "Keyboard", price: 199 }

🚀 调优进阶：成本与速度

• 问题：每步都走大模型，慢且贵。手段：默认挂便宜模型，只在关键提取调用上换强模型，单次调用即可覆盖。
• 问题：重复运行任务时重复计费。手段：切到 Browserbase 云浏览器并开启缓存，相同调用直接返回缓存结果，不消耗任何 token。

const stagehand = await Stagehand.create({ browser, // 换成 browserbase.launch({ apiKey }) 得到 model: { modelName: "google/gemini-2.5-flash" }, // 默认用便宜模型 cache: { threshold: 1 }, // 一次相同结果后开始命中缓存 });

❓ 常见问题

缓存为什么一直不命中？

本地浏览器没有缓存服务，cache选项不生效，必须用browserbase.launch()启动。另外指令措辞是缓存键的一部分，换同义词就会变成新键。

act 点错元素怎么办？

先用observe确认页面实际内容，再给调用传locator把快照范围收敛到你关心的容器，减少无关干扰。

支持 Python 和 Go 吗？

支持。三个原语语义与 TypeScript 版一致，分别用 Pydantic 模型和 Go 结构体替代 Zod schema，API key 也换成对应语言的 launch 参数传递。

📚 延伸阅读

• 快速上手：packages/docs/v4/first-steps/quickstart.mdx
• act 完整参考：packages/docs/v4/basics/act.mdx
• observe 完整参考：packages/docs/v4/basics/observe.mdx
• 缓存最佳实践：packages/docs/v4/best-practices/caching.mdx
• SDK 核心源码：packages/sdk-ts/src/stagehand.ts

【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand