网页爬虫后端AI 应用【免费下载链接】firecrawlThe web data API to search, scrape, and interact at scale. 项目地址https://gitcode.com/GitHub_Trending/fi/firecrawl点击查看免费下载导读本篇技术指南以仓库根目录的 CONTRIBUTING.md 为主体面向所有希望为 Firecrawl开源 Web 数据 API用于搜索、抓取与规模化交互贡献代码的开发者。读完本文你将掌握如何在本地搭建 Firecrawl API 开发环境并跑通首次抓取、如何借助harness启动整套服务与依赖容器来运行端到端测试、以及如何组织一次聚焦、可评审、带完整测试覆盖的 Pull Request。文中所有命令与实现细节均以当前仓库源码为事实依据可对照源码逐步验证。先选对路线本地开发与自托管是两条不同的路径贡献者的第一个决策不是写代码而是确认自己的目标。CONTRIBUTING.md 给出了一个明确的路线选择表你的目标起点修改 API、Worker 或测试代码按官方公开的本地运行指南搭建开发环境对应仓库内 SELF_HOST.md 之外的一套开发工作流在自己的基础设施上运行 Firecrawl、不改产品代码参考自托管指南与 docker-compose.yaml修改某个 SDK进入 apps/ 下对应的 SDK 目录使用其 package 脚本改进公共文档官方文档仓库firecrawl-docs独立于本仓库维护这条表格背后有一个重要的工程原则CONTRIBUTING.md 用一句话点破本地开发与自托管是两套不同的路径。本地开发使用 API harness 和apps/api/.envDocker Compose 部署使用仓库根目录的配置。不要把两份环境文件互相复制。这一点在 SELF_HOST.md 中有更完整的展开根目录的.env只覆盖docker-compose.yaml引用的变量apps/api/.env.example不是 Compose 的即插即用契约。也就是说同样的服务在开发 harness与Compose 部署两种运行形态下环境变量来源完全不同——混用会导致服务以错误的配置启动。搭建 API 开发环境前置条件按官方公开指南本地开发的推荐环境是Node.js 22与仓库内apps/api/package.json的types/node版本^22.19.1一致可在 package.json 中核对pnpm 11.4.0这是仓库锁定的包管理器版本package.json末尾的packageManager: pnpm11.4.0字段即强制声明Redis需要单独保持运行下文会说明原因PostgreSQL 与 RabbitMQ由 harness 管理的容器自动启动无需手工安装。启动命令源码归属的命令全部集中在 apps/api/package.json 的scripts中。在apps/api目录下执行pnpm install pnpm startpnpm start对应脚本为tsc node dist/src/harness.js --start-built先执行 TypeScript 编译再以已构建产物模式启动 harness。harness 会拉起 Firecrawl 的API、各类 Worker 和本地依赖容器而 Redis 需要按公开指南单独保持运行。harness 到底在做什么从源码看启动细节pnpm start真正调用的入口是 apps/api/src/harness.ts约 1251 行。从源码结构看它承担了一键启动整套开发环境的编排职责依赖安装与构建installDependencies并行执行pnpm install、pnpm build并进入 sharedLibs/go-html-to-md 执行go mod tidy和go build -buildmodec-shared把 Go 编写的 HTML→Markdown 转换器编译成共享库供 API 通过 native 模块调用容器编排setupNuqPostgres、setupNuqRabbitMQ、setupFdb自动检测 Docker 或 Podman依次尝试docker --version/podman --version构建firecrawl-nuq-postgres镜像并启动 PostgreSQL 容器、启动rabbitmq:3-management容器只有当NUQ_BACKENDfdb时才启动 FoundationDB 容器。如果环境变量NUQ_DATABASE_URL/NUQ_RABBITMQ_URL/FDB_CLUSTER_FILE已显式设置harness 会尊重你的选择、跳过容器管理服务进程编排startServices同时启动 API、队列 worker、NUQ_WORKER_COUNT个 NUQ worker、extract worker、nuq-prefetch / nuq-reconciler worker以及仅在启用 DB 认证时index worker就绪探测waitForPort轮询目标端口直至可用默认超时来自HARNESS_STARTUP_TIMEOUT_MS配置优雅清理stopDevelopmentServices 与 gracefulShutdown进程退出时停止所有子进程并停掉、删除由 harness 启动的容器保证环境可重复使用。正因为 harness 拥有完整的启动/清理闭环CONTRIBUTING.md 才放心地要求测试用 harness 跑——它确保了 API、Worker、PostgreSQL、RabbitMQ 在测试命令执行期间全部在线并在结束后清理干净。开发模式可选除pnpm start生产模式运行编译产物外package.json 还提供了pnpm devtsx src/harness.ts --start开发模式。从 harness 源码看--start模式会用tsc-watch监听 TypeScript 编译事件在首次编译成功及每次重编译成功后自动重启整套服务runDevMode实现改代码即热重启。做出一次聚焦的变更CONTRIBUTING.md 给出的变更流程只有 5 步但每一步都指向让 PR 容易评审这一目标Fork 仓库并创建描述性分支分支名应直接描述这次变更的内容修改前先复现当前行为确保你理解现状也能证明问题存在为成功路径和相关失败路径补充或更新测试覆盖做出能满足这些测试的最小改动在开 PR 之前运行最窄范围的有效检查。对 API 变更CONTRIBUTING.md 特别强调当行为跨越路由、Worker、队列或抓取引擎时优先使用端到端 snippet 覆盖。也就是说不要只写一个孤立的单元测试而是要通过真实的 API 请求验证整条调用链。仓库中 apps/api/src/tests/snips/ 下的测试组织v1 / v2 分版本目录覆盖 scrape、crawl、map、search、batch-scrape、webhook、monitor 等数十个场景正是这种以真实请求验证行为思路的体现。用 harness 运行 API 测试跑整套 snippet 套件从apps/api目录执行pnpm harness pnpm test:snips这条命令拆开看是两层pnpm harness调用tsx src/harness.ts把后面的命令原样交给它执行pnpm test:snips实际是vitest run src/__tests__/snips/v1 src/__tests__/snips/v2见 package.json 第 21 行。harness 会先启动 API、Worker、PostgreSQL 与 RabbitMQ再执行该命令最后清理自己启动的进程和容器。从 harness.ts 源码可以看到一个细节当传入的命令以pnpm test:snips或pnpm exec开头时harness 会先waitForPort等待 API 在localhost:PORT上就绪再执行测试命令——这保证了端到端测试不会因服务尚未启动而误报失败。跑单个测试文件需要更窄的测试时把 Vitest 的路径参数直接透传给 harnesspnpm harness pnpm exec vitest run path/to/test.ts例如针对某个具体模块验证pnpm harness pnpm exec vitest run src/__tests__/snips/v2/map.test.ts关于测试运行时长vitest.config.ts 中有明确设定testTimeout与hookTimeout均为 120 秒teardownTimeout为 30 秒并且默认使用forks线程池与isolate: true——因为这套套件会连接真实服务并进行大量模块级 mockvi.resetModulesvi.doMock不适合共享进程。snippet 测试自身则使用 90 秒的scrapeTimeout常量见 snips/lib.ts为慢速抓取留足余量。失败处理原则CONTRIBUTING.md 有一条硬性要求不要绕过失败的检查。由你的变更导致的失败必须修复与你无关的仓库既有失败要在 PR 中明确指出并给出足够让评审者复现的细节环境、配置、复现步骤。这条规则的用意是让 CI 信号对每个 PR 都保持可信。打开 Pull RequestPR 描述需要包含以下内容CONTRIBUTING.md 的原始清单为什么需要这个变更背景与动机行为发生了什么变化改动前后的差异你跑过的确切测试或检查命令原文方便评审复现任何配置、迁移、安全或部署影响例如新增环境变量、数据库迁移、权限变化当截图或请求/响应证据能显著降低验证成本时附上它们例如新路由的请求与返回体、抓取结果对比。同时有一条安全底线凭证、本地环境文件、原始用户数据和生成的密钥一律不要进入 commit 与 PR。仓库是多人协作与自动化的载体任何敏感信息一旦入库就难以彻底清除。这与 SELF_HOST.md 中默认 API 未认证、生产化之前必须补齐认证设计的提醒相互印证——开发环境中的.env、测试密钥都应当留在本地。遇到问题怎么办CONTRIBUTING.md 给出的求助路径是可复现的 bug 与功能讨论走官方 GitHub Issues社区交流进入 Firecrawl 的 Discord 社区。两者都是官方维护的外部渠道提问时建议附上复现步骤、期望行为与实际行为、相关测试输出与运行环境Node/pnpm/Redis 版本、容器运行时等这样维护者可以最快定位问题。如果你在仓库内自行排查两个高价值的自检入口是根目录的 SELF_HOST.md自托管形态的服务清单与生产化注意事项和 apps/api/package.json开发、测试、构建、各类 worker 的权威命令表。所有命令都以当前仓库实际内容为准如果仓库版本更新导致命令变化以你检出的那一次 revision 的源码为准。小结Firecrawl 的贡献流程可以浓缩为三条主线路径要选对开发 harness 与自托管 Compose 是两套配置体系环境文件不可互拷变更要聚焦先复现、再补测试、做最小改动跨模块行为用端到端 snippet 验证测试要走 harnesspnpm harness自动编排 API、Worker、PostgreSQL、RabbitMQ 的启动与清理让单条命令即可获得可信的测试信号。按照这套流程提交的 PR评审者可以快速理解动机、复现验证、评估影响——这正是 CONTRIBUTING.md 开头那句让每个变更聚焦、用测试证明行为、让 PR 易于评审的全部含义。赞分享网页爬虫后端AI 应用【免费下载链接】firecrawlThe web data API to search, scrape, and interact at scale. 项目地址https://gitcode.com/GitHub_Trending/fi/firecrawl点击查看免费下载相关推荐Grommet 贡献指南从 Fork 到 PR 合并的完整开发、测试与质量门禁实践Grommet 贡献指南从 Fork 到 PR 合并的完整开发、测试与质量门禁实践 本文基于 Grommet 仓库中的 CONTRIBUTING.md htt前端UI组件Trigger.dev 贡献指南从本地开发环境搭建到提交高质量 PR 的完整实战Trigger.dev 贡献指南从本地开发环境搭建到提交高质量 PR 的完整实战 Trigger.dev 是一个用于构建和部署持久化 AI Agent 与工作AI Agent后端任务调度开发工具可观测性AI 应用howdoi 贡献指南从搭建开发环境到提交高质量 PR 的完整实践howdoi 贡献指南从搭建开发环境到提交高质量 PR 的完整实践 本指南以仓库文档 docs/contributing_to_howdoi.md https开发工具CLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Firecrawl 贡献指南：本地 API 开发、Harness 测试与高质量 PR 的完整实践
网页爬虫后端AI 应用【免费下载链接】firecrawlThe web data API to search, scrape, and interact at scale. 项目地址https://gitcode.com/GitHub_Trending/fi/firecrawl点击查看免费下载导读本篇技术指南以仓库根目录的 CONTRIBUTING.md 为主体面向所有希望为 Firecrawl开源 Web 数据 API用于搜索、抓取与规模化交互贡献代码的开发者。读完本文你将掌握如何在本地搭建 Firecrawl API 开发环境并跑通首次抓取、如何借助harness启动整套服务与依赖容器来运行端到端测试、以及如何组织一次聚焦、可评审、带完整测试覆盖的 Pull Request。文中所有命令与实现细节均以当前仓库源码为事实依据可对照源码逐步验证。先选对路线本地开发与自托管是两条不同的路径贡献者的第一个决策不是写代码而是确认自己的目标。CONTRIBUTING.md 给出了一个明确的路线选择表你的目标起点修改 API、Worker 或测试代码按官方公开的本地运行指南搭建开发环境对应仓库内 SELF_HOST.md 之外的一套开发工作流在自己的基础设施上运行 Firecrawl、不改产品代码参考自托管指南与 docker-compose.yaml修改某个 SDK进入 apps/ 下对应的 SDK 目录使用其 package 脚本改进公共文档官方文档仓库firecrawl-docs独立于本仓库维护这条表格背后有一个重要的工程原则CONTRIBUTING.md 用一句话点破本地开发与自托管是两套不同的路径。本地开发使用 API harness 和apps/api/.envDocker Compose 部署使用仓库根目录的配置。不要把两份环境文件互相复制。这一点在 SELF_HOST.md 中有更完整的展开根目录的.env只覆盖docker-compose.yaml引用的变量apps/api/.env.example不是 Compose 的即插即用契约。也就是说同样的服务在开发 harness与Compose 部署两种运行形态下环境变量来源完全不同——混用会导致服务以错误的配置启动。搭建 API 开发环境前置条件按官方公开指南本地开发的推荐环境是Node.js 22与仓库内apps/api/package.json的types/node版本^22.19.1一致可在 package.json 中核对pnpm 11.4.0这是仓库锁定的包管理器版本package.json末尾的packageManager: pnpm11.4.0字段即强制声明Redis需要单独保持运行下文会说明原因PostgreSQL 与 RabbitMQ由 harness 管理的容器自动启动无需手工安装。启动命令源码归属的命令全部集中在 apps/api/package.json 的scripts中。在apps/api目录下执行pnpm install pnpm startpnpm start对应脚本为tsc node dist/src/harness.js --start-built先执行 TypeScript 编译再以已构建产物模式启动 harness。harness 会拉起 Firecrawl 的API、各类 Worker 和本地依赖容器而 Redis 需要按公开指南单独保持运行。harness 到底在做什么从源码看启动细节pnpm start真正调用的入口是 apps/api/src/harness.ts约 1251 行。从源码结构看它承担了一键启动整套开发环境的编排职责依赖安装与构建installDependencies并行执行pnpm install、pnpm build并进入 sharedLibs/go-html-to-md 执行go mod tidy和go build -buildmodec-shared把 Go 编写的 HTML→Markdown 转换器编译成共享库供 API 通过 native 模块调用容器编排setupNuqPostgres、setupNuqRabbitMQ、setupFdb自动检测 Docker 或 Podman依次尝试docker --version/podman --version构建firecrawl-nuq-postgres镜像并启动 PostgreSQL 容器、启动rabbitmq:3-management容器只有当NUQ_BACKENDfdb时才启动 FoundationDB 容器。如果环境变量NUQ_DATABASE_URL/NUQ_RABBITMQ_URL/FDB_CLUSTER_FILE已显式设置harness 会尊重你的选择、跳过容器管理服务进程编排startServices同时启动 API、队列 worker、NUQ_WORKER_COUNT个 NUQ worker、extract worker、nuq-prefetch / nuq-reconciler worker以及仅在启用 DB 认证时index worker就绪探测waitForPort轮询目标端口直至可用默认超时来自HARNESS_STARTUP_TIMEOUT_MS配置优雅清理stopDevelopmentServices 与 gracefulShutdown进程退出时停止所有子进程并停掉、删除由 harness 启动的容器保证环境可重复使用。正因为 harness 拥有完整的启动/清理闭环CONTRIBUTING.md 才放心地要求测试用 harness 跑——它确保了 API、Worker、PostgreSQL、RabbitMQ 在测试命令执行期间全部在线并在结束后清理干净。开发模式可选除pnpm start生产模式运行编译产物外package.json 还提供了pnpm devtsx src/harness.ts --start开发模式。从 harness 源码看--start模式会用tsc-watch监听 TypeScript 编译事件在首次编译成功及每次重编译成功后自动重启整套服务runDevMode实现改代码即热重启。做出一次聚焦的变更CONTRIBUTING.md 给出的变更流程只有 5 步但每一步都指向让 PR 容易评审这一目标Fork 仓库并创建描述性分支分支名应直接描述这次变更的内容修改前先复现当前行为确保你理解现状也能证明问题存在为成功路径和相关失败路径补充或更新测试覆盖做出能满足这些测试的最小改动在开 PR 之前运行最窄范围的有效检查。对 API 变更CONTRIBUTING.md 特别强调当行为跨越路由、Worker、队列或抓取引擎时优先使用端到端 snippet 覆盖。也就是说不要只写一个孤立的单元测试而是要通过真实的 API 请求验证整条调用链。仓库中 apps/api/src/tests/snips/ 下的测试组织v1 / v2 分版本目录覆盖 scrape、crawl、map、search、batch-scrape、webhook、monitor 等数十个场景正是这种以真实请求验证行为思路的体现。用 harness 运行 API 测试跑整套 snippet 套件从apps/api目录执行pnpm harness pnpm test:snips这条命令拆开看是两层pnpm harness调用tsx src/harness.ts把后面的命令原样交给它执行pnpm test:snips实际是vitest run src/__tests__/snips/v1 src/__tests__/snips/v2见 package.json 第 21 行。harness 会先启动 API、Worker、PostgreSQL 与 RabbitMQ再执行该命令最后清理自己启动的进程和容器。从 harness.ts 源码可以看到一个细节当传入的命令以pnpm test:snips或pnpm exec开头时harness 会先waitForPort等待 API 在localhost:PORT上就绪再执行测试命令——这保证了端到端测试不会因服务尚未启动而误报失败。跑单个测试文件需要更窄的测试时把 Vitest 的路径参数直接透传给 harnesspnpm harness pnpm exec vitest run path/to/test.ts例如针对某个具体模块验证pnpm harness pnpm exec vitest run src/__tests__/snips/v2/map.test.ts关于测试运行时长vitest.config.ts 中有明确设定testTimeout与hookTimeout均为 120 秒teardownTimeout为 30 秒并且默认使用forks线程池与isolate: true——因为这套套件会连接真实服务并进行大量模块级 mockvi.resetModulesvi.doMock不适合共享进程。snippet 测试自身则使用 90 秒的scrapeTimeout常量见 snips/lib.ts为慢速抓取留足余量。失败处理原则CONTRIBUTING.md 有一条硬性要求不要绕过失败的检查。由你的变更导致的失败必须修复与你无关的仓库既有失败要在 PR 中明确指出并给出足够让评审者复现的细节环境、配置、复现步骤。这条规则的用意是让 CI 信号对每个 PR 都保持可信。打开 Pull RequestPR 描述需要包含以下内容CONTRIBUTING.md 的原始清单为什么需要这个变更背景与动机行为发生了什么变化改动前后的差异你跑过的确切测试或检查命令原文方便评审复现任何配置、迁移、安全或部署影响例如新增环境变量、数据库迁移、权限变化当截图或请求/响应证据能显著降低验证成本时附上它们例如新路由的请求与返回体、抓取结果对比。同时有一条安全底线凭证、本地环境文件、原始用户数据和生成的密钥一律不要进入 commit 与 PR。仓库是多人协作与自动化的载体任何敏感信息一旦入库就难以彻底清除。这与 SELF_HOST.md 中默认 API 未认证、生产化之前必须补齐认证设计的提醒相互印证——开发环境中的.env、测试密钥都应当留在本地。遇到问题怎么办CONTRIBUTING.md 给出的求助路径是可复现的 bug 与功能讨论走官方 GitHub Issues社区交流进入 Firecrawl 的 Discord 社区。两者都是官方维护的外部渠道提问时建议附上复现步骤、期望行为与实际行为、相关测试输出与运行环境Node/pnpm/Redis 版本、容器运行时等这样维护者可以最快定位问题。如果你在仓库内自行排查两个高价值的自检入口是根目录的 SELF_HOST.md自托管形态的服务清单与生产化注意事项和 apps/api/package.json开发、测试、构建、各类 worker 的权威命令表。所有命令都以当前仓库实际内容为准如果仓库版本更新导致命令变化以你检出的那一次 revision 的源码为准。小结Firecrawl 的贡献流程可以浓缩为三条主线路径要选对开发 harness 与自托管 Compose 是两套配置体系环境文件不可互拷变更要聚焦先复现、再补测试、做最小改动跨模块行为用端到端 snippet 验证测试要走 harnesspnpm harness自动编排 API、Worker、PostgreSQL、RabbitMQ 的启动与清理让单条命令即可获得可信的测试信号。按照这套流程提交的 PR评审者可以快速理解动机、复现验证、评估影响——这正是 CONTRIBUTING.md 开头那句让每个变更聚焦、用测试证明行为、让 PR 易于评审的全部含义。赞分享网页爬虫后端AI 应用【免费下载链接】firecrawlThe web data API to search, scrape, and interact at scale. 项目地址https://gitcode.com/GitHub_Trending/fi/firecrawl点击查看免费下载相关推荐Grommet 贡献指南从 Fork 到 PR 合并的完整开发、测试与质量门禁实践Grommet 贡献指南从 Fork 到 PR 合并的完整开发、测试与质量门禁实践 本文基于 Grommet 仓库中的 CONTRIBUTING.md htt前端UI组件Trigger.dev 贡献指南从本地开发环境搭建到提交高质量 PR 的完整实战Trigger.dev 贡献指南从本地开发环境搭建到提交高质量 PR 的完整实战 Trigger.dev 是一个用于构建和部署持久化 AI Agent 与工作AI Agent后端任务调度开发工具可观测性AI 应用howdoi 贡献指南从搭建开发环境到提交高质量 PR 的完整实践howdoi 贡献指南从搭建开发环境到提交高质量 PR 的完整实践 本指南以仓库文档 docs/contributing_to_howdoi.md https开发工具CLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考