crawl4ai

Crawl4AI 网页抓取工具指南

Crawl4AI 是一个功能强大的开源网页抓取和数据处理工具，支持 6 种不同的工作模式。所有二进制输出（截图、PDF）都以 base64 编码返回，便于模型处理。

🎯 【至关重要】通用调用结构

所有对 crawl4ai 的调用都必须严格遵循以下嵌套结构！ 这是一个通用规则，适用于所有模式。

{
  "mode": "<模式名称>",
  "parameters": {
    "param1": "value1",
    "param2": "value2"
    // ...具体模式的所有参数都放在这里
  }
}

❌ 常见致命错误：未嵌套参数

// 这是一个绝对会导致失败的错误调用！
{
  "mode": "scrape",
  "url": "https://example.com" // 错误！'url' 必须在 'parameters' 内部
}

✅ 正确的基础调用模式

{
  "mode": "scrape",
  "parameters": {
    "url": "https://example.com"
  }
}

🚀 新增智能分级系统

版本 1.2 重要更新： 新增智能分级抓取系统，自动适应不同网站类型：

| 配置等级 | 适用场景 | 特点 | 性能表现 | |---------|---------|------|----------| | 标准配置 | 普通静态网站 | 高性能，快速抓取 | ⚡ 快速 (90秒超时) | | 增强配置 | JS网站、反爬网站 | 加强反爬，完整渲染 | 🛡️ 稳健 (120秒超时) | | 降级配置 | 极端复杂网站 | 最大化兼容性 | 🐢 保守 (180秒超时) |

智能识别能力：

• ✅ 自动检测 JavaScript 驱动网站（React、Vue、Angular等）
• ✅ 识别反爬机制（Cloudflare、reCAPTCHA等）
• ✅ 缓存成功配置，加速后续抓取
• ✅ 失败自动降级，提高成功率

📋 可用模式快速选择指南

| 模式 | 功能描述 | 主要用途 | 复杂度 | 推荐场景 | |------|----------|----------|---------|----------| | scrape | 抓取单个网页 | 获取页面内容、截图、PDF | ⭐⭐ | 单页面内容获取 | | deep_crawl | 深度智能爬取 | 使用策略深度爬取网站 | ⭐⭐⭐⭐ | 网站内容探索 | | batch_crawl | 批量 URL 处理 | 同时处理多个 URL | ⭐⭐ | 批量数据收集 | | extract | 结构化数据提取 | 基于 CSS 或 LLM 提取数据 | ⭐⭐⭐ | 特定数据提取 | | pdf_export | PDF 导出 | 将网页导出为 PDF | ⭐ | 文档保存 | | screenshot | 截图捕获 | 捕获网页截图 | ⭐ | 视觉证据保存 |

注意： crawl 模式已在最新版本中移除，请使用 scrape 或 deep_crawl 替代。

🎯 使用场景快速指南

场景1：快速获取页面内容

{
  "mode": "scrape", 
  "parameters": {
    "url": "https://example.com/article",
    "format": "markdown",
    "word_count_threshold": 10,
    "include_links": true,
    "include_images": true
  }
}

场景2：批量收集产品信息

{
  "mode": "batch_crawl",
  "parameters": {
    "urls": [
      "https://example.com/product1",
      "https://example.com/product2",
      "https://example.com/product3"
    ],
    "concurrent_limit": 4
  }
}

场景3：深度研究某个网站

{
  "mode": "deep_crawl",
  "parameters": {
    "url": "https://example.com/docs",
    "max_depth": 3,
    "max_pages": 80,
    "keywords": ["教程", "指南", "API"],
    "strategy": "best_first"
  }
}

场景4：提取结构化数据

{
  "mode": "extract",
  "parameters": {
    "url": "https://news.example.com/article",
    "schema_definition": {
      "name": "Article",
      "baseSelector": ".article-content",
      "fields": [
        {
          "name": "title",
          "selector": "h1",
          "type": "text"
        },
        {
          "name": "author",
          "selector": ".author",
          "type": "text"
        },
        {
          "name": "content",
          "selector": ".content",
          "type": "text"
        }
      ]
    },
    "extraction_type": "css"
  }
}

场景5：保存网页证据

{
  "mode": "scrape",
  "parameters": {
    "url": "https://example.com",
    "return_screenshot": true,
    "return_pdf": true,
    "screenshot_quality": 90,
    "screenshot_max_width": 1200
  }
}

🚀 详细模式说明

1. 抓取单个网页 (scrape)

智能分级抓取：新版工具自动根据网站类型选择最佳配置方案。

✅ 正确示例:

{
  "mode": "scrape",
  "parameters": {
    "url": "https://example.com",
    "format": "markdown",
    "css_selector": ".article-content",
    "include_links": true,
    "include_images": true,
    "return_screenshot": true,
    "return_pdf": false,
    "screenshot_quality": 80,
    "screenshot_max_width": 1200,
    "word_count_threshold": 10,
    "exclude_external_links": true
  }
}

❌ 错误示例（参数未嵌套）:

{
  "mode": "scrape",
  "url": "https://example.com", // 错误！缺少parameters包装
  "format": "markdown"
}

智能分级抓取原理：

1. 自动识别：工具会分析URL特征，判断网站类型
2. 分级配置：
3. 标准配置：普通网站，90秒超时，高性能
4. 增强配置：JS网站/反爬网站，120秒超时，完整渲染
5. 降级配置：极端复杂网站，180秒超时，最大化兼容
6. 失败降级：如果当前配置失败，自动尝试更兼容的配置
7. 配置缓存：成功配置会缓存，后续同域名请求更快

参数说明:

• url (必需): 要抓取的网页 URL，必须以 http:// 或 https:// 开头
• format: 输出格式，markdown(默认)/html/text
• css_selector: 提取特定内容的 CSS 选择器
• include_links: 是否在输出中包含链接，默认 true
• include_images: 是否在输出中包含图片，默认 true
• return_screenshot: 是否返回截图(base64)，默认 false
• return_pdf: 是否返回 PDF(base64)，默认 false
• screenshot_quality: 截图质量(10-100)，默认 70
• screenshot_max_width: 截图最大宽度，默认 1920
• word_count_threshold: 内容块最小单词数，默认 10
• exclude_external_links: 是否排除外部链接，默认 true

2. 深度网站爬取 (deep_crawl)

使用智能策略深度爬取整个网站，支持关键词评分和 URL 过滤。

✅ 正确示例:

{
  "mode": "deep_crawl",
  "parameters": {
    "url": "https://example.com",
    "max_depth": 3,
    "max_pages": 80,
    "strategy": "best_first",
    "include_external": false,
    "keywords": ["产品", "价格", "规格"],
    "url_patterns": ["/products/", "/docs/"],
    "stream": false
  }
}

增强功能：

• ✅ Context错误自动恢复：捕获并处理Crawl4AI内部错误
• ✅ 智能超时处理：400秒超时保护，返回部分结果
• ✅ 流式心跳：定期进度更新，避免Cloudflare 524错误

参数说明:

• url (必需): 起始 URL
• max_depth: 最大爬取深度，默认 3
• max_pages: 最大页面数，默认 80
• strategy: 爬取策略，bfs(默认)/dfs/best_first
• include_external: 是否跟踪外部链接，默认 false
• keywords: 用于相关性评分的关键词列表
• url_patterns: URL 模式过滤列表
• stream: 是否流式返回结果，默认 false

3. 批量 URL 处理 (batch_crawl)

同时处理多个 URL，适用于批量数据收集。

✅ 正确示例:

{
  "mode": "batch_crawl",
  "parameters": {
    "urls": [
      "https://example.com/page1",
      "https://example.com/page2",
      "https://example.com/page3"
    ],
    "stream": false,
    "concurrent_limit": 4
  }
}

❌ 错误示例（urls不是数组）:

{
  "mode": "batch_crawl",
  "parameters": {
    "urls": "https://example.com/page1" // 错误！urls必须是数组
  }
}

安全限制：

• ⚡ 并发数硬性上限：4（无论参数设置多高）
• ⏰ 整体超时：300秒（5分钟）
• 📊 最大页面数：20（防止过度请求）

参数说明:

• urls (必需): URL 列表，必须是数组格式
• stream: 是否流式返回，默认 false
• concurrent_limit: 最大并发数，默认 4 (已根据服务器内存升级调整，并设置了硬性上限)

4. 结构化数据提取 (extract)

从网页中提取结构化数据，主要依赖精确的 CSS 选择器。

✅ 正确示例 (CSS 提取):

{
  "mode": "extract",
  "parameters": {
    "url": "https://news.example.com/article",
    "schema_definition": {
      "name": "Article",
      "baseSelector": ".article-content",
      "fields": [
        {
          "name": "title",
          "selector": "h1",
          "type": "text"
        },
        {
          "name": "author",
          "selector": ".author",
          "type": "text"
        },
        {
          "name": "publish_date",
          "selector": ".date",
          "type": "text"
        },
        {
          "name": "content",
          "selector": ".content",
          "type": "text"
        }
      ]
    },
    "css_selector": ".article-content",
    "extraction_type": "css"
  }
}

⚠️ 关键限制与最佳实践：

• AI 智能提取限制: crawl4ai 的 extraction_type: "llm" 模式尚未部署有效的 LLM 实例。
• 注意事项做法: crawl4ai 提取场景: 仅适用于您能提供精确 CSS 选择器的简单、结构固定的页面。无法实现仅凭自然语言描述和 JSON Schema（即不提供 CSS 选择器）从复杂页面（如表格、列表）中智能提取数据。

🛡️ 自动修复机制： 我们的工具会自动修复常见的 schema 格式问题：

• 如果缺少 baseSelector，自动设置为 css_selector 或 'body'
• 如果缺少 fields，自动创建默认字段配置
• 如果缺少 name，自动设置为 "ExtractedData"
• 如果 schema 是数组格式，自动转换为对象格式

💡 最佳实践： 虽然工具会自动修复，但提供完整的 schema 可以获得更精确的提取结果。

参数说明:

• url (必需): 要提取的网页 URL
• schema_definition (必需): 定义输出结构的 JSON schema
• css_selector: 基础 CSS 选择器（CSS 提取时使用）
• extraction_type: 提取类型，css(默认)/llm
• prompt: LLM 提取的提示语

📋 Schema Definition 结构说明

CSS 提取模式必需的 schema 结构：

{
  "name": "YourSchemaName",           // 必需：schema 名称
  "baseSelector": "css-selector",     // 必需：基础 CSS 选择器
  "fields": [                         // 必需：字段定义数组
    {
      "name": "field_name",           // 必需：字段名称
      "selector": "css-selector",     // 必需：字段选择器
      "type": "text",                 // 必需：字段类型
      "multiple": true                // 可选：是否允许多个值
    }
  ]
}

LLM 提取模式 schema 结构：

{
  "type": "object",
  "properties": {
    "field1": {"type": "string"},
    "field2": {"type": "array", "items": {"type": "string"}}
  }
}

5. PDF 导出 (pdf_export)

将网页导出为 PDF 格式。

✅ 正确示例:

{
  "mode": "pdf_export",
  "parameters": {
    "url": "https://example.com/document",
    "return_as_base64": true