> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# 使用 Firecrawl 抓取网页

Firecrawl 是一个网页数据 API，可将网站转换成干净的 Markdown 或结构化 JSON。在本指南中，你会把 Firecrawl 接入 Mastra Tool，让 Agent 和 Workflow 可以按需搜索和抓取实时网页数据。

## 前提条件

- 已安装 Node.js `v22.13.0` 或更高版本
- Firecrawl API 密钥（可前往 <https://firecrawl.dev> 获取）
- 受支持的 [Model Provider](https://mastra.zisheng.pro/models) 提供的 API 密钥
- 现有的 Mastra 项目（按照[安装指南](https://mastra.zisheng.pro/guides/getting-started/quickstart)设置新项目）

## 安装

安装 Firecrawl SDK：

**npm**:

```bash
npm install firecrawl
```

**pnpm**:

```bash
pnpm add firecrawl
```

**Yarn**:

```bash
yarn add firecrawl
```

**Bun**:

```bash
bun add firecrawl
```

## 配置环境变量

在项目根目录创建 `.env` 文件：

```bash
FIRECRAWL_API_KEY=fc-your-api-key
# Optional: FIRECRAWL_API_URL=http://localhost:3002
```

## 构建 Firecrawl Tool

创建一个 Tool 文件，向 Mastra 提供 Firecrawl 的搜索和抓取能力。

1. 创建 `src/mastra/tools/firecrawl.ts` 并设置 Firecrawl：

   ```ts
   import { Firecrawl } from 'firecrawl'
   import { createTool } from '@mastra/core/tools'
   import { z } from 'zod'

   const firecrawl = new Firecrawl({ apiKey: process.env.FIRECRAWL_API_KEY! })

   export const firecrawlSearch = createTool({
     id: 'firecrawl-search',
     description: 'Search the web and return top results.',
     inputSchema: z.object({ query: z.string().min(1) }),
     outputSchema: z.object({
       results: z.array(
         z.object({
           title: z.string().nullable(),
           url: z.string(),
         }),
       ),
     }),
     execute: async ({ query }) => {
       const results = await firecrawl.search(query, { limit: 3 })
       return {
         results: (results.web ?? []).map(item => ({
           title: item.title ?? null,
           url: item.url,
         })),
       }
     },
   })

   export const firecrawlScrape = createTool({
     id: 'firecrawl-scrape',
     description: 'Scrape a URL and return markdown content.',
     inputSchema: z.object({ url: z.string().url() }),
     outputSchema: z.object({ markdown: z.string() }),
     execute: async ({ url }) => {
       const result = await firecrawl.scrape(url, {
         formats: ['markdown'],
         onlyMainContent: true,
       })
       return { markdown: result.markdown ?? '' }
     },
   })
   ```

2. 在 `src/mastra/agents/web-agent.ts` 创建新的 Agent：

   ```ts
   import { Agent } from '@mastra/core/agent'
   import { firecrawlSearch, firecrawlScrape } from '../tools/firecrawl'

   export const webAgent = new Agent({
     id: 'web-agent',
     name: 'Web Agent',
     instructions: 'Use Firecrawl tools to search and scrape web pages, then summarize the results.',
     model: 'openai/gpt-5.6-sol',
     tools: { firecrawlSearch, firecrawlScrape },
   })
   ```

3. 在 `src/mastra/index.ts` 中，将新建的 Agent 注册到 Mastra 实例：

   ```ts
   import { Mastra } from '@mastra/core'
   import { webAgent } from './agents/web-agent'

   export const mastra = new Mastra({
     agents: { webAgent },
   })
   ```

## 在 Studio 中测试

运行开发服务器并打开 [Studio](https://mastra.zisheng.pro/docs/studio/overview)：

```bash
mastra dev
```

在 Studio 中打开 **Web Agent**，然后尝试：

- “查找最新的 Mastra changelog，并总结最后一个版本。”
- “搜索 Firecrawl 定价并提取各个方案层级。”

## 自托管 Firecrawl

如果你在本地运行 Firecrawl，请设置 `FIRECRAWL_API_URL`，或在 client 中传入 `apiUrl`：

```ts
const firecrawl = new Firecrawl({
  apiKey: process.env.FIRECRAWL_API_KEY!,
  apiUrl: process.env.FIRECRAWL_API_URL,
})
```

## 相关资源

- [Firecrawl 文档](https://docs.firecrawl.dev)