firecrawl-download

firecrawl-download 技能概览

firecrawl-download 是做什么的

firecrawl-download 这个技能只专注于一件事：把一个网站或某个文档分区下载为结构清晰的本地文件。它会先做站点发现，再抓取页面，然后把每个页面保存到 .firecrawl/ 目录下，可输出为 markdown、截图，或每页多种格式。

如果你想离线保存一份文档、建立本地研究语料库，或者需要一个可重复执行的批量保存流程，firecrawl-download 会非常合适。相比泛泛的网页抓取提示词，firecrawl-download 更适合“整站/整块文档下载”这类场景，因为它已经把完整抓取流程封装好了，你不需要从零设计 crawl workflow。

谁适合使用 firecrawl-download 技能

最适合这类 firecrawl-download 技能的用户包括：

• 需要把文档保存到本地的开发者
• 收集站点内容做审阅的研究人员
• 搭建轻量内容归档的团队
• 希望用更少试错成本完成“下载这个网站”流程的 agents

如果你的真实目标是“把这个网站保存成可用的本地文件”，那这个技能比宽泛的 web scraping prompt 更对路。

安装前用户最关心什么

大多数人决定是否安装 firecrawl-download，核心都在看这四件事：

• 它能不能处理整个网站或整块文档分区，而不是只抓一个页面？
• 它保存出来的结果是不是可直接使用的本地目录结构？
• 它能不能限制范围，避免把不该下载的页面也抓下来？
• 它支不支持 markdown、截图等多种输出格式？

从技能源码来看，这四个问题答案都是肯定的。唯一需要提前知道的是：它被标记为 experimental，所以更适合把它当作一个高效的便利型工作流，而不是一个经过深度加固的归档系统。

在 Web Scraping 工作流中的关键差异

firecrawl-download for Web Scraping 的价值，不只是“抓得下来”这么简单。它真正的差异在于，这个命令把下面这些步骤打包在一起了：

• 先做 site mapping
• 再做 scraping
• 按页面输出文件
• 自动生成嵌套本地目录
• 下载时可以复用 scrape 选项

这也是为什么在“下载文档”场景里，它比单纯只返回页面内容的 scrape 命令更值得安装。

如何使用 firecrawl-download 技能

firecrawl-download 的安装上下文

从仓库内容来看，这个技能位于 firecrawl/cli 的 skills/firecrawl-download 目录下。一个实用的安装方式是：

npx skills add https://github.com/firecrawl/cli --skill firecrawl-download

安装后，优先查看：

• skills/firecrawl-download/SKILL.md

这个技能几乎没有太多辅助文件，因此 SKILL.md 就是最核心、最可靠的信息来源。

先看这个文件

建议你先从这里开始：

• skills/firecrawl-download/SKILL.md

这个文件能很快告诉你真实边界：firecrawl download 是一个实验性的便利命令，它把 map 和 scrape 组合在一起，把结果保存到 .firecrawl/ 下，并支持在下载过程中使用 scrape 选项。

firecrawl-download 的基础用法

使用 firecrawl-download skill 最快的方法，就是直接指向一个文档根目录或内容根路径：

firecrawl download https://docs.example.com

如果是无人值守执行，技能文档里明确建议使用：

firecrawl download https://docs.example.com -y

当你希望在 agent 或脚本工作流里跳过确认提示时，就应该加上 -y。

让技能发挥效果需要哪些输入

像“download this site”这种过于宽泛的请求，通常不够好。更有用的输入应该包括：

• 根 URL
• 你真正想下载的分区边界
• 最大页面数量
• 需要的输出格式
• 是否需要截图
• 需要排除什么内容

一个更强的请求会像这样：

“Use firecrawl-download to save https://docs.example.com locally as markdown with screenshots, include only /guides and /api, limit to 50 pages, and skip translated pages.”

这样的信息量，足够让技能在抓取前先把范围 map 对。

实际使用中最重要的命令模式

源码里能看到几种很有价值的高频用法：

# With screenshots
firecrawl download https://docs.example.com --screenshot --limit 20 -y

# Multiple formats per page
firecrawl download https://docs.example.com --format markdown,links --screenshot --limit 20 -y

# Filter by section
firecrawl download https://docs.example.com --include-paths "/features,/sdks"

这些示例之所以重要，是因为它们对应的正是实际落地时最常见的阻碍：内容太多、抓错分区，或者输出保真度不够。

本地会写入什么内容

这个技能会把输出保存到 .firecrawl/ 下的嵌套目录中。如果你请求了多种格式，那么每个页面可能会生成独立文件，例如：

• index.md
• links.txt
• screenshot.png

这种本地文件组织方式，是很多人选择安装 firecrawl-download 而不是临时写一个 scrape prompt 的关键原因之一。

如何把模糊目标改写成可执行的 prompt

如果你最初想到的是：

• “download this docs site”

更好的写法应该拆成：

• 目标 URL
• 希望包含的分区过滤条件
• 文件格式
• 是否需要截图
• 页面数量上限
• 需要排除的内容

给 agent 的示例 prompt：

“Use the firecrawl-download skill to download https://docs.example.com for offline use. Save as markdown plus screenshots, include only /getting-started,/api, cap at 30 pages, and use -y so the run is non-interactive.”

这样效果更好，因为它把范围和输出上的歧义都提前消掉了。

获得稳定结果的推荐 firecrawl-download 工作流

一个实用的 firecrawl-download guide 工作流可以这样走：

1. 先从最小但仍有价值的文档分区开始。
2. 在增加页面数量之前，先加上 --include-paths。
3. 第一次运行务必带上 --limit。
4. 检查 .firecrawl/ 的输出目录结构。
5. 只有在确实需要时，再加 --screenshot 或多格式输出。
6. 等第一轮样本结果没问题后，再扩大抓取范围。

这样可以避开一个很常见的失败模式：一开始就下载太多、太杂的内容。

什么情况下应该用 firecrawl-download，而不是普通 scrape

当你需要下面这些能力时，就应该优先考虑 firecrawl-download usage：

• 抓很多页面，而不是一个页面
• 需要本地文件，而不只是返回文本
• 需要一份可浏览的离线副本
• 需要快速保存一版文档快照供审阅或参考

如果你只需要单页内容，或者需要高度定制的提取逻辑，那普通 scrape 反而更合适。firecrawl-download 的核心价值，在于用更快的工作流完成站点级保存。

需要尽早了解的限制与权衡

从技能源码来看，最重要的实际约束包括：

• 它被标记为 experimental
• 它本质上是一个便利型命令
• 输出质量仍然取决于目标站点结构，以及你设置的范围过滤
• 不加限制地跑大范围下载，结果可能会很嘈杂，也可能远超预期

所以，这个技能非常适合“可控范围内的文档下载”，但并不意味着它能保证完美、完整的归档结果。

firecrawl-download 技能 FAQ

firecrawl-download 适合新手吗？

适合，尤其当你的任务就是“把文档保存到本地”时。它的命令示例很直观，交互式向导也能降低上手门槛。不过新手依然应该从较小的 --limit 和更窄的 --include-paths 开始，避免一次下载过大。

它和通用 AI 抓取提示词的真实区别是什么？

通用提示词当然也能描述任务，但 firecrawl-download 已经内置了更实用的模式：先 map 站点，再逐页 scrape，并按目录保存文件。这样既减少了前期搭建成本，也让整个流程更可重复。

firecrawl-download 只能用于文档站吗？

不是，但文档站确实是最明确、最匹配的使用场景。它在页面结构和路径相对可预测的网站上效果最好。对于高度动态、或者范围难以界定的网站，你可能需要更强的过滤条件，甚至换一种方法。

firecrawl-download 除了 markdown 还能保存别的格式吗？

可以。技能源码明确展示了每页多格式输出，以及可选截图功能。如果你的需求既包括可阅读文本，也需要视觉证据或页面辅助信息，这一点会很重要。

什么情况下不应该用 firecrawl-download？

如果你只需要以下这些能力，就不建议用 firecrawl-download：

• 单个页面
• 自定义提取 schema
• 在抓取过程中做深度后处理
• 一个有更严格完备性保证的归档 pipeline

这些场景下，更窄的 scrape 命令或更定制化的工作流通常会更合适。

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

先给 firecrawl-download 更收敛的范围

想提升 firecrawl-download 结果，最简单的方法就是减少歧义。优先明确使用：

• --include-paths
• --limit
• 清晰的文档根 URL

一个限定在 20 页的小范围任务，通常比一次失控的整站下载更有价值。

根据实际下游任务选择输出格式

不要默认把所有格式都打开。应该按下一步用途来选：

• markdown：适合阅读、搜索和 LLM ingestion
• links：适合关注结构关系的场景
• --screenshot：适合关注布局或 UI 证据的场景

这样既能减轻运行负担，也更方便后续审查输出结果。

全量下载前先做一次样本运行

一个很稳妥的迭代方式是：

firecrawl download https://docs.example.com --include-paths "/api" --limit 10 -y

先检查保存下来的文件，再决定是否扩展到更多分区或提高上限。这样能更早发现范围设定错误的问题。

常见失败模式，以及如何避免

典型问题包括：

• 下载了错误的分区
• 抓了过多页面
• 在自动化运行里忘记加 -y
• 请求了其实并不需要的输出格式

解决方式并不复杂：明确范围、首轮限制规模，并有意识地选择输出。

面向 agent 调用时，如何提升 prompt 质量

如果是由 agent 调用这个技能，建议在请求里明确说明：

• 精确的起始 URL
• 本地输出的目标用途
• 需要包含的分区
• 需要避开的分区
• 输出格式
• 运行规模上限

一个好的 prompt 例如：

“Use firecrawl-download to create an offline markdown copy of https://docs.example.com, only for /guides and /reference, with screenshots for each page, limited to 40 pages, and save non-interactively.”

这种写法会比“download the docs”执行效果好得多。

看完第一轮输出后，如何继续迭代

第一轮完成后，重点检查这些问题：

• .firecrawl/ 里是否包含了你预期的页面？
• 无关页面是不是太多？
• 你真正需要的是截图，还是纯文本就够？
• 下一轮应该扩大还是收窄 include paths？

提升 firecrawl-download skill 使用效果的最佳方式，不是盲目重跑，而是根据第一批结果真实产出的内容，调整范围和输出策略。