firecrawl-map

firecrawl-map 技能概览

firecrawl-map 是做什么的

firecrawl-map 是一个专门用于发现网站 URL 的技能。它最适合这样的场景：你知道目标域名，但不清楚具体页面；或者你想在正式进行 scraping、crawling 或内容提取之前，先快速摸清网站结构。

谁适合使用 firecrawl-map 技能

firecrawl-map 技能最适合以下这类做网页研究、站点发现或抓取前规划的人：

• 需要先找到正确页面、再进行深度提取的 AI agents
• 在搭建 web scraping 工作流的开发者
• 想审查某个站点公开 URL 覆盖面的研究人员
• 需要快速拿到一份 URL 列表、但不想直接启动完整 crawl 的运营或技术人员

它真正解决的任务是什么

大多数用户真正想要的，并不是“拿到所有页面”本身，而是回答这类问题：

• “这个网站上的 authentication 文档在哪？”
• “在我开始抓取前，这个域名下面到底有哪些页面？”
• “有没有基于 sitemap 的捷径，可以更快发现 URL？”
• “我应该先 map，再 crawl，还是直接开始 crawl？”

也正因为如此，firecrawl-map for Web Scraping 更适合当作发现阶段的工具，而不是最终的数据提取工具。

为什么大家会选择 firecrawl-map

它最核心的差异点是：速度快，而且范围可控。相比一句泛泛的提示词，比如“帮我找 docs 页面”，firecrawl-map 提供的是一条可复现的 CLI 路径：你可以列出 URL、按搜索词过滤，并把结果导出给后续步骤使用。

从仓库里能明确看到的主要优势包括：

• 可直接通过 firecrawl map 使用
• 对大站点可选 --search 过滤
• URL 清单可输出为文本或 JSON
• 支持选择 sitemap 策略
• 很适合作为 search 与更深层 crawl/scrape 之间的中间步骤

它不适合做什么

如果你需要的是以下能力，firecrawl-map 就不是合适的工具：

• 提取完整页面内容
• 交互式浏览
• 从每个页面做详细的结构化 scraping
• 超出 URL 发现范围的复杂站点遍历逻辑

在这些场景里，mapping 是准备步骤，不是终点。

如何使用 firecrawl-map 技能

firecrawl-map 技能的安装与运行前提

这个技能位于 firecrawl/cli 仓库的 skills/firecrawl-map 目录下。它的设计前提是运行环境能够执行：

• firecrawl *
• npx firecrawl *

如果你的 agent 或本地工作流可以执行 Bash 命令，那么通常按下面这条 firecrawl-map 安装/调用路径就够用了：

npx firecrawl map "<url>" --limit 100

如果你已经全局安装了 Firecrawl CLI，则可以直接用：

firecrawl map "<url>" --limit 100

使用前先看这个文件

建议先从这里开始：

• skills/firecrawl-map/SKILL.md

这个仓库切片本身很小，可供翻阅的辅助材料不多。这对快速上手是好事，但也意味着你在写提示时最好把域名、目标和输出格式说得更明确。

firecrawl-map 的基础用法模式

这个技能主要有两种常见使用方式。

1. 按主题找最可能的页面：

firecrawl map "https://example.com" --search "authentication" -o .firecrawl/filtered.txt

2. 获取更广泛的 URL 清单：

firecrawl map "https://example.com" --limit 500 --json -o .firecrawl/urls.json

这就是最核心的 firecrawl-map usage 模式：如果你是在找某一个页面，就先用 search 缩小范围；如果你是在为下一步 scraping 做规划，就先拿一份设定上限的 URL 列表。

这个技能需要什么输入

想把 firecrawl-map 用好，最好明确提供以下输入：

• 根 URL 或域名
• 你是需要一个最可能的页面，还是一批 URL
• 如果已知主题，给出搜索短语
• 期望返回 URL 的数量上限
• 输出格式：纯文本还是 JSON
• 是否需要把 subdomains 计算在内
• sitemap 应该怎么处理

弱输入：

• “Find docs on this site”

强输入：

• “Map https://docs.example.com, search for authentication, return top matching URLs as JSON, and include subdomains only if the main docs domain has too few results.”

后者能显著减少猜测空间，也让命令选择更直接。

如何把模糊需求改写成高质量提示

一个好用的 firecrawl-map 提示模板，通常可以在一句话里交代清楚这五件事：

• site
• intent
• scope
• filter
• output

示例：

• “Use firecrawl-map on https://example.com to list up to 200 public URLs, prefer sitemap discovery, skip unrelated subdomains, and save JSON output for later scraping.”

面向定向发现的示例：

• “Use firecrawl-map to find the page on https://example.com most related to pricing API limits, and write matching URLs to a text file.”

最佳工作流：先 map，再 scrape 或 crawl

一个实用的流程通常是这样的：

1. 如果你想定位某一个页面，先用带 --search 的 firecrawl map
2. 如果你需要更广的 URL 集合，就用带 --limit 和 --json 的 firecrawl map
3. 检查返回的 URL
4. 选出最相关的页面
5. 在你已经足够了解站点结构之后，再进入 scrape 或 crawl

与盲抓相比，这样更省时间，也更省成本。

会明显影响输出质量的选项

最重要的参数有这些：

• --search <query>：适合在大型站点里定位某个主题页面
• --limit <n>：防止结果集过大
• --json：更方便下游过滤和自动化处理
• --sitemap <include|skip|only>：当 sitemap 覆盖情况很关键时尤其有用
• --include-subdomains：可以扩大范围，但也更容易引入噪音
• -o, --output <path>：方便把结果接入 pipeline 复用

如果结果太杂，最先该收紧的通常是：搜索短语、域名范围，以及是否包含 subdomains。

如何选择 sitemap 策略

很多用户低估了 --sitemap 选项的重要性：

• only：如果你信任站点 sitemap，且想要更快、更干净的覆盖，这是最快的方式
• include：适合作为默认选项，既利用 sitemap，又不完全依赖它
• skip：当 sitemap 结果过旧、不完整或有误导性时更适合

对于文档站点来说，include 或 only 往往比无约束发现更能产出高质量的 firecrawl-map for Web Scraping 结果。

什么时候应该包含 subdomains

只有在目标内容可能不在主 hostname 下时，才建议使用 --include-subdomains，例如：

• docs.example.com
• developers.example.com
• support.example.com

对于企业官网，不要默认开启这个选项，除非你确实需要更广的覆盖。否则它很容易把营销页、支持页、应用入口等与你目标无关的内容也一并带进 URL 列表。

用户真正会用到的实战示例

查找 login 或 auth 文档页面：

firecrawl map "https://docs.example.com" --search "authentication" -o .firecrawl/auth-pages.txt

生成一份可复用的 JSON URL 清单：

firecrawl map "https://example.com" --limit 300 --json -o .firecrawl/site-map.json

针对 docs 站点优先使用仅 sitemap 发现：

firecrawl map "https://docs.example.com" --sitemap only --limit 500 --json

当 docs 所在位置不明确时，把范围扩大到 subdomains：

firecrawl map "https://example.com" --search "API reference" --include-subdomains

常见采用障碍

大家在使用 firecrawl-map 技能时，最大的卡点通常不是安装，而是请求本身不够清晰：

• 一开始就选了过大的域名范围
• 明明是在找单页，却忘了加 --search
• 没设 limit，一次拉回太多 URL
• 过早把 subdomains 也纳入范围
• 把 map 当成内容提取工具来用

如果第一次结果很乱，优先先缩小站点范围、明确主题，而不是急着换工具。

firecrawl-map 技能常见问题

firecrawl-map 比普通提示词更好吗？

如果任务是在已知站点上做 URL 发现，那么是的。普通提示词可能只能“猜”哪些页面比较像目标，而 firecrawl-map 提供的是一种具体、可复现的方式，去枚举并过滤目标域名下的 URL。

firecrawl-map 技能适合新手吗？

适合，因为它的命令面很小。最容易上手的起点就是下面这两个命令之一：

firecrawl map "https://example.com" --search "pricing"

firecrawl map "https://example.com" --limit 100 --json

新手最常见的错误，是让它去提取页面内容，而这并不属于这个技能的核心用途。

什么时候该用 firecrawl-map，而不是 crawling？

当你需要先理解站点结构，或先找出候选页面时，应该先用 firecrawl-map。等到发现阶段完成、你需要更广泛的遍历或页面级处理时，再进入 crawling。

什么时候不该用 firecrawl-map？

如果出现以下情况，就可以跳过它：

• 你已经知道精确 URL
• 你需要页面正文、metadata 或结构化提取
• 你需要的是浏览器交互，而不是 URL 列表
• 任务本身不是站点发现

firecrawl-map 适合大站点吗？

适合，但前提是你能控制范围。要有意识地使用 --search、--limit 和 sitemap 策略。大型站点恰恰是 firecrawl-map usage 最能体现价值的地方，但也是提示写得太松时最容易产生噪音的地方。

我该选哪种输出格式？

如果只是人工快速看一眼页面列表，选纯文本就够了。如果结果还要交给其他工具、脚本或下游步骤处理，就选 --json。

如何改进 firecrawl-map 技能的使用效果

一开始就把目标收得比你想象中更窄

想提升 firecrawl-map 结果质量，最简单的方法就是尽早缩小范围。如果你知道内容大概率在 docs 里，那就直接用 docs 的 hostname，不要从公司首页开始。

更好：

• https://docs.example.com

更差：

• https://example.com

搜索短语要贴近页面意图

对于 firecrawl-map 技能来说，search 的质量比关键词数量更重要。简短、贴近意图的短语，通常比塞满关键词的长句效果更好。

更好：

• authentication
• rate limits
• API reference

更差：

• where can I find complete developer authentication API reference and login documentation

前一种写法更利于 URL 过滤，通常也会返回更干净的匹配结果。

只要结果要进入下一步，优先选 JSON

如果你的下一步是 scrape、filter、classify 或 deduplicate，就直接用：

--json

这个小选择会让 firecrawl-map 工作流更适合自动化，也能减少手工清理。

map 不要只跑一次，要迭代着用

更稳的工作流通常是：

1. 先跑一次较窄范围的 --search
2. 检查最可能的 URL
3. 针对最合适的 subdomain 或 section 再跑第二次 map
4. 只有在确实需要时再提高 --limit
5. 等发现结果稳定后，再进入 scrape/crawl

这通常优于一次性跑一个超大任务，因为它能让信噪比保持更高。

留意 firecrawl-map 的常见失败模式

firecrawl-map for Web Scraping 常见的失败方式包括：

• 域名范围太大，导致无关 URL 过多
• 搜索词太模糊，导致漏掉目标页面
• 选错 sitemap 策略，导致清单不完整
• 没必要地开启 subdomains，导致结果噪音很重

这些问题都很好修：收紧站点范围、明确 query、切换 sitemap 模式，或者进一步缩小覆盖面。

用“成功标准”来改写提示

不要只说“给我所有 URL”，而要说明什么样的结果才算成功。

示例：

• “Use firecrawl-map to find pages related to authentication setup on https://docs.example.com. Return the most relevant URLs first, cap at 50, and save JSON output for follow-up scraping.”

这样一来，工具选择、参数设置和停止条件都会清晰得多。

保持一条简单的升级路径

可以按这条实用的决策路径来：

• 需要一个最可能的页面：map --search
• 需要一份 URL 清单：map --limit --json
• 需要页面内容：先 map，再 scrape
• 需要更广的遍历：先 map，再 crawl

这是在不把工作流搞复杂的前提下，改进 firecrawl-map 使用效果的最实用方式。