unclecode/crawl4ai 開源 AI 爬蟲實戰教學:非同步高速抓網頁、清洗雜訊並輸出乾淨 Markdown
unclecode/crawl4ai 是 GitHub 最受歡迎的開源 LLM 網頁爬蟲,支援非同步抓取、動態 JS 渲染與智慧過濾廣告導覽列,直接輸出適合 RAG 的乾淨 Markdown。
寫過 RAG 系統或 AI 代理的工程師都知道,抓網頁最痛苦的不是發送請求,而是清洗資料。
傳統爬蟲抓回來的 HTML 塞滿導覽列、頁尾版權、廣告區塊與複雜的樣式標籤。直接餵給大型語言模型,只會浪費大量 Token 並稀釋上下文準確度。
unclecode/crawl4ai 正是為了解決這個痛點而生的開源網頁爬蟲。它在 GitHub 上擁有極高人氣,採用 Apache-2.0 授權並提供最新 v0.9.5 版本。
它能自動啟動無頭瀏覽器渲染動態 JavaScript 網頁,透過內建演算法過濾雜訊,直接輸出結構清晰的 Markdown 或 JSON 資料。
如果你正在建置知識庫、研究型代理或自動化資料管線,這套工具非常適合你。但若只是要抓取完全靜態且結構極簡的 API 回應,直接用輕量 HTTP 請求反而更省資源。
這份 Crawl4AI 教學懶人包會帶你搞懂核心架構、三種部署方式、過濾器實戰寫法、深度爬蟲指令、常見地雷與安全邊界。
Crawl4AI 是什麼?為什麼能取代傳統網頁爬蟲?
傳統的 requests 搭配 BeautifulSoup 雖然輕巧,但面對現代大量使用 React 或 Vue 渲染的單頁式網頁往往抓不到真正內容。
工程師若改用 Playwright 或 Selenium 手寫捲動與等待邏輯,又得自己維護瀏覽器資源池與雜訊清除規則,開發成本相當高。
unclecode/crawl4ai 把這兩層繁瑣工程封裝成單一非同步介面。底下透過 Playwright 驅動 Chromium、Firefox 或 WebKit 引擎,確保動態載入的評論、表格與無限捲動頁面都能完整渲染。
往上則整合了智慧版面過濾器與結構化抽取策略,讓輸出結果天生就符合大型語言模型的閱讀習慣。
為了讓不同技術背景的開發者都能快速理解,以下用白話拆解幾個常見核心名詞:
- RAG 檢索增強生成:一種讓模型在回答問題前,先從外部文件或網頁資料庫搜尋相關段落的技術架構。原始資料越乾淨,模型回答就越精準。
- 非同步瀏覽器資源池:指程式同時開啟多個背景瀏覽器分頁並行抓取網頁,不必等上一頁載完才抓下一頁,能大幅縮短批量抓資料的等待時間。
- Fit Markdown 精簡格式:這個工具獨有的輸出格式,透過內容權重演算法把選單、側邊欄與頁尾剔除,只保留真正有意義的正文段落。
- CDP 遠端瀏覽器協定:Chrome DevTools Protocol 的簡稱,允許爬蟲直接連線到已經開啟或遠端託管的瀏覽器實例來執行任務。

三種部署方案怎麼選?雲端 API、Python 套件與 Docker 對照表
官方目前提供三種執行模式,分別對應不同的開發階段與維運能力。在動手安裝前,先對照下表確認哪一種最符合你的團隊需求:
| 比較項目 | Crawl4AI Cloud 雲端服務 | Python 本機套件 | 自建 Docker 伺服器 |
|---|---|---|---|
| 瀏覽器執行位置 | 官方雲端託管與調度 | 你自己的 Python 處理程序 | 你本機或主機的 Docker 容器 |
| 動態 JS 與反爬處理 | 自動處理代理 IP 與封鎖牆 | 需自行設定代理與指紋參數 | 需自行設定代理與環境變數 |
| 內建網頁搜尋端點 | 支援 /search、/serp 與 /answer |
不含搜尋服務,僅負責抓取 | 不含搜尋服務,僅負責抓取 |
| 授權與使用成本 | 每月 1,000 免費點數,付費方案 10 美元起 | 完全免費開源,自付硬體資源 | 完全免費開源,自付主機費用 |
| 適合情境 | 想快速串接 Claude Code MCP 或免維運上線 | 整合進現有 Python 資料管線或腳本 | 團隊共用 REST API 與遠端代理呼叫 |
若你希望完全掌握資料隱私、把資料留在內網,或者有大量批次抓取需求,建議優先選擇 Python 本機套件或自建 Docker 伺服器。
若只是想讓開發工具快速連網查資料,雲端 API 每月提供的免費額度已經足夠個人測試。雲端版也支援單次最多 50 個網址的串流批次呼叫,以及最高 10,000 個網址的背景排程任務。
步驟教學:Python 安裝與快速上手指令
要在自己的電腦或伺服器執行這套爬蟲,整個流程只需兩步。第一步透過 pip 安裝核心套件,第二步執行官方初始化指令下載無頭瀏覽器核心:
pip install -U crawl4ai
crawl4ai-setup
crawl4ai-doctor
執行 crawl4ai-setup 時,系統會自動安裝 Playwright 所需的瀏覽器二進位檔與系統依賴。最後跑一次 crawl4ai-doctor 可以幫你診斷環境是否缺漏函式庫。
如果自動安裝瀏覽器失敗,可以改用手動指令補齊 Chromium。若你是想參與開源貢獻的開發者,也能直接複製官方儲存庫並以可編輯模式安裝:
python -m playwright install --with-deps chromium
環境檢查通過後,就能在 Python 中使用 AsyncWebCrawler 進行非同步抓取。下面這段官方標準範例會抓取 Hacker News 首頁並印出轉換後的 Markdown:
import asyncio
from crawl4ai import AsyncWebCrawler
async def main():
async with AsyncWebCrawler() as crawler:
result = await crawler.arun(url="https://news.ycombinator.com")
print(result.markdown)
asyncio.run(main())
除了寫 Python 腳本,安裝套件時也會一併註冊 crwl 命令列工具。日常測試某個網址的輸出效果,或者想快速進行深度爬蟲,直接在終端機下指令即可:
# 將單一網頁轉為 Markdown 輸出
crwl https://news.ycombinator.com -o markdown
# 採用廣度優先策略進行深度抓取,最多抓 10 頁
crwl https://docs.crawl4ai.com --deep-crawl bfs --max-pages 10
# 搭配設定好的 LLM 金鑰直接對網頁提問抽取資訊
crwl https://www.example.com/products -q "Extract all product prices"
延伸閱讀:Code Mode 是什麼?Claude Code 實驗功能的啟用步驟與限制
自建 Docker 伺服器與雲端 MCP 串接實戰
如果團隊裡有多個微服務或前端應用都需要呼叫爬蟲,把服務打包成 Docker 容器是最乾淨的做法。
官方映像檔同時支援 AMD64 與 ARM64 架構,在 Apple Silicon Mac 或一般雲端 Linux 主機都能直接跑起來。啟動時建議分配至少 1GB 的共享記憶體 --shm-size=1g,避免 Chromium 執行多頁面時發生崩潰。
基於安全性考量,官方預設要求設定 CRAWL4AI_API_TOKEN 權杖。若沒有設定 Token,容器只允許從內部網路存取:
export CRAWL4AI_API_TOKEN="$(openssl rand -hex 32)"
docker run -d -p 11235:11235 --name crawl4ai --shm-size=1g \
-e CRAWL4AI_API_TOKEN="$CRAWL4AI_API_TOKEN" \
unclecode/crawl4ai:latest
容器啟動約十秒後,就可以用 curl 呼叫 /md 端點測試 Markdown 轉換效果,或者打開瀏覽器前往 http://localhost:11235/playground 使用視覺化測試介面與監控儀表板:
curl -s http://localhost:11235/md \
-H "Authorization: Bearer $CRAWL4AI_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url": "https://news.ycombinator.com"}' | jq -r .markdown
自建 Docker 伺服器內建預熱的瀏覽器池,並提供多種開箱即用的 REST API 端點,方便你整合進自動化工作流:
- 格式轉換端點:
/md直接回傳清洗後的 Markdown,/html則回傳處理過的原始 HTML 結構。 - 批次與串流抓取:
/crawl適合標準多頁抓取任務,/crawl/stream支援即時串流回傳每一頁的抓取結果。 - 視覺化與動態腳本:
/screenshot與/pdf可擷取網頁畫面或輸出 PDF 檔,/execute_js則允許在頁面上執行自訂 JavaScript。
如果你平時習慣在終端機使用 Claude Code,也能直接透過一行指令把官方雲端託管服務接成 MCP 工具,讓程式代理隨時抓最新的技術文件來讀:
claude mcp add --transport http crawl4ai https://api.crawl4ai.com/mcp \
--header "Authorization: Bearer $CRAWL4AI_KEY"
進階實戰技巧:過濾雜訊與免 LLM 結構化抽取
很多新手剛開始使用時,只拿預設的 result.markdown 就結束了。其實這套工具真正省錢又精準的威力,在於「內容過濾」與「CSS Schema 抽取」。
1. 用 PruningContentFilterLXML 與 BM25 產出 Fit Markdown
當新聞網站或技術部落格充斥側邊欄、相關推薦與留言區時,可以掛載 PruningContentFilterLXML。
它會根據文字密度與 HTML 結構自動修剪掉邊角雜訊,把精華保留在 result.markdown.fit_markdown 欄位中。若你有明確的搜尋關鍵字,也能改用 BM25ContentFilter,只保留與查詢主題高度相關的段落:
import asyncio
from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, CacheMode
from crawl4ai.content_filter_strategy import PruningContentFilterLXML
from crawl4ai.markdown_generation_strategy import DefaultMarkdownGenerator
async def main():
run_config = CrawlerRunConfig(
cache_mode=CacheMode.BYPASS,
markdown_generator=DefaultMarkdownGenerator(
content_filter=PruningContentFilterLXML(
threshold=0.48,
threshold_type="fixed",
min_word_threshold=0
)
),
)
async with AsyncWebCrawler(config=BrowserConfig(headless=True)) as crawler:
result = await crawler.arun(
url="https://en.wikipedia.org/wiki/Web_crawler",
config=run_config
)
print("原始長度:", len(result.markdown.raw_markdown))
print("過濾後長度:", len(result.markdown.fit_markdown))
asyncio.run(main())
2. 免呼叫模型,用 JsonCssExtractionStrategy 零成本抽欄位
如果你的目標是商品列表、新聞標題或固定版型的資料表,千萬不要每一頁都送給大型語言模型抽取 JSON,那樣速度慢又燒錢。
JsonCssExtractionStrategy 讓你用標準 CSS 選擇器或 XPath 定義好欄位格式,直接在本機高速解析出結構化陣列。搭配 scan_full_page=True,程式還會自動捲動到頁面最底端觸發延遲載入內容:
import asyncio, json
from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, CacheMode, JsonCssExtractionStrategy
schema = {
"name": "Quotes",
"baseSelector": "div.quote",
"fields": [
{"name": "text", "selector": "span.text", "type": "text"},
{"name": "author", "selector": "small.author", "type": "text"},
{
"name": "tags",
"selector": "a.tag",
"type": "list",
"fields": [{"name": "tag", "type": "text"}],
},
],
}
async def main():
run_config = CrawlerRunConfig(
extraction_strategy=JsonCssExtractionStrategy(schema),
scan_full_page=True,
scroll_delay=0.5,
cache_mode=CacheMode.BYPASS,
)
async with AsyncWebCrawler(config=BrowserConfig(headless=True)) as crawler:
result = await crawler.arun(
url="https://quotes.toscrape.com/scroll",
config=run_config
)
quotes = json.loads(result.extracted_content)
print(f"成功抽取 {len(quotes)} 筆資料")
asyncio.run(main())
如果連手寫 CSS 選擇器都覺得麻煩,工具還內建 generate_schema 產生器。你只要用自然語言描述一次想抓的欄位,它就能幫你生成可重複使用的 Schema 規則,之後完全不花模型費用就能批次跑完上千頁。
遇到版型極度不規則、每次都變動的網頁時,也能切換成 LLMExtractionStrategy。透過 Pydantic 模型定義輸出結構,並串接 OpenAI 或本地端 Ollama 模型,就能完成語意層級的欄位抽取。
深度爬蟲、網址探索與大量並發控制
針對整站知識庫建置的需求,這套框架提供了完整的全站探索與容錯機制,不需要工程師自己從頭寫佇列管理:
- 三種深度遍歷策略:支援廣度優先 BFS、深度優先 DFS 與最佳優先 Best-First 探索策略,並且提供
resume_state斷點續傳機制,即使爬到一半當機也能接續執行。 - 自我適應智慧爬蟲:內建的
AdaptiveCrawler會邊爬邊評估目前收集到的資訊量,一旦判定已經足以回答使用者的查詢問題,就會自動停止往下探索,大幅節省頻寬與時間。 - 高速網址預先探索:透過
AsyncUrlSeeder結合網站 Sitemap 與 Common Crawl 索引,在開啟prefetch=True後探索網址的速度可提升五到十倍。 - 多網址並發調度:當手上有數百個網址要同時抓取時,可以使用
arun_many搭配記憶體自適應調度器,自動根據本機剩餘記憶體動態調節同時開啟的瀏覽器分頁數量。
此外,對於需要處理本地檔案或純 HTML 字串的場景,抓取介面也支援直接傳入 raw: 與 file:// 協定,讓同一套清洗與分塊管線能無縫複用在本機資料夾的 HTML 檔案上。
針對長篇技術文件或維基百科條目,系統內建了主題分塊、正則表達式分塊與句子分塊策略,並可結合 CosineStrategy 透過餘弦相似度篩選出最貼近查詢問題的段落,進一步壓低送進語言模型的上下文長度。
如果需要抓取必須登入會員才能瀏覽的網站,你可以在 BrowserConfig 中指定本機 user_data_dir 目錄並開啟 use_persistent_context=True,就能保留 Cookie 與登入工作階段,搭配 CrawlerRunConfig 中的 magic=True 參數即可自動處理常見的彈窗與反自動化偵測。
延伸閱讀:IBM LLMON 預覽公開:Granite 如何分開指令與資料,降低提示注入風險?
安全邊界、實務限制與常見地雷
把自動化爬蟲接進 AI 代理管線時,工程團隊必須留意以下幾個邊界與風險:
- 間接提示注入風險:外部公開網頁可能藏有針對 AI 的惡意隱藏文字。當網頁轉成 Markdown 送進模型上下文時,務必做好指令與外部資料的隔離,不要讓模型直接根據爬回來的內容執行高風險工具或刪除操作。
- 共享記憶體與 OOM 當機:在 Docker 環境跑無頭 Chromium 時,預設的
/dev/shm空間通常只有 64MB,非常容易在開啟分頁或渲染大型網頁時崩潰。實務上一定要加上--shm-size=1g參數,並適度限制並發任務數量。 - 快取機制造成資料過期:系統預設會啟用快取來加速重複抓取。如果你抓取的是即時股價、新聞首頁或經常更新的動態看板,記得在
CrawlerRunConfig中明確設定cache_mode=CacheMode.BYPASS,以免讀到舊的快取頁面。 - 反爬蟲與網站授權邊界:雖然工具提供
enable_stealth隱身模式與持久化瀏覽器設定檔use_persistent_context,但遇到嚴格的企業級驗證碼或付費牆時,本機端仍會受阻。在商業應用上,也需遵守目標網站的robots.txt規範與 Apache-2.0 授權的署名要求。
常見問題
這套工具需要付費購買 API Key 才能使用嗎?
不需要。它的核心 Python 套件與 Docker 自建伺服器版本完全採用 Apache-2.0 開源授權,你可以免費部署在自己的電腦或雲端主機上。只有選擇使用官方託管的雲端服務時,才需要申請 API Key 與計算額度。
遇到需要登入或有大量 JavaScript 動態載入的網頁怎麼辦?
你可以在 BrowserConfig 中設定 user_data_dir 與 use_persistent_context=True 來保存登入後的 Cookie 與瀏覽器狀態。針對無限捲動的網頁,則在 CrawlerRunConfig 開啟 scan_full_page=True 與適當的 scroll_delay,讓爬蟲自動捲動到底部再抽取內容。
除了 OpenAI,可以搭配本地端免費模型做結構化抽取嗎?
可以。LLMExtractionStrategy 底層相容 LiteLLM 介面。只要在 LLMConfig 中將 provider 指定為 ollama/llama3.3 等本地端模型名稱,並把 api_token 設為 "no-token",就能完全離線執行結構化資料抽取。
為什麼用 Docker 啟動時一定要設定 CRAWL4AI_API_TOKEN?
這是為了避免未經授權的外部連線濫用你的瀏覽器資源池。官方安全預設規定自建容器必須帶入 Token 驗證,未設定時服務只會對容器內部回應,無法從外部呼叫 REST API。
結語
unclecode/crawl4ai 把原本破碎的瀏覽器自動化、動態渲染、廣告清洗與結構化抽取整合成一套成熟且高效率的開源管線,是目前建置 AI 資料前處理層最實用的選擇之一。
它特別適合正在開發 RAG 知識庫、需要即時為 AI 代理補充網頁上下文、或是想用零模型成本穩定抽取固定版型網頁資料的工程師與資料團隊。
相對地,如果你只需要抓純靜態 API、完全沒有前端渲染需求,或是沒有意願維護 Docker 與代理伺服器設定的非技術使用者,直接採用輕量 HTTP 工具或現成雲端 SaaS 會更輕鬆。
如果你也想持續追蹤這類最新開源 AI 工程工具的實戰拆解與第一手設定技巧,歡迎立即訂閱免費 AI 郵報,每週幫你把繁雜的技術文件濃縮成能直接上線的懶人包。