BrowserBase Stagehand 项目集成指南：在现有 Node.js 项目中安装与使用

BrowserBase Stagehand 项目集成指南：在现有 Node.js 项目中安装与使用

stagehand An AI web browsing framework focused on simplicity and extensibility. 项目地址: https://gitcode.com/gh_mirrors/stag/stagehand

前言

BrowserBase Stagehand 是一个强大的浏览器自动化工具，它结合了 Playwright 的浏览器控制能力和 AI 模型的智能决策能力。本文将详细介绍如何在现有 Node.js 项目中集成 Stagehand，帮助开发者快速构建智能化的浏览器自动化解决方案。

环境准备

运行时环境选择

Stagehand 目前仅支持 Node.js 运行时环境。虽然现代 JavaScript 运行时如 Deno 和 Bun 提供了许多创新特性，但它们目前存在以下限制：

• Bun 完全不支持：由于 Bun 尚未兼容 Playwright 核心功能
• Deno 兼容性问题：Playwright 在 Deno 中的支持尚不完善

建议使用 Node.js 16 或更高版本以获得最佳兼容性。

安装 Stagehand

基础安装

根据您使用的包管理器，选择以下命令之一进行安装：

# npm 用户
npm install @browserbasehq/stagehand zod

# pnpm 用户
pnpm add @browserbasehq/stagehand zod

# yarn 用户
yarn add @browserbasehq/stagehand zod

注意：zod 是必需的依赖项，用于定义和验证结构化输出。

Playwright 浏览器安装（本地开发）

要在本地运行 Stagehand 脚本，需要安装 Playwright 浏览器：

# npm 用户
npx playwright install

# pnpm 用户
pnpm add playwright && pnpm playwright install

# yarn 用户
yarn add playwright && yarn playwright install

基本使用示例

以下是一个完整的 Stagehand 使用示例，展示了如何初始化、导航页面、执行操作和提取数据：

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

async function main() {
  // 初始化 Stagehand 实例
  const stagehand = new Stagehand({
    env: "LOCAL", // 环境配置
    modelName: "gpt-4o", // 使用的 AI 模型
    modelClientOptions: {
      apiKey: process.env.OPENAI_API_KEY, // API 密钥
    },
  });
  
  await stagehand.init(); // 初始化

  const page = stagehand.page;

  // 页面导航
  await page.goto("https://www.google.com");
  
  // 执行智能操作
  await page.act("在搜索框中输入'Browserbase'");

  // 提取结构化数据
  const { title } = await page.extract({
    instruction: "第一个搜索结果的标题",
    schema: z.object({
      title: z.string(),
    }),
  });

  console.log("提取的标题:", title);

  await stagehand.close(); // 关闭
}

main();

配置详解

Stagehand 初始化时需要以下关键配置：

1. env：运行环境，本地开发使用 "LOCAL"
2. modelName：指定使用的 AI 模型（如 "gpt-4o"）
3. modelClientOptions：模型客户端配置，至少需要提供 API 密钥

核心功能

1. 智能页面操作 (page.act)：

   • 通过自然语言描述操作意图
   • Stagehand 会自动解析并执行相应操作

2. 结构化数据提取 (page.extract)：

   • 使用 Zod 定义数据结构
   • 通过自然语言指令指定提取内容
   • 返回类型安全的结构化数据

3. 页面控制：

   • 继承 Playwright 的所有页面控制能力
   • 支持导航、点击、输入等基础操作

最佳实践

1. 环境变量管理：

   • 将敏感信息如 API 密钥存储在环境变量中
   • 使用 dotenv 等工具管理开发环境变量

2. 错误处理：

   • 使用 try-catch 块捕获操作异常
   • 实现重试逻辑处理临时性失败

3. 资源清理：

   • 确保在脚本结束时调用 stagehand.close()
   • 避免浏览器实例泄漏

进阶技巧

1. 自定义操作：

   • 结合 Playwright 原生 API 实现复杂操作
   • 将常用操作封装为可复用函数

2. 多页面控制：

   • 利用 browser.newPage() 创建多个页面实例
   • 实现并行页面操作

3. 性能优化：

   • 合理设置操作超时时间
   • 避免不必要的页面重载

总结

通过本文，您已经学会了如何在现有 Node.js 项目中集成 BrowserBase Stagehand。这个强大的工具将浏览器自动化与 AI 能力相结合，能够显著提升自动化脚本的智能水平和开发效率。从简单的页面操作到复杂的数据提取，Stagehand 都能提供优雅的解决方案。

stagehand An AI web browsing framework focused on simplicity and extensibility. 项目地址: https://gitcode.com/gh_mirrors/stag/stagehand