在Next.js项目中集成Stagehand实现浏览器自动化

在Next.js项目中集成Stagehand实现浏览器自动化

【免费下载链接】stagehand An AI web browsing framework focused on simplicity and extensibility. 项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand

什么是Stagehand

Stagehand是一个强大的浏览器自动化工具，它基于Playwright构建，可以与Next.js框架无缝集成。通过Stagehand，开发者可以在服务器端执行复杂的浏览器操作，如页面导航、元素点击和数据提取等，非常适合构建需要浏览器自动化的Web应用。

为什么选择Stagehand与Next.js结合

Next.js作为流行的React框架，提供了出色的服务器端渲染能力。结合Stagehand后，开发者可以：

1. 在服务器端执行浏览器自动化任务
2. 构建需要浏览器交互的后台服务
3. 实现复杂的数据抓取和网页操作
4. 创建自动化测试和监控工具

环境准备

在开始之前，需要确保你的项目已经具备以下条件：

1. 一个已创建的Next.js项目
2. 有效的Browserbase API密钥和项目ID
3. Node.js环境（建议使用最新LTS版本）

安装依赖

首先需要在项目中安装必要的依赖包：

npm install @browserbasehq/stagehand @browserbasehq/sdk playwright zod

这些依赖包的作用分别是：

• @browserbasehq/stagehand: Stagehand核心库
• @browserbasehq/sdk: Browserbase SDK
• playwright: 浏览器自动化库
• zod: 数据验证库

核心实现步骤

1. 创建服务器端操作

在app/stagehand/main.ts中定义三个核心函数：

"use server";

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

// 主Stagehand脚本
async function main(stagehand: Stagehand) {
  const page = stagehand.page;
  
  // 导航到Stagehand文档页面
  await page.goto("https://docs.stagehand.dev/");
  
  // 点击快速开始链接
  await page.act("click the quickstart link");
  
  // 提取页面标题
  const { title } = await page.extract({
    instruction: "extract the main heading of the page",
    schema: z.object({
      title: z.string(),
    }),
  });

  return title;
}

// 初始化并运行Stagehand
export async function runStagehand(sessionId?: string) {
  const stagehand = new Stagehand({
    env: "BROWSERBASE",
    apiKey: process.env.BROWSERBASE_API_KEY,
    projectId: process.env.BROWSERBASE_PROJECT_ID,
    verbose: 1,
    logger: console.log,
    browserbaseSessionID: sessionId,
    disablePino: true,
  });
  
  await stagehand.init();
  await main(stagehand);
  await stagehand.close();
}

// 启动Browserbase会话
export async function startBBSSession() {
  const browserbase = new Browserbase();
  const session = await browserbase.sessions.create({
    projectId: process.env.BROWSERBASE_PROJECT_ID!,
  });
  
  const debugUrl = await browserbase.sessions.debug(session.id);
  
  return {
    sessionId: session.id,
    debugUrl: debugUrl.debuggerFullscreenUrl,
  };
}

2. 创建客户端组件

在app/components/stagehandEmbed.tsx中创建客户端组件：

"use client";

import { useCallback, useState } from "react";
import { runStagehand, startBBSSession } from "@/app/stagehand/main";

export function StagehandEmbed() {
  const [sessionId, setSessionId] = useState<string | null>(null);
  const [debugUrl, setDebugUrl] = useState<string | null>(null);

  const startSession = useCallback(async () => {
    const { sessionId, debugUrl } = await startBBSSession();
    setSessionId(sessionId);
    setDebugUrl(debugUrl);
    await runStagehand(sessionId);
  }, []);

  return (
    <div>
      {!sessionId && <button onClick={startSession}>Start Session</button>}
      {sessionId && debugUrl && (
        <iframe src={debugUrl} className="w-full h-full" />
      )}
    </div>
  );
}

3. 在页面中使用组件

最后，在页面文件中使用我们创建的组件：

import { StagehandEmbed } from "@/app/components/stagehandEmbed";

export default function Home() {
  return (
    <main>
      <StagehandEmbed />
    </main>
  )
}

工作原理解析

1. 会话启动：用户点击"Start Session"按钮时，客户端调用startBBSSession函数创建Browserbase会话
2. 会话嵌入：获取会话调试URL后，将其嵌入到iframe中显示
3. 自动化执行：同时调用runStagehand函数，在服务器端执行浏览器自动化脚本
4. 结果返回：自动化脚本执行完成后，结果可以通过各种方式返回给客户端

进阶用法

自定义自动化脚本

在main函数中，你可以编写任何Playwright支持的浏览器操作：

async function main(stagehand: Stagehand) {
  const page = stagehand.page;
  
  // 登录操作示例
  await page.goto("https://example.com/login");
  await page.fill("#username", "your_username");
  await page.fill("#password", "your_password");
  await page.click("#login-button");
  
  // 提取数据示例
  const userData = await page.extract({
    instruction: "Extract user profile information",
    schema: z.object({
      name: z.string(),
      email: z.string().email(),
      joinDate: z.string(),
    }),
  });
  
  return userData;
}

错误处理

建议为自动化脚本添加错误处理：

export async function runStagehand(sessionId?: string) {
  try {
    const stagehand = new Stagehand({ /* 配置 */ });
    await stagehand.init();
    const result = await main(stagehand);
    await stagehand.close();
    return result;
  } catch (error) {
    console.error("Stagehand执行失败:", error);
    throw error;
  }
}

性能优化建议

1. 会话复用：对于频繁的操作，考虑复用Browserbase会话
2. 并行处理：对于独立任务，可以使用多个会话并行处理
3. 资源清理：确保在操作完成后正确关闭会话
4. 日志记录：合理配置日志级别，便于调试和监控

常见问题解答

Q: Stagehand与常规Playwright有何不同？

A: Stagehand在Playwright基础上提供了更高层次的抽象，简化了常见浏览器自动化任务的实现，特别适合与Next.js等现代框架集成。

Q: 是否必须使用Browserbase？

A: 虽然技术上可以在本地运行Stagehand，但使用Browserbase可以大大简化浏览器实例的管理和维护工作，特别是在生产环境中。

Q: 如何处理页面加载超时？

A: 可以在Stagehand配置中设置超时参数，或在Playwright页面操作中使用timeout选项。

通过本文的介绍，你应该已经掌握了在Next.js项目中集成Stagehand实现浏览器自动化的基本方法。这种组合为构建需要浏览器交互的复杂Web应用提供了强大的技术支持。

【免费下载链接】stagehand An AI web browsing framework focused on simplicity and extensibility. 项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand