爬取2 credits

map_site

以成本最低的方式优先枚举站点页面：若来源提供 sitemap.xml，则直接读取；只有在没有可用 sitemap 时才回退到爬取。响应会告诉您实际走的是哪条路径。

使用场景

抓取前先取得 URL 列表

先枚举，再把列表交给 batch_scrape——远比开启提取的爬取更省成本。

查看站点向搜索引擎公开了什么

sitemap 模式如实反映站点自己声明的内容，而这往往与沿链接可达的内容并不一致。

找出孤立或无链接指向的页面

将 sitemap 列表与一次 crawl_deep 的结果对比：出现在 sitemap 中但爬取从未到达的页面就是无入链页面。

在投入 credits 前先估算站点规模

total_pages 能在您开始按页付费提取之前，告诉您这项工作有多大。

Endpoint

POST/api/v1/tools/map_site

Auth Required

Free 方案 1 次请求/秒

2 credits

Parameters

max_depth 与 include_external 仅适用于回退爬取。当找到可用的 sitemap.xml 时，它们会被忽略，因为此时并不会发生爬取。

Name	Type	Required	Default	Description
url	string	Required	-	该站点的任意 URL。其来源用于查找 `/sitemap.xml`；若触发回退爬取，它也是起始点。 Example: https://example.com
max_depth	number	Optional	2	回退爬取的深度，1-5。找到 sitemap 时会被忽略。 Example: 2
include_external	boolean	Optional	false	在每页链接列表中包含外部链接。仅限爬取模式——外部页面会被计数，但永远不会被访问。 Example: false
timeout	number	Optional	15000	总时间预算（毫秒），1000-30000。实际会被限制在 18000 附近，以适配无服务器执行上限。 Example: 15000
respect_robots	boolean	Optional	true	遵守目标站点的 robots.txt。保持 `true` 时，robots.txt 对 `CrawlForge` 禁止的路径会在抓取之前以 403 拒绝，且不扣除 credits。仅在你与目标站点另有约定时才设为 `false`——此时响应会带上一条 `warnings`，并且该覆盖会记录到你的 API key 上。 Example: true

两种建立站点地图的方式

响应中的 source 会说明实际运行的是哪一种——两种模式返回相同的字段，但填充方式不同。

source: "sitemap"

从 {origin}/sitemap.xml 读取，最多跟进 3 个子 sitemap，上限 500 个 URL。快速而完整。由于未进行任何爬取，max_depth_reached 与 sitemap 均返回 null。

source: "crawl"

在没有可用 sitemap 时使用。在时间预算内进行最多 30 个页面的有界广度优先爬取。此时 sitemap 会填入每个页面上找到的链接。

sitemap 字段并不是一份 sitemap。在爬取模式下，它保存的是每个已爬取页面到其页面内链接的映射；在 sitemap 模式下则为 null。枚举出的 URL 始终位于 pages 中。

若站点在 /sitemap.xml 上以 200 状态返回一个 HTML 页面，该情况会被识别并拒绝，从而转入爬取模式，而不是错误地报告出一个无效页面。

请求示例

terminalBash

curl -X POST https://crawlforge.dev/api/v1/tools/map_site \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "max_depth": 2,
    "include_external": false,
    "timeout": 15000
  }'

响应示例

200 OK1,240ms

{
  "success": true,
  "data": {
    "base_url": "https://example.com",
    "source": "sitemap",
    "total_pages": 128,
    "internal_links": 128,
    "external_links": 0,
    "pages": [
      "https://example.com/",
      "https://example.com/pricing",
      "https://example.com/docs"
    ],
    "max_depth_reached": null,
    "sitemap": null
  },
  "credits_used": 2,
  "credits_remaining": 998,
  "processing_time": 1240
}

Field Descriptions

data.source值为 "sitemap" 或 "crawl"——说明本次结果由哪种策略产生。

data.total_pagespages 数组中的 URL 数量。

data.internal_links找到的去重内部链接数。在 sitemap 模式下与页面总数一致。

data.external_links去重后的外部链接数。在 sitemap 模式下始终为 0，因为不会读取任何页面正文。

data.pages枚举出的 URL——这正是您需要的列表。

data.max_depth_reached实际到达的最深爬取层级；在未进行爬取的 sitemap 模式下为 null。

data.sitemap仅限爬取模式：每个已爬取页面对应其页面内找到的链接。在 sitemap 模式下为 null。

错误处理

无法建立任何映射 (422 NO_PAGES_MAPPED)

既没有可用的 sitemap，起始 URL 也没有返回可供爬取的 HTML 页面。当 URL 指向 PDF、图片或 API 端点时很常见。不扣除 credits。

目标返回错误 (502 TARGET_HTTP_ERROR)

站点返回了非 2xx 状态。有反爬保护的站点通常会落到这里——请改用 stealth_mode。

URL 无效 (400 VALIDATION_ERROR)

url 格式错误、使用了 http/https 以外的协议，或解析到了私有地址。max_depth 须为 1-5，timeout 须为 1000-30000。

目标响应过慢 (504 FETCH_TIMEOUT)

站点未在预算时间内响应。可调高 timeout，但其上限约为 18000 毫秒。

被 robots.txt 拦截（403 Forbidden）

目标站点的 robots.txt 对 CrawlForge 禁止了该路径。若你与目标站点另有约定，可设置 respect_robots: false 予以覆盖——该覆盖会记录到你的 API key 上。该覆盖不适用于列入 CrawlForge 永久排除名单的主机——无论 respect_robots 取何值，这类主机一律被拒绝。只有入口 URL 会返回 403：遍历过程中发现的、被 robots.txt 禁止的 URL 会被排除在站点地图之外，并在 warnings 中说明。

sitemap 模式并不是爬取模式的子集： sitemap 可能列出没有任何链接指向的页面，而爬取也可能到达 sitemap 未收录的页面。若两者都需要，请同时运行本工具与 crawl_deep 并比对两份列表。

credits 消耗

2 credits

每次请求 2 credits

固定 2 credits，无论结果来自包含 500 个 URL 的 sitemap，还是一次 30 页的爬取。失败的调用（包括无法建立映射时的 422）均不计费。

成本明细：

任意一次映射，sitemap 或爬取模式：2 credits

方案建议：

Free 方案： 1,000 个一次性试用 credits = 500 次站点映射

Hobby 方案： 5,000 credits/月 = 2,500 次站点映射（$19/月）

Professional 方案： 50,000 credits/月 = 25,000 次站点映射（$99/月）

映射是估算工作量最省钱的方式——先枚举，再只对真正需要的 URL 支付按页计费的 credits。

相关工具

crawl_deep

按深度与页数控制沿链接爬取（4 credits）

extract_links

获取单个页面上的链接（1 credit）

batch_scrape

从枚举出的 URL 中提取内容（每个 URL 5 credits）

scrape

对单个页面进行完整提取（2 credits）

准备好试用 map_site 了吗？免费注册，获得 1,000 credits，为您的第一个站点建立地图。

使用场景

抓取前先取得 URL 列表

先枚举，再把列表交给 batch_scrape——远比开启提取的爬取更省成本。

查看站点向搜索引擎公开了什么

sitemap 模式如实反映站点自己声明的内容，而这往往与沿链接可达的内容并不一致。

找出孤立或无链接指向的页面

将 sitemap 列表与一次 crawl_deep 的结果对比：出现在 sitemap 中但爬取从未到达的页面就是无入链页面。

在投入 credits 前先估算站点规模

total_pages 能在您开始按页付费提取之前，告诉您这项工作有多大。

Parameters

max_depth 与 include_external 仅适用于回退爬取。当找到可用的 sitemap.xml 时，它们会被忽略，因为此时并不会发生爬取。

Name	Type	Required	Default	Description
url	string	Required	-	该站点的任意 URL。其来源用于查找 `/sitemap.xml`；若触发回退爬取，它也是起始点。 Example: https://example.com
max_depth	number	Optional	2	回退爬取的深度，1-5。找到 sitemap 时会被忽略。 Example: 2
include_external	boolean	Optional	false	在每页链接列表中包含外部链接。仅限爬取模式——外部页面会被计数，但永远不会被访问。 Example: false
timeout	number	Optional	15000	总时间预算（毫秒），1000-30000。实际会被限制在 18000 附近，以适配无服务器执行上限。 Example: 15000
respect_robots	boolean	Optional	true	遵守目标站点的 robots.txt。保持 `true` 时，robots.txt 对 `CrawlForge` 禁止的路径会在抓取之前以 403 拒绝，且不扣除 credits。仅在你与目标站点另有约定时才设为 `false`——此时响应会带上一条 `warnings`，并且该覆盖会记录到你的 API key 上。 Example: true

两种建立站点地图的方式

响应中的 source 会说明实际运行的是哪一种——两种模式返回相同的字段，但填充方式不同。

source: "sitemap"

从 {origin}/sitemap.xml 读取，最多跟进 3 个子 sitemap，上限 500 个 URL。快速而完整。由于未进行任何爬取，max_depth_reached 与 sitemap 均返回 null。

source: "crawl"

在没有可用 sitemap 时使用。在时间预算内进行最多 30 个页面的有界广度优先爬取。此时 sitemap 会填入每个页面上找到的链接。

curl -X POST https://crawlforge.dev/api/v1/tools/map_site \ -H "X-API-Key: cf_test_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com", "max_depth": 2, "include_external": false, "timeout": 15000 }'

响应示例

200 OK1,240ms

{
  "success": true,
  "data": {
    "base_url": "https://example.com",
    "source": "sitemap",
    "total_pages": 128,
    "internal_links": 128,
    "external_links": 0,
    "pages": [
      "https://example.com/",
      "https://example.com/pricing",
      "https://example.com/docs"
    ],
    "max_depth_reached": null,
    "sitemap": null
  },
  "credits_used": 2,
  "credits_remaining": 998,
  "processing_time": 1240
}

Field Descriptions

data.source值为 "sitemap" 或 "crawl"——说明本次结果由哪种策略产生。

data.total_pagespages 数组中的 URL 数量。

data.internal_links找到的去重内部链接数。在 sitemap 模式下与页面总数一致。

data.external_links去重后的外部链接数。在 sitemap 模式下始终为 0，因为不会读取任何页面正文。

data.pages枚举出的 URL——这正是您需要的列表。

data.max_depth_reached实际到达的最深爬取层级；在未进行爬取的 sitemap 模式下为 null。

data.sitemap仅限爬取模式：每个已爬取页面对应其页面内找到的链接。在 sitemap 模式下为 null。

错误处理

无法建立任何映射 (422 NO_PAGES_MAPPED)

既没有可用的 sitemap，起始 URL 也没有返回可供爬取的 HTML 页面。当 URL 指向 PDF、图片或 API 端点时很常见。不扣除 credits。

目标返回错误 (502 TARGET_HTTP_ERROR)

站点返回了非 2xx 状态。有反爬保护的站点通常会落到这里——请改用 stealth_mode。

URL 无效 (400 VALIDATION_ERROR)

url 格式错误、使用了 http/https 以外的协议，或解析到了私有地址。max_depth 须为 1-5，timeout 须为 1000-30000。

目标响应过慢 (504 FETCH_TIMEOUT)

站点未在预算时间内响应。可调高 timeout，但其上限约为 18000 毫秒。

被 robots.txt 拦截（403 Forbidden）

credits 消耗

2 credits

每次请求 2 credits

固定 2 credits，无论结果来自包含 500 个 URL 的 sitemap，还是一次 30 页的爬取。失败的调用（包括无法建立映射时的 422）均不计费。

成本明细：

任意一次映射，sitemap 或爬取模式：2 credits

方案建议：

Free 方案： 1,000 个一次性试用 credits = 500 次站点映射

Hobby 方案： 5,000 credits/月 = 2,500 次站点映射（$19/月）

Professional 方案： 50,000 credits/月 = 25,000 次站点映射（$99/月）

映射是估算工作量最省钱的方式——先枚举，再只对真正需要的 URL 支付按页计费的 credits。