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 的调用都必须严格遵循以下嵌套结构！ 这是一个通用规则，适用于所有模式。

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

智能分级抓取原理：

自动识别：工具会分析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 过滤。

✅ 正确示例:

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

参数说明:

url (必需): 要导出为 PDF 的网页 URL
return_as_base64: 是否返回 base64 编码，默认 true

6. 截图捕获 (`screenshot`)

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

✅ 正确示例:

{
  "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: 缺少嵌套参数

// ❌ 错误
{
  "mode": "scrape",
  "url": "https://example.com"
}

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

错误 2: URL 缺少协议

// ❌ 错误
{
  "mode": "scrape",
  "parameters": {
    "url": "example.com"
  }
}

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

错误 3: 错误的参数类型

// ❌ 错误 - urls 应该是数组
{
  "mode": "batch_crawl",
  "parameters": {
    "urls": "https://example.com"
  }
}

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

错误 4: extract模式使用错误的参数名

// ❌ 错误 - 应该使用 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. 组合使用媒体捕获

{
  "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. 智能深度爬取

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

3. 批量处理重要页面

{
  "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. 智能内容提取

{
  "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"，请使用替代模式

Install Skill

SKILL.md

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`)