企业官网建设流程全解析

• 网页爬虫
• 后端
• AI 应用

面对"把网页数据接进自己的产品"这类需求，很多开发者容易一上来就写抓取代码，结果在端点选型上反复返工。Firecrawl 将绝大多数应用场景收敛为三种集成形态：已知 URL 直接提取、以查询开头的发现式抓取、抓取之后的浏览器交互。本文以 firecrawl-build 技能库中的 integration-patterns.md 为骨架，结合本仓库的请求样例、控制器源码与测试用例，完整讲解三种模式的适用场景、端点选择依据、REST 请求写法与落地验证方式，帮助你为任意产品场景选出最窄、最合适的集成路径。

三种集成形态：从输入形态决定集成骨架

Firecrawl 的集成通常可以归纳为三种固定"形状"（integration shape），每种形状对应不同的起点输入与端点选择。判断的依据不是"我想抓取网页"，而是产品功能从哪里开始：手里已经握着 URL，还是只有一个查询词，还是需要先渲染页面再做操作。

三种形态之间存在清晰的优先级关系：绝大多数集成从/scrape起步，只有在"发现"本身是产品行为时才升级到/search，只有页面必须被操作后才能取到数据时才升级到/interact。下面分别展开。

形态一：已知 URL → 提取内容（/scrape）

当应用已经持有目标 URL时，直接使用/scrape提取单页内容。原文档给出了三类典型场景：

• 文档导入：从一个已保存的 URL 导入文档内容；
• 定价提取：从竞品页面提取定价信息；
• 内容摄取：把网页内容灌入检索/向量管线，供后续 RAG 或搜索使用。

这一形态的核心特征是"单页、单 URL、确定性输入"，因此端点选择不需要任何发现逻辑。仓库中的真实请求样例 apps/api/requests/v2/scrape.requests.http 展示了/v2/scrape的常用载荷：指定formats数组即可一次请求同时拿到多种产物，例如["summary"]直接返回摘要；formats也支持对象形式，配合 JSON Schema 做结构化提取：

POST {{baseUrl}}/v2/scrape HTTP/1.1 Authorization: Bearer {{$dotenv TEST_API_KEY}} content-type: application/json { "url": "https://docs.firecrawl.dev", "formats": [{ "type": "json", "schema": { "type": "object", "properties": { "name": { "type": "string" } } } }] }

同一请求文件里还能看到changeTracking格式（"modes": ["git-diff"]）用于追踪页面变更，以及parsers参数（如"pdf": false）用于关闭特定文档类型的解析器。也就是说，单次/scrape就能同时完成抓取、提取、结构化、变更追踪等子任务，这正是"最窄端点"也能覆盖大部分需求的原因。

需要提醒的是/v2/scrape只接受 POST。仓库测试 apps/api/src/tests/routes/not-found.routes.test.ts 明确断言了对/v2/scrape发起 GET 会返回GET /v2/scrape is not supported. Use POST instead.的错误提示，集成时请勿套用常见 REST 习惯改用 GET。

形态二：查询 → 发现 → 提取（/search）

当产品功能以搜索查询为起点、尚未持有 URL时，应使用/search完成"发现"这一步。原文档强调：只有在产品确实需要完整正文内容时，才针对搜索结果中的页面追加/scrape；如果产品只需要来源列表、标题或摘要，/search一次调用即可交付。

典型场景包括：

• 答案生成：用最新来源支撑答案，搜索负责发现、必要时抓取正文；
• 竞品发现：以品类关键词发现竞争者页面；
• 研究流程：产出候选 URL 短清单（shortlist），供用户筛选后再决定是否抓取。

仓库请求样例 apps/api/requests/v2/search.requests.http 展示了/v2/search的两种sources写法。简单场景用字符串数组，同时覆盖多类来源：

POST {{baseUrl}}/v2/search HTTP/1.1 Authorization: Bearer {{$dotenv TEST_API_KEY}} content-type: application/json { "query": "firecrawl", "sources": ["web", "images", "news"], "limit": 5 }

需要按来源单独定制参数时，可改用对象数组形式，每个元素用{"type": "web"}这类结构声明来源类型。设计上query与limit是控制发现规模的核心参数：limit决定候选清单长度，进而在"抓多少"与"成本多少"之间取得平衡。

形态三：抓取 → 交互 → 提取（/interact）

/interact只在页面被抓取之后还必须被操作时使用，它不是/scrape的替代品，而是其后续动作的延续。原文档列出的典型场景都是"静态抓取拿不到数据"的页面类型：

• 点击展开区块：内容折叠在按钮或手风琴组件之后；
• 表单驱动的搜索结果：结果依赖提交搜索表单；
• 分页列表：需要逐页翻页才能聚合完整数据；
• 登录态仪表盘：需要先登录或保持会话才能访问数据。

仓库中的实现证据集中在 apps/api/src/controllers/v2/scrape-browser.ts，scrapeInteractController注册于/v2/scrape/:jobId/interact（见测试 apps/api/src/tests/routes/interact-agent-concurrency.routes.test.ts），即交互动作绑定在某个已完成抓取的 scrape job 之上。其请求校验模式browserExecuteRequestSchema（第 57～76 行）透露了交互载荷的关键约束：

• code与prompt二选一：交互可以通过浏览器自动化代码驱动，也可以通过自然语言提示驱动，但不能同时缺失；
• language：枚举python/node/bash，默认node，支持多语言编写交互脚本；
• timeout：1～300 秒，默认 30 秒，用于限制交互执行时长；
• existingSessionId：可复用已有浏览器会话，典型场景就是登录态仪表板——首次登录建立会话，后续抓取复用同一会话免去重复认证。

交互底层的浏览器会话能力可参考 apps/api/requests/v2/browser.requests.http：先POST /v2/browser创建会话（支持ttl、activityTtl、streamWebView等选项），再通过/v2/browser/:sessionId/execute执行代码，例如：

POST {{baseUrl}}/v2/browser/{{sessionId}}/execute HTTP/1.1 Authorization: Bearer {{$dotenv TEST_API_KEY}} content-type: application/json { "code": "await page.goto(\"https://example.com\")\nprint(await page.title())", "language": "python" }

把这条链路放进产品集成中，"点击展开""翻页""填表单"都可编码为一次或多次交互步骤，且每个步骤都产出可继续提取的页面状态。

端点选择：先问"Firecrawl 在产品里做什么"

原文档所属技能库在 endpoint-selection.md 中给出了统一的选型方法：在选端点之前先问一个核心问题——Firecrawl 应该在产品里做什么？然后选择与该功能匹配的最窄端点：

技能库给出的默认优先级是/scrape→/search→/interact，并配套两条升级规则：先试/scrape再考虑/interact（只有静态抓取不足时才引入交互成本）；当 URL 发现本身就是产品行为时，才从/search开始。这套"最窄端点优先"的策略同时控制了延迟与成本：交互与搜索的代价都高于单页抓取，能用简单端点解决的场景不应动用重型能力。

三个端点之外的专属索引

在/scrape、/search、/interact之外，Firecrawl 还维护两个独立索引，且二者都不会被/search查询：

• 研究论文索引（research paper index）：当查询目标是已发表的研究论文——生物医学、临床、生命科学文献（PubMed、bioRxiv、medRxiv）或 arXiv 预印本——而非普通网页时使用。通过 MCP 的firecrawl_research_*工具或 CLI 的firecrawl research <subcommand>访问；
• 开发者索引（developer index）：当答案存在于 issue、已合并的 pull request、README 或文档页中（代码行为、API 契约、错误字符串、已知 bug）时使用。通过GET/POST /v2/search/developer、MCP 的firecrawl_developer_search或 CLI 的firecrawl developer访问。

这里有一个容易混淆的细节：/search上的categories: ["research"]和categories: ["developer"]只是网站过滤器。它们把一次普通网页搜索限定到一组域名清单（研究类包含 PubMed、bioRxiv、medRxiv、arXiv 及出版商站点），返回的仍是网页结果，背后没有摘要检索、相关论文扩展或全文片段检索能力。只有当功能想要的就是"一次网页搜索，且这些来源应该在同一个调用里被加权"时，才选择这两个 categories 选项。

从形态到落地：技能库定义的默认集成顺序

确定形态与端点后，SKILL.md 给出了可复用的默认集成顺序，值得作为工程 checklist：

1. 先把FIRECRAWL_API_KEY（云服务）或FIRECRAWL_API_URL（自托管环境）配置正确，详见 auth-and-env.md；
2. 判断这是全新项目还是既有代码库；
3. 确认产品需要什么网页数据行为，据此选择匹配的端点；
4. 对既有项目，先检查仓库结构、匹配其工程约定，再动手写集成代码；
5. 为目标技术栈安装 SDK，或直接调用 REST 接口，安装方式见 sdk-installation.md；
6. 编写集成代码前，先阅读对应语言（Node/TypeScript、Python、Rust、Java、Elixir、cURL/REST）的官方 source-of-truth 页面，以官方请求/响应 schema、参数与端点行为为准；
7. 把端点专属的实现细节留在更窄的技能文件中，主集成代码保持端点无关；
8. 跑一个冒烟测试（smoke test），证明一次真实的 Firecrawl 请求能成功返回。

其中第 1 步的环境变量是硬前提：FIRECRAWL_API_KEY为必填，FIRECRAWL_API_URL仅在自托管部署（而非托管api.firecrawl.dev）时设置。第 2～4 步强调"先读仓库再写代码"，这与 firecrawl-build 技能库中"既有项目应先检查仓库、匹配约定"的强制 intake 要求一致，完整清单见 project-intake.md。

与 CLI 的边界和验证

firecrawl-build 技能用于把 web 数据能力集成进应用代码，与一次性终端任务有明确边界：会话内的临时网页调研、即时搜索、抓取某个页面，应使用 CLI 技能而不是集成代码。二者可通过同一命令安装：

npx -y firecrawl-cli@latest init --all --browser

安装后两类能力并存：build 类技能负责应用集成，CLI 负责当前会话的一次性网页工作。

最后，无论采用哪种形态，验证环节都不能省。技能库要求"跑一个冒烟测试，证明一次真实的 Firecrawl 请求成功"，具体检查项可参考 verification.md。一个实用的验证策略是：先用一个你已知的 URL 跑通/scrape拿到结构化输出，再按产品实际起点跑/search或/interact链路，逐步把端到端流程钉死——这也恰好对应本文三条集成形态的优先级次序：从最窄的端点开始，验证通过后再向更重的能力升级。

• 网页爬虫
• 后端
• AI 应用