Back to Details

crw-map

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

crw-map — URL discovery without content

crw-map — 无需获取内容的URL发现

When to use

适用场景

  • You need to know which URLs exist on a site before committing to a crawl — map first, then crawl only the section you need.
  • Step 3 in the crw ladder: if you want content, combine with crw-scrape (single pages) or crw-crawl (bulk). Map is URL-only — no page content is returned.
  • Estimating crawl cost: 
    crw map docs.example.com | wc -l
    tells you how many pages a subsequent crawl would touch before you commit.
  • Finding a specific path: filter the URL list with 
    grep
    instead of crawling the whole site.
  • 在决定爬取网站之前，你需要先了解该网站存在哪些URL——先绘制网站地图，再仅爬取你需要的部分。
  • 这是crw工作流阶梯的第3步：如果需要获取内容，可以结合crw-scrape（单页面抓取）或crw-crawl（批量爬取）。Map仅返回URL，不返回页面内容。
  • 估算爬取成本：
    crw map docs.example.com | wc -l
    可以在你决定爬取前，告诉你后续爬取会涉及多少页面。
  • 查找特定路径：使用
    grep
    过滤URL列表，无需爬取整个网站。

Quick start

快速开始

CLI (binary on PATH):
bash
crw map "https://docs.example.com"                       # URLs to stdout
crw map "https://docs.example.com" -d 3 --format json   # JSON object, depth 3
crw map "https://example.com" --sitemap-only             # sitemap.xml only
crw map "https://example.com" --no-sitemap               # link crawl only
crw map "https://example.com" --format json > .crw/urls.json
MCP (inside an agent harness):
crw_map(url="https://docs.example.com")
crw_map(url="https://docs.example.com", maxDepth=3, limit=200)
crw_map(url="https://example.com", useSitemap=false)       # link crawl only
crw_map(url="https://example.com", crawlFallback=false)    # sitemap only
REST (drop-in for Firecrawl SDKs — just swap the base URL):
bash
curl -X POST "$CRW_API_URL/v1/map" -H "Authorization: Bearer $CRW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://docs.example.com","maxDepth":2,"limit":200}'
CLI（已添加至PATH的二进制文件）：
bash
crw map "https://docs.example.com"                       # 将URL输出到标准输出
crw map "https://docs.example.com" -d 3 --format json   # 输出JSON格式，深度为3
crw map "https://example.com" --sitemap-only             # 仅使用sitemap.xml
crw map "https://example.com" --no-sitemap               # 仅进行链接爬取
crw map "https://example.com" --format json > .crw/urls.json
MCP（在Agent harness中使用）：
crw_map(url="https://docs.example.com")
crw_map(url="https://docs.example.com", maxDepth=3, limit=200)
crw_map(url="https://example.com", useSitemap=false)       # 仅进行链接爬取
crw_map(url="https://example.com", crawlFallback=false)    # 仅使用站点地图
REST（可直接替换Firecrawl SDK的基础URL）：
bash
curl -X POST "$CRW_API_URL/v1/map" -H "Authorization: Bearer $CRW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://docs.example.com","maxDepth":2,"limit":200}'

Response: {"success":true,"data":{"links":[...]}} — links are under data.links

响应：{"success":true,"data":{"links":[...]}} — 链接位于data.links下

jq tip for REST: jq '.data.links[]'

REST的jq技巧：jq '.data.links[]'

undefined
undefined

Options

选项

NeedCLI flagMCP / REST field
Discovery depth
-d/--depth N
(default 2)
maxDepth
(default 2)
Result format
--format text|json
— (always JSON)
Sitemap only (no link crawl)
--sitemap-only
crawlFallback: false
Link crawl only (no sitemap)
--no-sitemap
useSitemap: false
Cap URL count—
limit
(default 100; 
0
= unbounded)
JS rendering
--js
—
Proxy
--proxy URL
—
Stealth mode
--stealth
—
Rate limit
--rate-limit N
(default 5.0 req/s)		—
Concurrency
--concurrency N
(default 10)		—
Per-page timeout
--timeout MS
(default 15000)		—
MCP truncates to 100 URLs by default (
truncated: true
+ 
totalDiscovered
in response). Pass 
limit: 0
to opt out.
需求CLI 标志MCP / REST 参数
发现深度
-d/--depth N
（默认值 2）
maxDepth
（默认值 2）
结果格式
--format text|json
—（始终为 JSON）
仅使用站点地图（不进行链接爬取）
--sitemap-only
crawlFallback: false
仅进行链接爬取（不使用站点地图）
--no-sitemap
useSitemap: false
限制URL数量—
limit
（默认值 100；
0
= 无限制）
JS渲染
--js
—
代理
--proxy URL
—
隐身模式
--stealth
—
请求速率限制
--rate-limit N
（默认值 5.0 次/秒）		—
并发数
--concurrency N
（默认值 10）		—
单页面超时时间
--timeout MS
（默认值 15000）		—
MCP默认会截断至100条URL（响应中包含
truncated: true
和
totalDiscovered
）。传入
limit: 0
可取消限制。

The map → scrape / crawl pattern

地图→抓取/爬取模式

bash
undefined
bash
undefined

1. Map to see what's there

1. 绘制地图，了解网站内容分布

crw map "https://docs.example.com" --format json > .crw/urls.json
crw map "https://docs.example.com" --format json > .crw/urls.json

2a. Grep for the section you need

2a. 筛选出你需要的板块

grep '"authentication"' .crw/urls.json
grep '"authentication"' .crw/urls.json

2b. Scrape a single page

2b. 抓取单个页面

crw scrape "https://docs.example.com/api/authentication"
crw scrape "https://docs.example.com/api/authentication"

2c. Or crawl the whole /api section

2c. 或爬取整个/api板块

crw crawl "https://docs.example.com/api" -d 2 -l 50

With MCP in a single agent turn:
crw_map(url="https://docs.example.com", limit=0)
crw crawl "https://docs.example.com/api" -d 2 -l 50

在Agent的单次调用中使用MCP：
crw_map(url="https://docs.example.com", limit=0)

inspect links[], pick the /changelog/* subset

查看links[]，选择/changelog/*子板块

crw_crawl(url="https://docs.example.com/changelog", maxDepth=1, maxPages=20)
undefined
crw_crawl(url="https://docs.example.com/changelog", maxDepth=1, maxPages=20)
undefined

Tips

使用技巧

  • Map before crawl, always. A 3-second map call can save a 10-minute crawl abort. If the map returns 5 000 URLs and you only need 
    /blog/*
    , scope the crawl to that sub-path.
  • Sitemap + crawl fallback (default) is the most complete. sitemap.xml gives canonical URLs; the BFS link scan catches pages not in the sitemap. Use 
    --sitemap-only
    only when you trust the sitemap is complete.
  • Depth 2 covers most docs sites. Increase to 3-4 for deeply nested wikis; 1 is enough to enumerate top-level sections.
  • Filter in shell, not in context. Pipe to 
    grep
    , 
    jq '.links[]'
    (CLI JSON output), or 
    wc -l
    rather than loading the full list into model context. For REST responses use 
    jq '.data.links[]'
    (links are nested under 
    data
    ).
  • No content returned. Map is intentionally URL-only. If you want page content, follow up with 
    crw scrape
    or 
    crw crawl
    .
  • 始终先绘制地图再爬取。一次3秒的地图调用可以避免10分钟的无效爬取。如果地图返回5000条URL，但你只需要
    /blog/*
    ，就将爬取范围限定在该子路径。
  • 默认的「站点地图+爬取 fallback」模式最全面。sitemap.xml提供规范URL；BFS链接扫描可以捕获未在站点地图中列出的页面。仅当你确信站点地图完整时，才使用
    --sitemap-only
    。
  • 深度2足以覆盖大多数文档类网站。对于深度嵌套的维基类网站，可以增加到3-4；深度1足以枚举顶级板块。
  • 在Shell中过滤，而非在模型上下文里。通过管道传递给
    grep
    、
    jq '.links[]'
    （CLI JSON输出）或
    wc -l
    ，而非将完整列表加载到模型上下文中。对于REST响应，使用
    jq '.data.links[]'
    （链接嵌套在
    data
    下）。
  • 不返回内容。Map工具特意仅返回URL。如果需要页面内容，请后续使用
    crw scrape
    或
    crw crawl
    。

See also

另请参阅

  • crw-scrape — scrape individual URLs from the map
  • crw-crawl — bulk content extraction after mapping
  • crw — hub skill with the full workflow ladder
  • crw-scrape — 从地图结果中抓取单个URL
  • crw-crawl — 绘制地图后进行批量内容提取
  • crw — 包含完整工作流阶梯的核心工具