企业官网建设流程全解析

Firecrawl 免费自部署：5 步把任意网页变成 LLM 能读的 Markdown

【免费下载链接】firecrawlThe context API to search, scrape, and interact with the web at scale. 🔥项目地址: https://gitcode.com/GitHub_Trending/fi/firecrawl

AI 应用要"看懂"网页，先过内容这一关。原始 HTML 里塞满脚本和广告标签，直接喂给大模型既费 token 又跑偏。Firecrawl 是一个开源的网页抓取 API：你给它一个 URL，它还你干净的 Markdown 或结构化 JSON。它支持单页抓取、全站爬取、站点 URL 测绘，还能在 JS 渲染页面上点击、滚动后再取内容。下文只讲一件事——把它部署到自己机器上，并从第一个成功的请求一直调到批量抓取。

一条请求走完全链路

动手前先弄清它内部怎么分工，后面排错全靠这张图。

你向 API（默认端口 3002）发起 POST 请求，这是输入；API 把任务写入队列（RabbitMQ + PostgreSQL），这是规则调度；worker 拉起 Playwright 无头浏览器加载页面，等待 JS 渲染完成后把 HTML 转成 Markdown 返回，这是输出。

所以堆栈里每个组件都不可少：

注意：自部署版USE_DB_AUTHENTICATION默认是false，调用时不带Authorization 头；AI 增强功能（如 agent）需要配置OPENAI_API_KEY，不配也不影响抓取主线。

10 分钟跑通第一次抓取

前提：机器已装好 Docker，内存建议 8GB 以上（compose 文件给 api 和 playwright 分别限了 8G 和 4G 上限，机器内存不够就改apps/api和apps/playwright-service-ts两处mem_limit）。

1. 📦 克隆代码到本地：git clone https://gitcode.com/GitHub_Trending/fi/firecrawl
2. 进入目录启动全部服务：cd firecrawl && docker compose up -d --build
3. 首次构建要编译 API 镜像，等 5-15 分钟。用docker compose logs -f api盯日志，出现 3002 端口监听字样即就绪。
4. 🎯 发第一个请求，验证抓取是否生效：

curl -X POST http://localhost:3002/v2/scrape \ -H 'Content-Type: application/json' \ -d '{"url":"https://example.com","formats":["markdown"]}'

返回 JSON 里data.markdown字段有干净的正文，恭喜，链路通了。

提示：formats是输出开关，markdown、html、json、screenshot可任意组合。

三种常用抓法，参数照抄即可

同一个/v2/scrape端点能覆盖大部分场景，区别只在参数。下面三套配置可直接复制。

单页深挖：scrape

适合：文档页、商品页、单篇文章入库。

全站采集：crawl

适合：整站文档、帮助中心全量入库。注意 crawl 是异步任务，接口先返回任务 ID，用GET /v2/crawl/{id}轮询到status: completed才拿数据；各语言 SDK 已帮你自动轮询。

先摸底再动手：map

适合：爬取前先拿到完整 URL 清单，再决定抓哪些、批量抓多少。

另外，多个已知 URL 一次性抓完用/v2/batch_scrape，一次传几百个链接比循环单抓省得多。

踩坑清单：症状、原因、处理

抓回来的是空壳或报错

• 症状：markdown为空，或提示页面加载失败
• 可能原因：页面全靠 JS 渲染，默认等待时间不够
• 处理：加"waitFor": 5000；仍不行就在actions里加一次滚动后再取

请求被拒，提示权限问题

• 症状：401/403
• 可能原因：自部署没开数据库认证却带了Authorization头，或反过来开了认证却没配库
• 处理：保持USE_DB_AUTHENTICATION=false就不带头调用；要上认证就同时完成数据库 schema 配置，二者必须一致

请求发不出去

• 症状：连接拒绝或超时
• 可能原因：3002 端口被占用，或 compose 里PORT映射没生效
• 处理：docker compose logs api看启动日志；换端口时.env里设PORT=3003后重启

crawl 任务一直查不到结果

• 症状：轮询始终不是completed
• 可能原因：limit设得太大，或目标站反爬严格
• 处理：先用map确认站点规模，把limit降到 50 以内试跑

注意：默认配置会遵守目标站点的 robots.txt，商用前请自行确认合规边界。

部署完成度自检

五条全过，说明这套 Firecrawl 已经可以接进你的 AI 流水线：

• POST /v2/scrape返回非空 markdown，且无 JS 渲染缺失
• GET /v2/map能在几秒内列出目标站 URL 清单
• 一个小站 crawl 任务能轮询到completed，页数与limit吻合
• 重启 Docker 后（docker compose restart）以上请求依然正常
• 目标站点被 robots.txt 屏蔽的 URL 确实没有被抓取

接下来可以做的事很具体：把formats换成json配合 schema 出结构化字段，或者在.env里配一个模型服务解锁 AI 功能。按需来，别一次全开。

【免费下载链接】firecrawlThe context API to search, scrape, and interact with the web at scale. 🔥项目地址: https://gitcode.com/GitHub_Trending/fi/firecrawl