crawlberg-crawling-a-site

用途

当单个 URL 不够用时，使用 crawlberg crawl。它适用于用户想要抓取文档站、博客、营销页面或整个域名的场景，通过跟随链接捕获每个可达页面并输出为 Markdown。

主要能力

• 从种子 URL 出发，按指定深度跟随链接抓取页面。
• 支持设置页面数量硬上限、并发请求数、同源请求间隔。
• 可选择停留在种子域名内、遵守 robots.txt。
• 支持 HTTP、HTTPS、SOCKS5 代理，可覆盖 User-Agent 和超时。
• 支持浏览器模式（auto、always、never）及外部 CDP 端点。
• 输出格式支持 json 或 markdown。
• 接受多个种子 URL，引擎通过 batch_crawl 扇出并聚合结果。

使用方式

快速示例：

crawlberg crawl https://example.com \
  --depth 3 \
  --max-pages 200 \
  --concurrent 8 \
  --rate-limit 250 \
  --stay-on-domain \
  --respect-robots-txt \
  --format markdown

通常应覆盖的默认值：

• --depth 2 较浅，建议显式设置。
• --max-pages 默认无上限，对未知站点应设置上限。
• --concurrent 10 对小型主机过于激进，第三方站点建议降至 4-8。

参数说明：

参数	默认值	用途
--depth, -d	2	从种子 URL 出发的最大跳数。
--max-pages, -n	—	抓取页面的硬上限。对任何未知站点都应设置。
--concurrent, -c	10	并行进行中的请求数。
--rate-limit	200	对同一源的请求间隔毫秒数。
--stay-on-domain	off	跳过离开种子域名的链接。
--respect-robots-txt	off	遵守 robots.txt。对任何第三方主机都应传入。
--proxy	—	HTTP、HTTPS 或 SOCKS5 代理 URL。
--user-agent	—	覆盖请求 UA。应如实标识。
--timeout	30000	每请求超时毫秒数。
--browser-mode	auto	auto、always、never。
--browser-endpoint	—	外部 CDP ws:// URL。
--format	json	json 或 markdown。
--config	—	内联 JSON 或 @file.json 提供完整 CrawlConfig。

多个种子 URL 可按位置参数传入。

场景选择

自有文档站：

crawlberg crawl https://docs.example.com \
  --depth 5 --max-pages 1000 --concurrent 16 --rate-limit 100 \
  --stay-on-domain --format markdown > docs.md

在自有基础设施上可提高并发、降低请求间隔。

第三方站点：

crawlberg crawl https://blog.unknown.example \
  --depth 2 --max-pages 50 --concurrent 4 --rate-limit 500 \
  --stay-on-domain --respect-robots-txt --format markdown

保持浅层、限制页面数、严格限速、遵守 robots。

多种子批量：

crawlberg crawl \
  https://example.com/blog \
  https://example.com/docs \
  https://example.com/pricing \
  --depth 2 --max-pages 100 --stay-on-domain --format json

多种子抓取的 JSON 输出为 BatchCrawlResults 对象：{ "results": [ { "url", "result", "error" }, … ], "total_count", "completed_count", "failed_count" }。每个条目的 url 是种子 URL，result 是完整抓取载荷（失败时为 null），error 是同级字符串字段（成功时为 null）。使用 .results[] | {url, error} 迭代，而非顶层数组。

输出

Markdown 模式：

---
URL: https://example.com/page-one
---
# Page One

… markdown content …

---
URL: https://example.com/page-two
---
…

JSON 模式：顶层 CrawlResult 包含 pages: [...]。每个页面携带渲染后的 Markdown 以及元数据、链接、图片、JSON-LD 和 HTTP 响应信息。读取 result.pages[i].markdown.content 获取 Markdown 字符串。

适用场景

• 抓取自有文档站、博客、营销页面或整个域名。
• 对第三方站点进行浅层、限速、遵守 robots 的抓取。
• 多种子批量抓取并聚合结果。
• 需要将页面内容以 Markdown 或 JSON 形式保存时。

限制与注意事项

礼貌清单：

• 每次第三方抓取都传入 --respect-robots-txt。
• 限制 --max-pages，失控的 BFS 可能发出数万次请求。
• 对出现压力迹象（5xx、变慢）的主机提高 --rate-limit。
• 通过 --user-agent crawlberg (contact@example.com) 标识自己。

常见陷阱：

• 未返回页面：种子页可能仅依赖 JS，引擎在 --browser-mode auto 下会自动回退到无头模式，但 never 模式会静默产生空抓取。可用 --browser-mode always 重跑。
• 抓取离开域名：传入 --stay-on-domain。可在 --config JSON 中结合 allow_subdomains: true 包含子域名。
• 抓取缓慢：默认每源限速 200 毫秒，同一主机上的多个种子 URL 仍共享该桶。可将种子分散到不同主机，或对无关源提高 --concurrent。
• 内存增长：每个页面携带完整 Markdown 加结构化数据。应将 JSON 输出流式写入文件而非保留在内存中；若下游无法跟上，应积极设置 --max-pages。

何时改用 map：

如果用户只需要 URL 列表（站点地图分析、链接规划、为其他工具提供种子），使用 crawlberg map <url>——它跳过渲染，返回扁平的 MapResult，可在数秒内获得数百个 URL。