跳到正文
CrawlForge MCP
爬取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

NameTypeRequiredDefaultDescription
url
stringRequired-
该站点的任意 URL。其来源用于查找 `/sitemap.xml`；若触发回退爬取，它也是起始点。
Example: https://example.com
max_depth
numberOptional2
回退爬取的深度，1-5。找到 sitemap 时会被忽略。
Example: 2
include_external
booleanOptionalfalse
在每页链接列表中包含外部链接。仅限爬取模式——外部页面会被计数，但永远不会被访问。
Example: false
timeout
numberOptional15000
总时间预算（毫秒），1000-30000。实际会被限制在 18000 附近，以适配无服务器执行上限。
Example: 15000
respect_robots
booleanOptionaltrue
遵守目标站点的 robots.txt。保持 `true` 时，robots.txt 对 `CrawlForge` 禁止的路径会在抓取之前以 403 拒绝，且不扣除 credits。仅在你与目标站点另有约定时才设为 `false`——此时响应会带上一条 `warnings`，并且该覆盖会记录到你的 API key 上。
Example: true
max_inline_chars
numberOptional40000
内联返回的最大结果大小，以其 JSON 的字符数计（1,000-10,000,000）。超过后，响应会携带 `preview`（格式化 JSON 的前 `max_inline_chars` 个字符）、`result_handle`、`total_chars`、`truncated: true` 和 `expires_at`，其余部分由 [read_result](/docs/api-reference/tools/read-result) 读取，每次调用 1 credit。已存储的结果保留 1 小时。
Example: 40000

两种建立站点地图的方式

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

source: "sitemap"
从 {origin}/sitemap.xml 读取，最多跟进 3 个子 sitemap，上限 500 个 URL。快速而完整。由于未进行任何爬取，max_depth_reached 与 sitemap 均返回 null。
source: "crawl"
在没有可用 sitemap 时使用。在时间预算内进行最多 30 个页面的有界广度优先爬取。此时 sitemap 会填入每个页面上找到的链接。

请求示例

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 中说明。

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 方案： 100,000 credits/月 = 50,000 次站点映射（$99/月）

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

相关工具

crawl_deep
按深度与页数控制沿链接爬取（4 credits）
extract_links
获取单个页面上的链接（1 credit）
batch_scrape
从枚举出的 URL 中提取内容（每个 URL 5 credits）
scrape
对单个页面进行完整提取（2 credits）