---
name: crawl4ai
description: 功能强大的开源网页抓取和数据处理工具，支持6种工作模式，包括截图、PDF导出和智能爬取
tool_name: crawl4ai
category: web-crawling
priority: 9
tags: ["web-scraping", "screenshot", "pdf-export", "structured-data-extraction", "deep-crawling", "batch-processing", "content-extraction", "anti-detection", "automation"]
version: 1.2
---

# Crawl4AI 网页抓取工具指南

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

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

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

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

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

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

### ✅ 正确的基础调用模式

```json
{
  "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：快速获取页面内容
```json
{
  "mode": "scrape", 
  "parameters": {
    "url": "https://example.com/article",
    "format": "markdown",
    "word_count_threshold": 10,
    "include_links": true,
    "include_images": true
  }
}
```

### 场景2：批量收集产品信息
```json
{
  "mode": "batch_crawl",
  "parameters": {
    "urls": [
      "https://example.com/product1",
      "https://example.com/product2",
      "https://example.com/product3"
    ],
    "concurrent_limit": 4
  }
}
```

### 场景3：深度研究某个网站
```json
{
  "mode": "deep_crawl",
  "parameters": {
    "url": "https://example.com/docs",
    "max_depth": 3,
    "max_pages": 80,
    "keywords": ["教程", "指南", "API"],
    "strategy": "best_first"
  }
}
```

### 场景4：提取结构化数据
```json
{
  "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：保存网页证据
```json
{
  "mode": "scrape",
  "parameters": {
    "url": "https://example.com",
    "return_screenshot": true,
    "return_pdf": true,
    "screenshot_quality": 90,
    "screenshot_max_width": 1200
  }
}
```

## 🚀 详细模式说明

### 1. 抓取单个网页 (`scrape`)

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

**✅ 正确示例:**
```json
{
  "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
  }
}
```

**❌ 错误示例（参数未嵌套）:**
```json
{
  "mode": "scrape",
  "url": "https://example.com", // 错误！缺少parameters包装
  "format": "markdown"
}
```

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

**参数说明:**
- `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 过滤。

**✅ 正确示例:**
```json
{
  "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，适用于批量数据收集。

**✅ 正确示例:**
```json
{
  "mode": "batch_crawl",
  "parameters": {
    "urls": [
      "https://example.com/page1",
      "https://example.com/page2",
      "https://example.com/page3"
    ],
    "stream": false,
    "concurrent_limit": 4
  }
}
```

**❌ 错误示例（urls不是数组）:**
```json
{
  "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 提取):**
```json
{
  "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 结构：
```json
{
  "name": "YourSchemaName",           // 必需：schema 名称
  "baseSelector": "css-selector",     // 必需：基础 CSS 选择器
  "fields": [                         // 必需：字段定义数组
    {
      "name": "field_name",           // 必需：字段名称
      "selector": "css-selector",     // 必需：字段选择器
      "type": "text",                 // 必需：字段类型
      "multiple": true                // 可选：是否允许多个值
    }
  ]
}
```

### LLM 提取模式 schema 结构：
```json
{
  "type": "object",
  "properties": {
    "field1": {"type": "string"},
    "field2": {"type": "array", "items": {"type": "string"}}
  }
}
```

### 5. PDF 导出 (`pdf_export`)

将网页导出为 PDF 格式。

**✅ 正确示例:**
```json
{
  "mode": "pdf_export",
  "parameters": {
    "url": "https://example.com/document",
    "return_as_base64": true
  }
}
```

**参数说明:**
- `url` (必需): 要导出为 PDF 的网页 URL
- `return_as_base64`: 是否返回 base64 编码，默认 true

### 6. 截图捕获 (`screenshot`)

捕获网页截图，支持质量压缩和尺寸调整。

**✅ 正确示例:**
```json
{
  "mode": "screenshot",
  "parameters": {
    "url": "https://example.com",
    "full_page": true,
    "return_as_base64": true,
    "quality": 80,
    "max_width": 1200,
    "max_height": 3000
  }
}
```

**参数说明:**
- `url` (必需): 要截图的网页 URL
- `full_page`: 是否截取整个页面，默认 true
- `return_as_base64`: 是否返回 base64 编码，默认 true
- `quality`: 截图质量(10-100)，默认 70
- `max_width`: 最大宽度，默认 1920
- `max_height`: 最大高度，默认 5000

## 🛡️ 增强的反爬能力

**版本 1.2 新增反爬特性：**

### 浏览器指纹混淆
- ✅ 随机 User-Agent 轮换
- ✅ 随机视口尺寸 (1280-1920 × 720-1080)
- ✅ 隐身模式（Incognito）减少指纹追踪

### 高级浏览器参数
- ✅ 禁用自动化控制特征 (`--disable-blink-features=AutomationControlled`)
- ✅ 禁用 Web 安全和站点隔离
- ✅ 禁用扩展和通知
- ✅ 禁用 IP 泛洪保护

### 智能等待策略
- ✅ 标准配置：短等待 (1.0秒)，高性能
- ✅ 增强配置：中等等待 (2.0秒)，完整渲染
- ✅ 降级配置：长等待 (3.0秒)，最大化兼容

## 🔄 常见工作流

### 新闻文章采集工作流
**目标**: 自动收集和分析新闻内容
1. **发现阶段**: 使用 `deep_crawl` 发现相关文章链接
2. **采集阶段**: 使用 `batch_crawl` 批量获取内容  
3. **提取阶段**: 使用 `extract` 结构化提取关键信息

### 竞品分析工作流
**目标**: 系统化分析竞争对手网站
1. **证据收集**: 使用 `screenshot` 捕获竞品页面
2. **内容分析**: 使用 `scrape` 获取详细内容
3. **文档保存**: 使用 `pdf_export` 保存证据

### 产品目录爬取工作流  
**目标**: 建立完整的产品数据库
1. **目录探索**: 使用 `deep_crawl` 发现所有产品页面
2. **数据提取**: 使用 `extract` 提取产品信息

## 🛠️ 故障排除

### 常见问题与解决方案

#### 性能问题
- **超时问题**: 工具已内置智能超时，标准配置90秒，增强配置120秒，降级配置180秒
- **内存问题**: 启用 `stream: true`，减少批量处理的 URL 数量。后端已设置内存上限（6000MB），高并发可能触发浏览器重启

#### 内容质量问题  
- **内容缺失**: 调整 `word_count_threshold`，检查 `css_selector`
- **截图不完整**: 增加 `max_height` 值，确保 `full_page: true`

#### 网络问题
- **连接失败**: 检查 URL 格式，验证网络连接
- **被网站屏蔽**: 智能分级系统会自动降级配置，提高成功率

#### Extract 模式特定问题
- **空结果**: 检查 `fields` 数组中的 `selector` 是否准确匹配页面元素
- **字段缺失**: 确保 `schema_definition` 包含完整的 `name`、`baseSelector`、`fields` 结构
- **自动修复**: 工具会自动补全缺失字段，但手动提供完整 schema 效果更好

#### 智能分级系统问题
- **配置选择不当**: 工具会自动学习，失败次数多的URL会自动使用更兼容的配置
- **缓存问题**: 配置缓存按域名存储，清除浏览器实例会重置缓存

### 调试技巧

1. **从简单开始**: 先用 `scrape` 模式测试单个页面
2. **逐步增加复杂度**: 确认基础功能正常后再使用高级模式  
3. **检查参数**: 确保所有参数都正确嵌套在 `parameters` 对象内
4. **验证输出**: 先测试小规模数据，确认输出格式符合预期

## ⚠️ 重要提示

### ✅ 正确做法
- **参数嵌套**: 所有参数必须放在 `parameters` 对象内
- **URL 格式**: 必须以 `http://` 或 `https://` 开头  
- **模式选择**: 根据需求选择合适的模式
- **内存管理**: 大量数据时使用流式处理 (`stream: true`)
- **Schema 完整性**: 为 CSS 提取提供完整的 `name`、`baseSelector`、`fields` 结构

### ❌ 常见错误

**错误 1: 缺少嵌套参数**
```json
// ❌ 错误
{
  "mode": "scrape",
  "url": "https://example.com"
}

// ✅ 正确
{
  "mode": "scrape",
  "parameters": {
    "url": "https://example.com"
  }
}
```

**错误 2: URL 缺少协议**
```json
// ❌ 错误
{
  "mode": "scrape",
  "parameters": {
    "url": "example.com"
  }
}

// ✅ 正确
{
  "mode": "scrape",
  "parameters": {
    "url": "https://example.com"
  }
}
```

**错误 3: 错误的参数类型**
```json
// ❌ 错误 - urls 应该是数组
{
  "mode": "batch_crawl",
  "parameters": {
    "urls": "https://example.com"
  }
}

// ✅ 正确
{
  "mode": "batch_crawl",
  "parameters": {
    "urls": ["https://example.com"]
  }
}
```

**错误 4: extract模式使用错误的参数名**
```json
// ❌ 错误 - 应该使用 schema_definition
{
  "mode": "extract", 
  "parameters": {
    "url": "https://example.com",
    "schema": { // 错误！应该是 schema_definition
      "title": "string"
    }
  }
}

// ✅ 正确
{
  "mode": "extract",
  "parameters": {
    "url": "https://example.com", 
    "schema_definition": {
      "name": "Article",
      "baseSelector": ".content",
      "fields": [
        {
          "name": "title",
          "selector": "h1",
          "type": "text"
        }
      ]
    }
  }
}
```

## 🎪 高级使用技巧

### 1. 组合使用媒体捕获
```json
{
  "mode": "scrape",
  "parameters": {
    "url": "https://example.com",
    "include_links": true,
    "include_images": true,
    "return_screenshot": true,
    "return_pdf": true,
    "screenshot_quality": 90,
    "screenshot_max_width": 1200,
    "word_count_threshold": 15
  }
}
```

### 2. 智能深度爬取
```json
{
  "mode": "deep_crawl",
  "parameters": {
    "url": "https://docs.example.com",
    "strategy": "best_first",
    "keywords": ["API", "教程", "示例"],
    "max_depth": 3,
    "max_pages": 80
  }
}
```

### 3. 批量处理重要页面
```json
{
  "mode": "batch_crawl",
  "parameters": {
    "urls": [
      "https://example.com/home",
      "https://example.com/about", 
      "https://example.com/contact",
      "https://example.com/products"
    ],
    "concurrent_limit": 4
  }
}
```

### 4. 智能内容提取
```json
{
  "mode": "extract",
  "parameters": {
    "url": "https://news.example.com/article",
    "schema_definition": {
      "name": "NewsArticle",
      "baseSelector": ".article-container",
      "fields": [
        {
          "name": "headline",
          "selector": "h1.news-title",
          "type": "text"
        },
        {
          "name": "author",
          "selector": ".author-name",
          "type": "text"
        },
        {
          "name": "publish_date",
          "selector": ".publish-date",
          "type": "text"
        },
        {
          "name": "main_content",
          "selector": ".article-body",
          "type": "text"
        },
        {
          "name": "tags",
          "selector": ".tag",
          "type": "text",
          "multiple": true
        }
      ]
    },
    "extraction_type": "css"
  }
}
```

## 📝 最佳实践总结

1. **选择合适的模式**: 根据任务复杂度选择最简单有效的模式
2. **渐进式测试**: 从小规模开始测试，逐步扩大范围  
3. **资源管理**: 注意并发数和内存使用，避免过度请求
4. **错误处理**: 准备好处理网络错误和内容解析失败的情况
5. **合法使用**: 遵守网站的 robots.txt 和服务条款
6. **格式检查**: 每次调用前确认参数正确嵌套在 `parameters` 对象内
7. **参数验证**: 确保 URL 包含协议，数组参数正确格式
8. **命名规范**: extract模式必须使用 `schema_definition` 参数名
9. **内容控制**: 使用 `include_links` 和 `include_images` 控制输出内容
10. **质量优化**: 使用 `word_count_threshold` 过滤低质量内容块
11. **Schema 完整性**: 为 CSS 提取提供完整的 schema 结构以获得最佳结果
12. **信任智能分级**: 无需手动调整配置，工具会自动选择最佳方案
13. **注意模式变更**: 已移除 `crawl` 模式，请使用 `scrape` 或 `deep_crawl` 替代

## 🔄 版本更新说明

### 版本 1.2 主要更新
1. **新增智能分级系统**: 自动适应不同网站类型的配置策略
2. **增强反爬能力**: 改进浏览器指纹混淆和反检测机制
3. **内存管理优化**: 提升内存使用效率和稳定性
4. **错误处理改进**: 增强对 Context 错误的捕获和恢复
5. **移除 `crawl` 模式**: 简化模式选择，聚焦核心功能
6. **参数自动修复**: 增强对输入参数的容错能力

### 向后兼容性
- ✅ 所有现有调用格式保持兼容
- ✅ 智能分级系统对 Agent 完全透明
- ✅ 新增功能不影响现有功能
- ❌ 不再支持 `mode: "crawl"`，请使用替代模式