Stagehand v4 快速入门：本地浏览器与结构化提取

这是什么？适合谁？

Stagehand 是 Browserbase 开发的浏览器 Agent SDK。 它把自然语言动作 act、页面元素发现 observe 与结构化提取 extract 接到浏览器驱动上。 适合编写内部网页工具、信息提取脚本和带人工确认的后台操作流程的开发者。

本文使用 v4 接口，不沿用旧版构造器与初始化方式。 核验日官方 TypeScript 包源码版本为 4.3.0，安装要求 Node.js 22.18.0 或更新版本。 本文没有执行 SDK；示例依据官方 v4 quickstart 与安装文档整理。

如果需求只是固定选择器点击与回归断言，先判断是否真的需要模型。 模型有助于处理语义定位，却引入推理费用、误判和网页内容外发边界。 “能生成符合 schema 的对象”也不等于对象中的事实一定正确。

前置条件

• 已安装 Chrome；本地模式通过 Chrome DevTools Protocol 驱动浏览器。
• Node.js 至少 22.18；本文使用 npm 和 TypeScript。
• 模型供应商 API key，以及该账号可用的模型名称。
• 一个不含机密、无需登录的页面作为首任务目标。
• 本地模式不能使用 Browserbase Model Gateway，必须显式传模型和 key。
• 生产账号、支付与删除流程不能作为首次自动化测试对象。

官方还提供 Python 与 Go SDK，但不能逐行替换 TypeScript 语法。 Python、Go 的最低版本与安装包以各自当前文档为准。

安装与第一个任务

1. 创建示例项目

mkdir my-stagehand-app
cd my-stagehand-app
npm init -y
npm install @browserbasehq/stagehand@4 "zod@~4.4.3"
npm install --save-dev tsx typescript @types/node

保留 package-lock.json，团队后续用相同锁文件安装。 Zod 限定在 4.4.x，是官方 quickstart 给出的类型兼容建议。 安装 SDK 不等于已经安装 Chrome，浏览器需要单独具备。

2. 创建 index.ts

首任务只读取 Example Domain 的公开页面，不登录，不发送表单。 模型名称采用核验日官方 README 的示例；账号是否可用须自行确认。 API key 从应用自己的环境读取，不复制文档中被截断的字段。

import { localBrowser, Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod/v4";

async function main() {
  const apiKey = process.env.OPENAI_API_KEY;
  if (!apiKey) throw new Error("请在当前环境设置 OPENAI_API_KEY");
  const browser = await localBrowser.launch();
  try {
    const stagehand = await Stagehand.create({
      browser,
      model: { modelName: "openai/gpt-5.4-mini", apiKey },
    });
    try {
      const [page] = await browser.context.pages();
      if (!page) throw new Error("浏览器未提供初始页面");
      await page.goto("https://example.com");
      const { data } = await stagehand.extract(
        "Extract the main heading and explain the page purpose in one sentence.",
        z.object({ heading: z.string(), purpose: z.string() }),
      );
      console.log(JSON.stringify(data, null, 2));
      const observed = await stagehand.observe("Find the learn more link");
      console.log(observed.data);
    } finally {
      await stagehand.close();
    }
  } finally {
    await browser.close();
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

3. 运行与判断结果

通过你的安全环境管理方式设置 OPENAI_API_KEY，不要把密钥写进源文件。 Stagehand 不会自动读取 .env；若用该文件，需要应用自己加载。

npx tsx index.ts

成功判据：Chrome 被启动，终端输出带 heading 与 purpose 的 JSON，随后输出发现的链接信息并退出。 人工核对 heading 是否与页面的 Example Domain 标题一致，purpose 是否符合页面用途。 发现列表可能受页面变化或模型影响，不要断言它永远返回固定数量。 失败时保留错误类型，先区分浏览器启动、模型鉴权和提取环节。

初级用法：三类操作不要混用

observe 用于发现可交互元素，v4 的结果列表放在 .data 中。 在使用 data[0].selector 前检查列表非空，并确认所选元素确实符合任务。 不要把“模型返回一个 selector”理解为“这个 selector 必然可用于敏感操作”。

act 执行自然语言动作，例如在已经打开的无敏感演示页面上：

await stagehand.act("Click the learn more link");

这行放在上一段脚本的会话内、stagehand.close() 之前使用。 它可能离开当前页面；首次提取示例刻意不执行点击，方便先验证只读路径。

extract 提供 schema 与提取指令，v4 返回对象中的 .data 才是提取数据。 给字段明确含义，比写“把页面都给我”更容易检查；空值策略也应在 schema 中明确。 固定路径的导航继续用 page.goto，不必每一步都让模型重新推断。

高级玩法

1. 先发现，再用 locator 执行

对登录表单，可先发现输入框，再由程序使用 selector 填入凭据。 这能避免把密码直接写进自然语言指令，但页面内容仍可能进入后续模型上下文。 执行前检查候选数与元素含义，填完后不要立即运行提取整页内容的指令。 凭据保护需要日志脱敏、最小权限账号与单独的会话策略，不能只靠一种调用方式。

2. 用 userDataDir 复用专用会话

官方给出的本地持久化方式是 localBrowser.launch({ userDataDir: "./browser-data" })。 为自动化建立专用目录，不使用自己的日常 Chrome 主配置目录。 该目录可能含 cookie 和登录状态，应忽略版本控制、限制读取，并按团队政策清理。 复用会话能减少重复登录，但登录过期或二次验证仍需正常处理，不能绕过安全机制。

3. 切换到 Browserbase 云端

云端使用 browserbase.launch，显式传入 Browserbase key。 未指定模型时，官方 Model Gateway 可选择和认证模型；这与本地模式不同。 服务器端 cache: true 用于复用重复动作，不应当作所有请求免费或永不失效的保证。 先核对当前 Browserbase 费用与数据政策，再迁移真实业务会话。

4. 建立字段级业务断言

schema 检查类型，应用另行检查发票金额、时间范围、条目数量和跨页完整性。 例如分页表格应逐页处理并在程序中去重，不能只让模型口头说“已提取全部”。 保存任务输入、版本与脱敏结果，出现页面变更时可复核是否遗漏字段。 对付款、发布和删除动作，保留人工确认与执行后读取验证。

小技巧

1. 先只跑 extract 和 observe，验证鉴权与页面读取后再加入 act。
2. 指令只描述一个明确动作，避免把登录、导出和发送混成一条不可检查的操作。
3. 本地 key 要由代码显式传入；仅设置环境变量不会自动完成 SDK 配置。
4. 用 finally 分别关闭 Stagehand 与 browser，避免失败后留下进程。
5. 保留锁文件，并在升级前检查 v4 的迁移说明，不混用旧教程。
6. 结构化结果仍要对照页面；用必填字段和业务断言捕捉空结果。

常见踩坑

以下是基于官方接口与安装约束推导的风险，非本站运行经验。

1. create 或 localBrowser 不存在

现象：从 SDK 导入后找不到 v4 接口。 原因：安装到旧版本，或者代码仍按旧构造器方式编写。 解决：检查依赖与锁文件，按同一 v4 文档统一接口，不混用 new Stagehand 的旧启动流程。

2. 已设置 key 却仍报鉴权错误

现象：启动浏览器后模型初始化失败。 原因：SDK 不自动读取环境，也不会自动加载 .env，或 key 与模型账号不匹配。 解决：在代码中读取变量并传入 model.apiKey，检查供应商与账号可用模型。

3. extract 返回对象没有预想字段

现象：访问 result.heading 得到空值。 原因：v4 把结构化结果放在 result.data，或页面内容本身与 schema 不符。 解决：先检查完整返回结构，访问 .data，并人工核对页面与提取范围。

4. Zod schema 出现类型冲突

现象：把 schema 传给 extract 时 TypeScript 报类型错误。 原因：官方提示较新的 Zod minor 可能与支持类型不匹配。 解决：按 quickstart 固定 zod@~4.4.3，使用 zod/v4 导入并检查重复依赖。

5. 本地环境没有可用浏览器

现象：脚本尚未导航就失败。 原因：缺少 Chrome，或运行环境不允许启动浏览器进程。 解决：按安装文档配置 Chrome 和运行权限，不通过关闭系统安全隔离来强行启动。

常见问题 FAQ

Q1：一定要购买 Browserbase 吗？

A：本地 Chrome 路径不需要云端浏览器，但模型 API 与本地资源仍可能收费；云端是另一种部署选择。

Q2：开源 SDK 是否等于没有模型费？

A：不是。MIT 许可与推理账单不同，云端浏览器和相关增值服务也应单独核算。

Q3：能保证改版后脚本不坏吗？

A：不能。官方提供语义定位与 self-healing 机制，但本站未测改版恢复率，业务断言仍不可省。

Q4：为什么不用 Playwright 初始化？

A：当前 v4 安装文档说明直接通过 CDP 驱动浏览器、没有 Playwright 依赖；相似 API 不代表对象可以互换。

Q5：可以直接处理生产支付或后台发布吗？

A：不建议从这类动作开始。先使用测试账号与只读流程，敏感动作需要授权、确认和执行后核验。

权限、安全、成本与声明

网页内容、模型请求、cookie、截图与日志属于不同的数据边界，应分别评估。 不要把含个人信息的页面默认交给外部模型，也不要提交 browser-data。 SDK 许可为 MIT，不含特定服务额度、SLA 或准确性承诺。 本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。

参考链接

核验日期：2026-11-03。以 v4 文档和实际安装依赖为准。

• 官方站点
• 官方仓库
• v4 Quickstart
• v4 安装要求
• TypeScript 包版本与运行时约束