firecrawl-map

firecrawl-map skill 概覽

firecrawl-map 的功能是什麼

firecrawl-map 是一個專門用來發現網站 URL 的聚焦型 skill。當你已知網域、但還不知道確切頁面在哪裡，或是在進行 scraping、crawl、內容擷取之前，想先快速盤點網站結構時，它特別好用。

誰適合使用 firecrawl-map skill

最適合使用 firecrawl-map skill 的，是在做網頁研究、網站探索，或前期爬取規劃的人：

• 在深入擷取前，先需要找出正確頁面的 AI agents
• 建置 web scraping 工作流程的開發者
• 稽核網站公開 URL 足跡的研究人員
• 想先快速拿到 URL 清單、但不想直接啟動完整 crawl 的操作人員

真正要解決的工作需求

多數使用者想要的其實不是「把所有頁面都抓出來」本身，而是想回答這類問題：

• 「這個網站的 authentication 文件在哪一頁？」
• 「在我開始 scrape 之前，這個網域底下有哪些頁面？」
• 「有沒有 sitemap 可用，能更快找到 URL？」
• 「我應該先 map，還是直接進 crawl？」

因此，firecrawl-map for Web Scraping 特別適合作為探索階段的工具，而不是最後的資料擷取步驟。

為什麼大家會選 firecrawl-map

它的主要差異點在於速度，以及對範圍的掌控。和「幫我找 docs 頁面」這種通用 prompt 相比，firecrawl-map skill 提供的是可重現的 CLI 路徑：你可以列出 URL、用搜尋詞過濾，並把輸出匯出給後續流程使用。

從 repository 可以看出的主要優勢包括：

• 可直接用 firecrawl map 透過 CLI 操作
• 大型網站可搭配 --search 做篩選
• URL 清單可輸出為文字或 JSON
• 支援選擇 sitemap 策略
• 很適合放在 search 與更深入 crawl／scrape 工作之間，作為中間步驟

它不適合拿來做什麼

當你需要以下能力時，firecrawl-map 就不是對的工具：

• 擷取完整頁面內容
• 互動式瀏覽
• 對每一頁進行詳細的結構化 scraping
• 超出 URL 發現範圍之外的複雜網站遍歷邏輯

在這些情境中，mapping 是前置準備，不是終點。

如何使用 firecrawl-map skill

firecrawl-map skill 的安裝與執行前提

這個 skill 位於 firecrawl/cli repository 的 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

這個 repository 區塊本身很小，可額外檢查的輔助材料不多。這有利於快速採用，但也代表你在 prompt 裡最好明確說清楚網域、目標，以及輸出格式。

firecrawl-map 的基本使用模式

這個 skill 支援兩種常見用法。

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 清單。

這個 skill 需要哪些輸入

想把 firecrawl-map skill 用好，以下輸入要清楚提供：

• 根 URL 或網域
• 你是要找一個可能頁面，還是要很多 URL
• 如果已知主題，請提供搜尋詞
• 希望回傳的 URL 數量上限
• 輸出格式：純文字或 JSON
• 是否要把子網域算進去
• sitemap 要如何處理

不夠好的輸入：

• 「幫我找這個網站的 docs」

較好的輸入：

• 「Map https://docs.example.com，搜尋 authentication，以 JSON 回傳最相關的 URL；只有在主 docs 網域結果太少時，才納入 subdomains。」

後者能大幅減少猜測空間，也讓應該用哪個指令變得很明確。

如何把模糊需求寫成高品質 prompt

一份好的 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

和盲目直接 scraping 相比，這樣通常更省時間，也更省成本。

會明顯影響輸出品質的選項

最重要的選項有：

• --search <query>：最適合在大型網站中定位某個主題頁面
• --limit <n>：避免結果集過大
• --json：讓後續篩選與自動化更容易
• --sitemap <include|skip|only>：當 sitemap 覆蓋率很重要時特別有用
• --include-subdomains：可擴大範圍，但也更容易引入雜訊
• -o, --output <path>：讓結果可在 pipeline 中重複利用

如果結果雜訊太多，優先收緊的通常是搜尋詞、網域範圍，以及是否納入子網域。

如何選 sitemap 策略

--sitemap 這個選項的重要性，往往比多數使用者預期的還高：

• only：如果你信任該網站的 sitemap，且想要更快、更乾淨的覆蓋，這是最快的選擇
• include：當你希望 sitemap 能幫忙、但又不想完全依賴它時，是很好的預設值
• skip：如果 sitemap 結果過期、不完整，或容易誤導時，這個選項更適合

對文件型網站來說，include 或 only 往往比不加限制的探索，更能得到好的 firecrawl-map for Web Scraping 結果。

什麼時候該納入子網域

只有在目標內容可能不在主 hostname 上時，才建議使用 --include-subdomains，例如：

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

對企業網站來說，不要把它當成預設開關，除非你真的想擴大涵蓋範圍。否則它很容易把 marketing、support 或 app 介面的 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-only 探索：

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

當 docs 位置不明時，把範圍擴大到子網域：

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

常見導入障礙

大家在使用 firecrawl-map skill 時，主要卡住的通常不是安裝，而是需求表達品質：

• 一開始就從過於寬泛的網域下手
• 明明是在找單一頁面，卻忘了加 --search
• 沒設上限就拉了太多 URL
• 太早納入 subdomains
• 把 map 當成內容擷取工具

如果第一次跑出來的結果很亂，先縮小網站範圍、把主題描述得更準，再考慮換工具。

firecrawl-map skill 常見問題

firecrawl-map 會比一般 prompt 更好嗎？

如果任務是在已知網站上做 URL 發現，答案是會。一般 prompt 可能只能猜哪些頁面比較可能存在，但 firecrawl-map 提供的是具體、可重複執行的方法，能直接列舉並篩選目標網域下的 URL。

firecrawl-map skill 適合新手嗎？

適合，因為它的指令面很小。最簡單的起手式就是以下兩條其中之一：

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

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

新手最常犯的錯，是要求它去擷取頁面內容；但這不在這個 skill 的核心用途內。

什麼時候該用 firecrawl-map，而不是直接 crawling？

當你需要先理解網站結構，或先找出候選頁面時，應先用 firecrawl-map。等完成探索後，如果你需要更廣泛的遍歷或頁面層級處理，再進入 crawling。

什麼情況下不該用 firecrawl-map？

以下情況可以直接跳過：

• 你已經知道確切 URL
• 你需要頁面文字、metadata 或結構化擷取
• 你需要的是瀏覽器互動，而不是 URL 列表
• 任務本身不是網站探索

firecrawl-map 在大型網站上好用嗎？

好用，但前提是你有控制好範圍。請有意識地使用 --search、--limit 和 sitemap 策略。大型網站正是 firecrawl-map usage 最有價值的場景，但也是 prompt 寫得太鬆時最容易產生雜訊的地方。

我該選哪種輸出格式？

如果只是要讓人快速看一份頁面清單，純文字就夠了。如果結果後面還要交給其他工具、script 或流程處理，請選 --json。

如何改善 firecrawl-map skill 的使用效果

一開始就把目標縮得比你想像中更窄

想改善 firecrawl-map 結果，最簡單的方法就是盡早縮小範圍。如果你已經知道內容大概率在 docs，直接用 docs hostname，而不是公司首頁。

較好：

• https://docs.example.com

較差：

• https://example.com

搜尋詞要對齊頁面意圖

對 firecrawl-map skill 來說，搜尋品質比關鍵字數量更重要。簡短、能表達意圖的詞組，通常比塞滿關鍵字的查詢更有效。

較好：

• 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 guide 更容易自動化，也能減少人工清理。

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

比較穩健的工作方式是：

1. 先跑一次範圍較窄的 --search
2. 檢查最可能的 URL
3. 針對最好的子網域或區段，再跑第二次 map
4. 只有在需要時才提高 --limit
5. 等探索結果穩定後，再進入 scrape／crawl

這樣通常比一次跑超大範圍更好，因為能把有效訊號維持在較高水位。

留意常見失敗模式

firecrawl-map for Web Scraping 常見的失敗模式包括：

• 因網域太寬而出現大量不相關 URL
• 搜尋詞太模糊，導致漏掉目標頁面
• 選錯 sitemap 策略，造成清單不完整
• 不必要地開啟 subdomains，讓結果過於雜亂

每一種都有相對直接的修正方式：縮小網站範圍、明確查詢詞、調整 sitemap 模式，或進一步收斂 scope。

以成功條件來寫 prompt

不要只說「給我所有 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 使用成果、又不會把工作流程複雜化的最實用方式。