> ## Documentation Index
> Fetch the complete documentation index at: https://stagehand.readme-i18n.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 安装 Stagehand

将 Stagehand 添加到新项目或现有项目中。

<Tip>
  对于 TypeScript/Node.js：我们强烈建议使用 Node.js 运行时环境来运行 Stagehand 脚本，而不是 Deno 或 Bun 等较新的替代方案。

  **Bun 不支持 Stagehand**，因为它不支持 [Playwright](https://github.com/search?q=repo:oven-sh/bun+playwright\&type=issues)。

  对于 Python：需要 Python 3.9 或更高版本，并建议使用 [uv](https://docs.astral.sh/uv/) 来管理虚拟环境。
</Tip>

<Tabs>
  <Tab title="TypeScript">
    我们强烈推荐在新项目中使用 `npx create-browser-app` 来集成 Stagehand。请查阅我们的[快速入门指南](https://docs.stagehand.dev/get_started/quickstart)开始使用。

    若您已有现有项目，可通过安装 `@browserbasehq/stagehand` 包来引入 Stagehand。

    <Tabs>
      <Tab title="npm">
        ```bash theme={null}
        npm install @browserbasehq/stagehand
        ```
      </Tab>

      <Tab title="pnpm">
        ```bash theme={null}
        pnpm add @browserbasehq/stagehand
        ```
      </Tab>

      <Tab title="yarn">
        ```bash theme={null}
        yarn add @browserbasehq/stagehand
        ```
      </Tab>
    </Tabs>

    <Note>
      运行 Stagehand 脚本时可能需要安装 Playwright 浏览器，特别是在本地运行环境下。
    </Note>

    ```bash theme={null}
    playwright install
    ```

    随后，您可以通过导入 `Stagehand` 类在项目中使用该工具。

    ```typescript theme={null}
    import { Stagehand } from "@browserbasehq/stagehand";

    async function main() {
    	const stagehand = new Stagehand({
    		// 使用 npx create-browser-app 时，该配置存放于
    		// 单独的 stagehand.config.ts 文件中
    		env: "LOCAL",
    		modelName: "openai/gpt-4.1-mini",
    		modelClientOptions: {
    			apiKey: process.env.OPENAI_API_KEY,
    		},
    	});
    	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(),
    		}),
    	});
    	

    	await stagehand.close();
    }

    main();
    ```
  </Tab>

  <Tab title="Python">
    开始前请确保已安装 Python 3.9+。推荐使用 [uv](https://docs.astral.sh/uv/) 管理虚拟环境。

    <Steps>
      <Step title="推荐：设置虚拟环境">
        ```bash theme={null}
        uv venv
        source .venv/bin/activate
        ```
      </Step>

      <Step title="安装 Stagehand Python 包">
        ```bash theme={null}
        pip install stagehand
        ```

        若使用 **uv** 虚拟环境，可通过以下命令安装：

        ```bash theme={null}
        uv add stagehand
        ```
      </Step>

      <Step title="配置环境变量">
        创建 `.env` 文件或导出环境变量：

        ```bash theme={null}
        export MODEL_API_KEY="your_model_api_key" # OpenAI, Anthropic 等
        # 浏览器环境配置
        # export BROWSERBASE_API_KEY="your_browserbase_api_key"
        # export BROWSERBASE_PROJECT_ID="your_browserbase_project_id"
        ```
      </Step>

      <Step title="创建首个脚本">
        创建 `main.py` 文件：

        ```python theme={null}
        import asyncio
        import os
        from stagehand import Stagehand, StagehandConfig
        from dotenv import load_dotenv

        load_dotenv()

        async def main():
        		config = StagehandConfig(
        				env="LOCAL",
        				model_name="openai/gpt-4.1-mini",
        				model_api_key=os.getenv("MODEL_API_KEY")
        		)
        		
        		stagehand = Stagehand(config)
        		
        		try:
        				await stagehand.init()
        				page = stagehand.page
        				
        				await page.goto("https://docs.stagehand.dev/")
        				await page.act("点击快速入门链接")
        				
        				result = await page.extract("提取页面主标题")
        				
        				print(f"提取结果: {result.extraction}")
        				
        		finally:
        				await stagehand.close()

        if __name__ == "__main__":
        		asyncio.run(main())
        ```
      </Step>

      <Step title="运行脚本">
        ```bash theme={null}
        python main.py
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>