> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-0siop6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 在本地运行 Firecrawl 进行开发

> 设置 Firecrawl API 开发环境，验证本地抓取，并在贡献代码前运行仓库自带的测试工具。

修改 API、worker 或测试时，请在本地运行 Firecrawl。此流程会安装开发依赖项，并通过 API 测试框架启动仓库自带的服务。

<Warning>
  这是面向贡献者的开发环境，不是部署指南。如果你想在自己控制的基础设施上运行 Firecrawl，
  而不修改产品，请参阅 [自托管 Firecrawl](/zh/contributing/self-host)。
</Warning>

<div id="choose-local-development-or-self-hosting">
  ## 选择本地开发还是自行托管
</div>

* 需要基于当前源代码版本快速进行编写、测试和调试时，请**在本地开发**。
* 希望在自己的基础设施上使用稳定的 Docker Compose 基线时，请**自行托管固定版本**。
* 希望以最快的托管方式使用 Firecrawl，而无需维护上述任一环境时，请**使用 Firecrawl Cloud**。

请将这些环境分开使用。`apps/api/.env` 中的 API 开发配置文件与根目录的 Compose `.env` 分别用于不同的进程，不能互换。

<div id="start-the-firecrawl-development-environment">
  ## 启动 Firecrawl 开发环境
</div>

<div id="install-the-prerequisites">
  ### 安装前置依赖
</div>

安装：

* [Git](https://git-scm.com/downloads)
* Node.js 22
* pnpm `11.4.0`
* [Redis](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/)
* Docker 或 Podman，用于运行由 API 测试框架管理的 PostgreSQL 和 RabbitMQ 容器
* [Go](https://go.dev/dl/) 1.23 或更高版本，API 测试框架会在每次启动时重新构建
* [Rust](https://www.rust-lang.org/tools/install)，执行 `pnpm install` 时会为 `@mendable/firecrawl-rs` 原生包构建 Rust 组件

启用 API 所使用的包管理器版本：

```bash theme={null}
corepack enable
corepack prepare pnpm@11.4.0 --activate
```

<div id="clone-firecrawl-and-install-dependencies">
  ### 克隆 Firecrawl 并安装依赖
</div>

```bash theme={null}
git clone https://github.com/firecrawl/firecrawl.git
cd firecrawl/apps/api
pnpm install
```

使用最精简的无需认证的开发配置创建 `apps/api/.env`：

```bash theme={null}
cat > .env <<'EOF'
PORT=3002
HOST=0.0.0.0
REDIS_URL=redis://localhost:6379
REDIS_RATE_LIMIT_URL=redis://localhost:6379
USE_DB_AUTHENTICATION=false
PLAYWRIGHT_MICROSERVICE_URL=
EOF
```

如需让测试框架创建本地 PostgreSQL 和 RabbitMQ 容器，请不要设置 `NUQ_DATABASE_URL` 和 `NUQ_RABBITMQ_URL`。仅在您有意自行管理这些依赖项时才设置它们。

<div id="start-redis-and-firecrawl">
  ### 启动 Redis 和 Firecrawl
</div>

在一个终端中启动 Redis：

```bash theme={null}
redis-server
```

然后在另一个终端中，从 `apps/api` 目录启动 Firecrawl：

```bash theme={null}
pnpm start
```

启动命令会构建 API、启动 API 和 worker 进程，并管理本地队列容器。开发期间请保持此终端窗口处于打开状态。

<div id="verify-one-local-scrape">
  ### 验证本地抓取
</div>

检查 API 进程是否正常响应：

```bash theme={null}
curl \
  --fail \
  --silent \
  --show-error \
  http://localhost:3002/v0/health/readiness
```

预期响应：

```json theme={null}
{"status":"ok"}
```

然后测试抓取路径：

```bash theme={null}
curl \
  --fail-with-body \
  --silent \
  --show-error \
  --max-time 75 \
  -X POST \
  http://localhost:3002/v2/scrape \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "formats": ["markdown"],
    "timeout": 60000
  }'
```

成功的响应包含 `success: true`、`data.markdown` 中的 Markdown 内容，以及 `data.metadata.statusCode` 中的 HTTP 状态码。

<div id="change-and-test-firecrawl">
  ## 修改并测试 Firecrawl
</div>

每次修改都应聚焦明确，覆盖成功路径及相关失败场景，并运行由源码维护、且足以验证该行为的最小范围测试命令。

在 `apps/api` 目录下，运行 API snippet 测试套件及其依赖项：

```bash theme={null}
pnpm harness pnpm test:snips
```

测试框架会为测试命令启动 API、worker、PostgreSQL 和 RabbitMQ，随后清理其启动的进程。如果无需运行完整的 snippet 测试套件，请使用更有针对性的 Vitest 路径。

贡献前，请先阅读仓库中的 [`CONTRIBUTING.md`](https://github.com/firecrawl/firecrawl/blob/main/CONTRIBUTING.md)，再创建 pull request。

<div id="troubleshoot-the-development-environment">
  ## 排查开发环境问题
</div>

<div id="redis-does-not-connect">
  ### Redis 无法连接
</div>

确认 Redis 正在监听 `localhost:6379`，并确保 `apps/api/.env` 中的两个 Redis URL 都使用该地址。

<div id="the-harness-cannot-start-postgresql-or-rabbitmq">
  ### 测试框架无法启动 PostgreSQL 或 RabbitMQ
</div>

启动 Docker 或 Podman，然后重新运行 `pnpm start`。如果这些服务由你自行管理，请显式设置其连接 URL，而不要依赖测试框架管理的容器。

<div id="port-3002-is-already-in-use">
  ### 端口 3002 已被占用
</div>

请停止其他进程，或在 `apps/api/.env` 中更改 `PORT`，然后在验证请求中使用相同的端口。

<div id="basic-fetch-works-but-browser-rendering-does-not">
  ### 基本抓取可用，但浏览器渲染不可用
</div>

将 `PLAYWRIGHT_MICROSERVICE_URL` 留空会禁用独立的 Playwright 服务。仅当测试的变更需要该服务时，才启动并配置它。

<div id="where-to-go-next">
  ## 下一步
</div>

* **需要部署而非开发？** 请参阅[自托管 Firecrawl](/zh/contributing/self-host)。
* **还在选择方案？** 比较[开源版与 Firecrawl Cloud](/zh/contributing/open-source-or-cloud)。
* **准备好贡献了吗？** 请查看由源代码仓库维护的[贡献指南](https://github.com/firecrawl/firecrawl/blob/main/CONTRIBUTING.md)。