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"
}

智能分级抓取原理：

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

参数说明:

•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秒)，最大化兼容

🔄 常见工作流

新闻文章采集工作流

目标: 自动收集和分析新闻内容

•发现阶段: 使用 deep_crawl 发现相关文章链接
•采集阶段: 使用 batch_crawl 批量获取内容
•提取阶段: 使用 extract 结构化提取关键信息

竞品分析工作流

目标: 系统化分析竞争对手网站

•证据收集: 使用 screenshot 捕获竞品页面
•内容分析: 使用 scrape 获取详细内容
•文档保存: 使用 pdf_export 保存证据

产品目录爬取工作流

目标: 建立完整的产品数据库

•目录探索: 使用 deep_crawl 发现所有产品页面
•数据提取: 使用 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会自动使用更兼容的配置
•缓存问题: 配置缓存按域名存储，清除浏览器实例会重置缓存

调试技巧

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

⚠️ 重要提示

✅ 正确做法

•参数嵌套: 所有参数必须放在 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"
  }
}

📝 最佳实践总结

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

🔄 版本更新说明

版本 1.2 主要更新

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

向后兼容性

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

Crawl4AI 网页抓取工具指南

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

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

✅ 正确的基础调用模式

🚀 新增智能分级系统

📋 可用模式快速选择指南

🎯 使用场景快速指南

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

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

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

场景4：提取结构化数据

场景5：保存网页证据

🚀 详细模式说明

1. 抓取单个网页 (scrape)

2. 深度网站爬取 (deep_crawl)

3. 批量 URL 处理 (batch_crawl)

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

📋 Schema Definition 结构说明

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

LLM 提取模式 schema 结构：

5. PDF 导出 (pdf_export)

6. 截图捕获 (screenshot)

🛡️ 增强的反爬能力

浏览器指纹混淆

高级浏览器参数

智能等待策略

🔄 常见工作流

新闻文章采集工作流

竞品分析工作流

产品目录爬取工作流

🛠️ 故障排除

常见问题与解决方案

性能问题

内容质量问题

网络问题

Extract 模式特定问题

智能分级系统问题

调试技巧

⚠️ 重要提示

✅ 正确做法

❌ 常见错误

🎪 高级使用技巧

1. 组合使用媒体捕获

2. 智能深度爬取

3. 批量处理重要页面

4. 智能内容提取

📝 最佳实践总结

🔄 版本更新说明

版本 1.2 主要更新

向后兼容性

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

2. 深度网站爬取 (`deep_crawl`)

3. 批量 URL 处理 (`batch_crawl`)

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

5. PDF 导出 (`pdf_export`)

6. 截图捕获 (`screenshot`)