用途
Firecrawl CLI 用于网页抓取与内容提取。当页面依赖 JavaScript 渲染、属于单页应用（SPA），或需要结构化 Markdown 输出时，应优先使用 Firecrawl 而非 WebFetch。它也适用于“搜索加抓取”工作流，以及映射整个站点的 URL 树。
主要能力
- 搜索网页：支持普通搜索、搜索并抓取结果内容、按时间范围（如过去一天）过滤。
- 抓取单页：支持仅提取正文内容、等待 JS 渲染（--wait-for）、输出为 Markdown 等。
- 映射站点：生成站点 URL 列表，并可按关键词（如 blog）过滤。
- 并行批量抓取：小批量可用 & 与 wait，大批量可用 xargs -P 控制并发。
- 抓取后处理：可用 grep、jq 等工具从输出文件中提取标题、关键词匹配等。
- 认证与状态：提供 --status 检查认证与额度状态，login --browser 进行浏览器登录，也支持通过环境变量 FIRECRAWL_API_KEY 设置密钥。
使用方式
核心命令示例：
# 搜索
firecrawl search "query" -o .firecrawl/search.json --json
firecrawl search "query" --scrape -o .firecrawl/results.json --json
firecrawl search "AI news" --tbs qdr:d -o .firecrawl/today.json --json
# 抓取单页
firecrawl scrape https://example.com -o .firecrawl/example.md
firecrawl scrape https://example.com --only-main-content -o .firecrawl/clean.md
firecrawl scrape https://spa.com --wait-for 3000 -o .firecrawl/spa.md
# 映射站点
firecrawl map https://example.com -o .firecrawl/urls.txt
firecrawl map https://example.com --search "blog" -o .firecrawl/blog-urls.txt
并行批量抓取示例：
# 小批量
firecrawl scrape site1.com -o .firecrawl/1.md &
firecrawl scrape site2.com -o .firecrawl/2.md &
firecrawl scrape site3.com -o .firecrawl/3.md &
wait
# 大批量
cat urls.txt | xargs -P 10 -I {} sh -c 'firecrawl scrape "{}" -o ".firecrawl/$(echo {} | md5).md"'
抓取后提取示例：
grep "^# " .firecrawl/*.md
grep -l "keyword" .firecrawl/*.md
jq -r '.data.web[].title' .firecrawl/*.json
认证方式：
firecrawl --status
firecrawl login --browser
export FIRECRAWL_API_KEY=your_key
适用场景
- 需要抓取 JS 渲染页面或 SPA。
- 需要结构化 Markdown 输出。
- 需要搜索并抓取前 5-10 条结果内容，或进行 20+ 来源的深度研究（并行 Firecrawl）。
- 需要发现某个域名下的所有页面。
- 需要抓取位于认证或付费墙之后的页面（先执行 firecrawl login）。
限制与注意事项
- 不要串行抓取 6 个以上 URL：10 个串行抓取需 50 秒以上，并行只需 5-8 秒，且串行不会报错，只是变慢。
- 不要未检查大小就把整个 .firecrawl/*.md 输出文件读入上下文，抓取页面常超过 5000 行；应先用 wc -l，再用 grep/head 提取所需内容。
- 不要用 Firecrawl 获取实时数据（如股价、体育比分）：抓取结果有 10 秒以上延迟，且每次请求消耗额度，应使用直接 API。
- 不要对已有官方 SDK/API 的站点使用 Firecrawl（例如 GitHub 应使用 gh）。
- 不要省略 -o 参数：否则输出只到 stdout 且不会持久化，浪费额度并需要重新抓取。
- 认证抓取前不要跳过 firecrawl --status：认证静默失败会返回空输出而非报错。
- 批量运行前应检查容量：firecrawl --status 显示 Concurrency: X/100。
- 规模决策：1-5 页用串行加 -o；6-50 页用 & 与 wait 并行；50+ 页用 xargs -P 10，并先检查并发容量。
- 输出应始终写入 .firecrawl/ 目录（并加入 .gitignore）。
- 常见错误排查：未认证时检查 --status 并执行 login --browser；并发限制时查看 --status 并等待或降低 -P；页面加载失败时用 curl -I 检查连通性，加 --wait-for 5000，或尝试 --format html 查看原始 HTML；输出文件为空时用 head -20 查看，加 --only-main-content 或 --include-tags article,main。
- 参考文件加载时机：排查 3 个以上未知标志、请求头注入、Cookie 处理、站点地图模式或自定义 user-agent 时加载 references/cli-options.md；构建 3 步以上转换管道、解析搜索结果嵌套 JSON、合并或去重 10 个以上抓取文件时加载 references/output-processing.md；基础搜索/抓取/映射使用标准标志时不要加载参考文件。
- 参数 $ARGUMENTS：搜索查询、URL 或抓取目标；为空时询问要抓取什么。