在本地运行 Firecrawl 进行开发

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

这是面向贡献者的开发环境，不是部署指南。如果你想在自己控制的基础设施上运行 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 enable
corepack prepare pnpm@11.4.0 --activate

克隆 Firecrawl 并安装依赖

git clone https://github.com/firecrawl/firecrawl.git
cd firecrawl/apps/api
pnpm install

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

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。仅在您有意自行管理这些依赖项时才设置它们。

启动 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。
准备好贡献了吗？ 请查看由源代码仓库维护的贡献指南。

快速上手

核心端点

更多

快速入门

开发者指南

Webhooks

使用场景

其他

参与贡献

在本地运行 Firecrawl 进行开发

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

启动 Firecrawl 开发环境

安装前置依赖

克隆 Firecrawl 并安装依赖

启动 Redis 和 Firecrawl

验证本地抓取

修改并测试 Firecrawl

排查开发环境问题

Redis 无法连接

测试框架无法启动 PostgreSQL 或 RabbitMQ

端口 3002 已被占用

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

下一步

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

​启动 Firecrawl 开发环境

​安装前置依赖

​克隆 Firecrawl 并安装依赖

​启动 Redis 和 Firecrawl

​验证本地抓取

​修改并测试 Firecrawl

​排查开发环境问题

​Redis 无法连接

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

​端口 3002 已被占用

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

​下一步

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

启动 Firecrawl 开发环境

安装前置依赖

克隆 Firecrawl 并安装依赖

启动 Redis 和 Firecrawl

验证本地抓取

修改并测试 Firecrawl

排查开发环境问题

Redis 无法连接

测试框架无法启动 PostgreSQL 或 RabbitMQ

端口 3002 已被占用

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

下一步