Stagehand 自然语言浏览器自动化完整指南：告别选择器维护，10 行代码让 AI 替你操作网页-开发者社区

Stagehand 自然语言浏览器自动化完整指南：告别选择器维护，10 行代码让 AI 替你操作网页

【免费下载链接】stagehandThe SDK to extract data and interact with any site on the web. Get started with Claude Code, Codex, Eve, Mastra, and more.项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand

写过爬虫的都懂：网站一改版，你手写的选择器集体失效，修起来比写还烦。Stagehand 把这个环节交给 AI——免选择器自动化，你用一句话描述想做的事，它自己找元素、点按钮、把结构化数据拿回来。

⚡ 先跑起来：3 条命令 + 10 行脚本

建一个空目录，装 SDK，跑一个脚本，浏览器窗口就会自己弹出来开始操作：

mkdir my-stagehand-app && cd my-stagehand-app && pnpm init -y pnpm add @browserbasehq/stagehand 'zod@~4.4.3'

index.ts就 10 行：启动浏览器、打开商品页，依次调act / extract / observe三个核心方法，最后关浏览器。

import { browserbase, Stagehand } from "@browserbasehq/stagehand"; import { z } from "zod/v4"; const browser = await browserbase.launch({ apiKey: process.env.BROWSERBASE_API_KEY }); const stagehand = await Stagehand.create({ browser }); const [page] = await browser.context.pages(); await page.goto("https://shop.example.com/product"); const { data } = await stagehand.extract("Extract the product name and price", z.object({ name: z.string(), price: z.number() })); console.log(data); await stagehand.act("Click the 'Add to Cart' button"); await stagehand.close(); await browser.close();

注意 key 是在代码里显式传进去的，SDK 不会偷偷读你的环境变量。这段脚本跑完，终端里会打印出符合 schema 的对象，浏览器角落的商品数加一，整个过程可以肉眼盯着复现。

export BROWSERBASE_API_KEY="your-key" pnpm dlx tsx index.ts

🎯 取数据：免选择器抓回结构化数据

以前取一个价格，你得先定位 DOM 节点，再解析文本、清洗格式，拿到手还是个字符串。现在一行：

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

data是按你给的 zod 结构校验过的类型化对象，直接进日志、进表格、丢给下游，不用二次加工。

🔧 执行操作：一行代码让 AI 替你点按钮

写选择器、调选择器这一步直接省了，一句指令交给 AI：

await stagehand.act("Click the 'Add to Cart' button");

页面改版导致已记录的操作失效时，给Stagehand.create()传selfHeal: true，它会重新推理这个动作并自动重试一次，脚本不会当场报废。

🧭 感知页面：先看后动，多步流程才稳

不确定按钮在不在？先问一句"这页能点什么"：

const { data: actions } = await stagehand.observe("Find the login-related buttons on the page");

返回一组带 selector 的可执行动作，人工确认后再喂给act。更省事的是act可以直接接收observe返回的Action对象，回放时不走模型推理，纯确定性执行——"先看后动"就是多步自动化稳的骨架。

📦 完整走一遍：抓信息 → 加购 → 观察后续

把三种能力串进一个真实业务流：进商品详情页，按结构抓回字段，点加购，再列一遍当前页还能点什么。

const { data: p } = await stagehand.extract("Extract the product details", z.object({ name: z.string(), price: z.number(), inStock: z.boolean(), })); console.log(p); await stagehand.act("Click the 'Add to Cart' button"); const { data: actions } = await stagehand.observe("What can I click on this page?"); console.log(actions.map((a) => a.title));

预期终端输出：

{ name: "Wireless Mouse", price: 29.99, inStock: true } [ "Click the 'Add to Cart' button", "Navigate to 'Backpacks'", "Open 'Reviews'" ]

两次结果都是结构化的：提取回来是符合 schema 的对象，观察回来的是可回放的动作清单，可以直接交给一个 agent 决定下一步往哪走。

⚖️ 边界与代价：别急着上，也别硬套

每次 act / extract 都是一次模型推理，API 成本和单次执行的耗时摆在那里；页面内容本身会变，断言"点完一定跳到某页"要留点余量。所以别硬套：页面永远不变、只跑固定流程的回归测试，手写脚本又快又确定，引入 AI 属于杀鸡用牛刀。它的用武之地是反过来的场景——表单自动填写、盯竞品页面、让 agent 看着页面内容自己决定点哪，这些"选择器维护成本高"的活儿，才值得换。

另外两个实用开关：本地调试把browserbase.launch()换成localBrowser.launch()，用本机 Chrome 省掉云 key；重复调用同一个提取时，给调用传cache: { threshold: 1 }，第二次命中缓存就不再消耗 LLM 调用。