Crawl4AI 学习指南（适用于 v0.7.x，更新于 2025-12-18）

https://docs.crawl4ai.com/core/quickstart/

本文面向希望快速上手并理解 Crawl4AI 工作原理的开发者，涵盖安装、核心概念、常用配置、运行流程、调试与性能优化。示例以异步接口（AsyncWebCrawler）为主。

1. 它是什么

• 开源、LLM 友好的浏览器爬虫框架，自动把网页转成干净 Markdown/HTML，支持 CSS/XPath/LLM 等提取策略。
• 以 Playwright 启动浏览器，提供丰富的运行配置与 Hook，适合 RAG、数据收集、产品监测等场景。

2. 安装与环境准备

1. Python & 虚拟环境：推荐 Python ≥3.9，使用 venv 或 conda。
2. 安装库：

   pip install -U crawl4ai        # 核心功能
   # 或安装全量特性（含 LLM/向量/模型依赖）
   pip install "crawl4ai[all]"
   

3. 浏览器下载（必做，否则会报 Executable not found）：

   python -m playwright install chromium
   

4. 一次性初始化/自检（可选）：

   crawl4ai-setup     # 下载模型、校验依赖
   crawl4ai-doctor    # 输出环境检查结果
   

3. 核心组件与职责

• AsyncWebCrawler：对外入口，负责生命周期管理（启动/关闭浏览器）、调度单次或批量抓取。
• BrowserConfig：浏览器级别设置（引擎、headless、用户代理、代理、超时、视口等）。
• CrawlerRunConfig：单次抓取的运行参数（缓存、会话、等待条件、过滤、提取策略、Markdown 生成等）。
• CrawlerStrategy（默认 Playwright 策略）：控制页面创建、导航、Hook 调用、出错重试。
• BrowserManager：封装 Playwright 的浏览器/上下文/页面资源池，处理启动、复用与关闭。
• CrawlResult：返回的结果对象，常用字段：success、status_code、error_message、html、cleaned_html、markdown、links、images、metadata。
• Hook 体系：before_goto / after_goto / before_extract / after_extract 等，可插入自定义逻辑。

4. 最小可运行示例

import asyncio
from crawl4ai import AsyncWebCrawler

async def main():
    async with AsyncWebCrawler() as crawler:
        result = await crawler.arun(url="https://example.com")
        print(result.markdown[:300])

asyncio.run(main())

5. 常用配置速查

创建配置对象：from crawl4ai.async_configs import BrowserConfig, CrawlerRunConfig，枚举如 CacheMode 也在同一命名空间。

5.1 BrowserConfig（浏览器级）

• browser_type: "chromium"（默认）/"firefox"/"webkit"
• headless: True/False，调试时可设 False。
• user_agent: 伪装 UA。
• proxy: 形如 http://user:pass@host:port。
• viewport: 视口大小，提升渲染一致性。
• timeout: 启动/新页超时毫秒数。

5.2 CrawlerRunConfig（单次抓取级）

• 缓存/会话：
  • cache_mode: CacheMode.ENABLED（读写缓存）、BYPASS（跳过读取但写入）、DISABLED（完全不用缓存）。
  • session_id: 复用浏览器会话，适合需要登录或保持 Cookie 的场景。
• 导航控制：
  • timeout: 单页导航超时（毫秒）。
  • wait_for: CSS 选择器或可执行条件，等待元素出现再提取。
  • js_code / c4a_script: 进入页面后执行 JS（如点击“加载更多”）。
• 内容过滤：
  • excluded_tags: 例如 ["nav", "footer"] 去除导航/页脚噪音。
  • exclude_external_links、exclude_social_media_domains: 剔除外链或社媒域名。
  • word_count_threshold: 忽略过短文本块。
• 提取/转换：
  • extraction_strategy: CSS/XPath/LLM/JSON schema 等结构化提取策略。
  • chunking_strategy: RegexChunking 等切块方式，为 LLM/向量化做准备。
  • markdown_generator: 自定义 HTML→Markdown 规则。
• 合规与日志：
  • check_robots_txt: 遵守 robots.txt，默认建议开启。
  • verbose: 显示详细日志，排障友好。

6. 批量与并发示例

from crawl4ai import AsyncWebCrawler
from crawl4ai.async_configs import CrawlerRunConfig

urls = ["https://example.com", "https://www.python.org"]

async def main():
    run_cfg = CrawlerRunConfig(cache_mode="BYPASS", verbose=True)
    async with AsyncWebCrawler() as crawler:
        results = await crawler.arun_many(urls, config=run_cfg, max_concurrency=5)
        for url, res in zip(urls, results):
            print(url, res.success, len(res.markdown))

asyncio.run(main())

arun_many 内部基于 asyncio 并发；请自行控制 max_concurrency 以避免目标站点限流。

7. 动态站点与交互

• 使用 wait_for="div.article" 等待渲染完成。
• 在 js_code 中编写脚本模拟点击滚动：

  js = "document.querySelector('button.load-more')?.click();"
  run_cfg = CrawlerRunConfig(js_code=[js], wait_for=".item")
  

• 若站点需要登录：
  • 先手动登录并导出 Cookie，再在 BrowserConfig(cookies=...) 或自定义 Hook 中注入。
  • 结合 session_id 复用上下文，减少重复登录。

8. CLI 与 Docker（可选）

• CLI：

  crwl https://example.com -o markdown
  crwl https://docs.crawl4ai.com --deep-crawl bfs --max-pages 10
  

• Docker 体验版（0.7 系列）：

  docker pull unclecode/crawl4ai:0.7.0
  docker run -d -p 11235:11235 --shm-size=1g unclecode/crawl4ai:0.7.0
  # Playground: http://localhost:11235/playground
  

9. 运行流程原理（简化视图）

1. 创建 AsyncWebCrawler → 根据 BrowserConfig 启动 Playwright 浏览器。
2. 为每个 URL 创建页面 → 执行 Hook before_goto。
3. page.goto(url, wait_until="domcontentloaded") 或按 wait_for 条件等待。
4. 执行 js_code/c4a_script → 再次等待条件。
5. 提取：
   • 抽取原始 HTML → 清洗（移除噪音标签、外链等）。
   • Markdown 生成 + 可选结构化提取（CSS/XPath/LLM）。
6. 组装 CrawlResult 返回；触发 after_extract 等 Hook。
7. 关闭页面/浏览器（或由上下文管理器自动处理）。

10. 性能与稳定性建议

• 显式设置 cache_mode 与 session_id，避免不确定的缓存行为。
• 控制并发：对公共站点保持礼貌（并发 3–5），必要时加延时或限速。
• 过滤噪音：excluded_tags/word_count_threshold 减少无用文本，降低后续 LLM 成本。
• 统一环境：在容器/CI 中固定字体、locale、Playwright 版本，避免渲染差异。
• 调试时设 verbose=True，并可将 headless=False 观察页面。

11. 常见错误排查

• Executable doesn’t exist：未运行 python -m playwright install chromium。
• ERR_CONNECTION_RESET / 超时：网络被拦截或目标站不可达；先用 curl 验证，再配置代理 proxy。
• robots.txt 拒绝 (403)：关闭 check_robots_txt 仅用于测试，生产应遵守站点策略。
• 内容为空或截断：确认 wait_for/timeout 是否足够，或页面需滚动加载时加入 js_code。

12. 进一步学习

• 官方文档（v0.7.x）：https://docs.crawl4ai.com/
• 示例与源码：https://github.com/bogpad/crawl4ai
• 博客进阶文章：缓存/并发/提取策略性能调优（crawl4.com 博客系列）。

13. 与 LLM 交互（DeepSeek / ChatGPT 等）

Crawl4AI 基于 LiteLLM，支持任何被 LiteLLM 适配的提供商；通过 LLMConfig(provider=..., api_token=..., base_url=...) 即可切换模型。

13.1 安装与依赖

• 未安装 LLM 依赖时执行：pip install "crawl4ai[all]"（包含 LiteLLM 与常用模型适配）。
• 最小化依赖方案：确保有 pip install litellm，否则 LLMConfig 无法调用外部模型。

13.2 凭证与环境变量

• OpenAI / ChatGPT：export OPENAI_API_KEY=sk-...
• DeepSeek：export DEEPSEEK_API_KEY=sk-...，DeepSeek 兼容 OpenAI 协议，基址默认 https://api.deepseek.com/v1。
• 其他厂商遵循 LiteLLM 约定设置对应 *_API_KEY，如 ANTHROPIC_API_KEY、GROQ_API_KEY、GEMINI_API_KEY、OLLAMA_API_BASE+model 等。

13.3 快速示例：用 LLMExtractionStrategy 结构化提取

import os
from crawl4ai import AsyncWebCrawler, LLMConfig
from crawl4ai.extraction_strategy import LLMExtractionStrategy

llm_cfg = LLMConfig(
    provider="openai/gpt-4o-mini",          # ChatGPT 家族；改成 "deepseek/deepseek-chat" 即用 DeepSeek
    api_token=os.getenv("OPENAI_API_KEY"),
)

strategy = LLMExtractionStrategy(
    llm_config=llm_cfg,
    instruction="提取页面主标题(title)和摘要(summary)",
    schema={
        "type": "object",
        "properties": {
            "title": {"type": "string"},
            "summary": {"type": "string"}
        },
        "required": ["title", "summary"],
    },
)

async def main():
    async with AsyncWebCrawler() as crawler:
        result = await crawler.arun(
            url="https://example.com",
            extraction_strategy=strategy,
        )
        print(result.extracted_content)  # LLM 生成的结构化结果

13.4 切换到 DeepSeek

• 仅替换配置即可：

from crawl4ai import LLMConfig

deepseek_cfg = LLMConfig(
    provider="deepseek/deepseek-chat",      # 思维链版可用 deepseek/deepseek-reasoner
    api_token=os.getenv("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com/v1",  # OpenAI 兼容端点
)

13.5 常见坑位与优化

• 速率/费用：LLM 调用有延迟与成本，批量任务可在 LLMConfig 里调低并发或启用重试退避，或把长文先 chunk 后再投喂 LLM。
• 优先 schema：能用 CSS/XPath/正则解决的场景优先使用非 LLM 提取，LLM 仅补充复杂语义，能显著省费。
• 上下文压缩：对长页面可先用 chunking_strategy + 向量召回，减少进入 LLM 的 token。

14. AsyncPlaywrightCrawlerStrategy 是什么

• 定位：Crawl4AI 默认的浏览器抓取策略，实现 AsyncCrawlerStrategy 接口；负责创建/复用 Playwright 浏览器、上下文与页面，并把抓取结果交给后续清洗和提取管线。
• 主要职责：
  • 依据 BrowserConfig 启动（或复用）浏览器，设置代理、UA、视口、下载目录、Cookie、持久化会话等。
  • 按 CrawlerRunConfig 导航页面：执行 page.goto，等待 wait_until / wait_for 条件；可执行 js_code、虚拟滚动、Hook（before/after_goto、before/after_extract）。
  • 收集 HTML/截图/下载文件/网络资源，封装 CrawlResult（html、cleaned_html、markdown、links、images、metadata、extracted_content 等）。
• 适用场景：需要 JS 渲染、反爬交互、滚动加载、文件下载等动态站点。若目标是纯静态页面，可换用更轻的 HTTP 策略（如 AsyncHTTPCrawlerStrategy，0.5+ 提供）。
• 常用配置提示：
  • BrowserConfig: proxy / user_agent / accept_downloads / downloads_path / cookies / headless / timeout。
  • CrawlerRunConfig: wait_until / wait_for / js_code / virtual_scroll_config / check_robots_txt / cache_mode / session_id。
• 自定义挂载示例：

  from crawl4ai import AsyncWebCrawler, BrowserConfig
  from crawl4ai.async_crawler_strategy import AsyncPlaywrightCrawlerStrategy
  
  bcfg = BrowserConfig(headless=True)
  strategy = AsyncPlaywrightCrawlerStrategy(browser_config=bcfg)
  
  async with AsyncWebCrawler(
      config=bcfg,
      crawler_strategy=strategy,
  ) as crawler:
      res = await crawler.arun(url="https://example.com")
      print(res.success, len(res.markdown))
  

---

完成本篇后，你可以：

• 在本地运行简单或批量抓取；
• 通过配置 Cache/Session/Hook/JS 满足动态站点需求；
• 理解内部流程，定位常见问题并做性能优化。