Firecrawl 贡献者环境设置

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

Warning

这是面向贡献者的开发环境，不是部署指南。如果你想在自己控制的基础设施上运行 Firecrawl，而不修改产品，请参阅自托管 Firecrawl。

选择本地开发还是自行托管#

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

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

启动 Firecrawl 开发环境#

安装前置依赖#

安装：

Git
Node.js 22
pnpm 11.4.0
Redis
Docker 或 Podman，用于运行由 API 测试框架管理的 PostgreSQL 和 RabbitMQ 容器
Go 1.23 或更高版本，API 测试框架会在每次启动时重新构建
Rust，执行 pnpm install 时会为 @mendable/firecrawl-rs 原生包构建 Rust 组件

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

corepack enablecorepack prepare pnpm@11.4.0 --activate

克隆 Firecrawl 并安装依赖#

git clone https://github.com/firecrawl/firecrawl.gitcd firecrawl/apps/apipnpm install

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

cat > .env <<'EOF'PORT=3002HOST=0.0.0.0REDIS_URL=redis://localhost:6379REDIS_RATE_LIMIT_URL=redis://localhost:6379USE_DB_AUTHENTICATION=falsePLAYWRIGHT_MICROSERVICE_URL=EOF

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

启动 Redis 和 Firecrawl#

在一个终端中启动 Redis：

redis-server

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

pnpm start

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

验证本地抓取#

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

curl \  --fail \  --silent \  --show-error \  http://localhost:3002/v0/health/readiness

预期响应：

{"status":"ok"}

然后测试抓取路径：

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 状态码。

修改并测试 Firecrawl#

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

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

pnpm harness pnpm test:snips

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

贡献前，请先阅读仓库中的 CONTRIBUTING.md，再创建 pull request。

排查开发环境问题#

Redis 无法连接#

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

测试框架无法启动 PostgreSQL 或 RabbitMQ#

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

端口 3002 已被占用#

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

基本抓取可用，但浏览器渲染不可用#

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

下一步#

需要部署而非开发？ 请参阅自托管 Firecrawl。
还在选择方案？ 比较开源版与 Firecrawl Cloud。
准备好贡献了吗？ 请查看由源代码仓库维护的贡献指南。