Crawl4AI

Crawl4AI 快速入门：从一个网页得到可核对的 Markdown

这是什么？适合谁？

Crawl4AI 是面向 LLM、RAG 与数据管道的网页抓取工具。开源 Python 库通过浏览器访问页面，把页面转换为 Markdown，也提供 CSS、XPath 与 LLM 结构化提取策略。

适合需要把获准采集的文档站、产品说明或公开知识页面转换为检索材料的开发者。它解决的是“如何拿到可处理的页面内容”，不是替你判定内容真实、授权范围或采集是否合法。

这里主要介绍自己运行开源库的路径。官方另有自行托管的服务端和 Crawl4AI Cloud；三种部署方式的账户、费用、密钥与接口不能混为一谈。

核验日期为 2026-10-15。本文没有把 README 中的速度宣传当作独立测试成绩，也不承诺任何网站都能抓取成功。

准备工作

• 准备 Python 虚拟环境，兼容版本以当前包元数据与安装文档为准。
• 需要联网下载 Python 包和浏览器运行文件，并有本机安装权限。
• 选一个允许抓取、不含登录态和敏感信息的网页作为首个目标。
• 开源基础抓取与 Markdown 转换不要求 LLM API Key；选择模型提取时另行配置模型服务。
• 先确定输出保存目录，避免把完整网页、Cookie 或日志提交到代码仓库。

三步快速上手

第一步：隔离安装

python -m venv .venv

在 macOS/Linux 中激活：

source .venv/bin/activate

在 Windows PowerShell 中激活：

.venv\Scripts\Activate.ps1

安装库并准备浏览器：

python -m pip install -U crawl4ai
crawl4ai-setup
crawl4ai-doctor

setup 用于浏览器准备，doctor 用于检查安装。若脚本找不到，先确认当前终端确实使用刚创建的虚拟环境。

第二步：运行最小页面转换

把下面代码保存为 first_crawl.py。这是根据官方快速入门改写的教学示例，不是本站执行日志。

import asyncio
from pathlib import Path
from crawl4ai import AsyncWebCrawler

async def main():
    async with AsyncWebCrawler() as crawler:
        result = await crawler.arun(url="https://example.com")
        if not result.success:
            raise RuntimeError(result.error_message)
        markdown = str(result.markdown)
        Path("example.md").write_text(markdown, encoding="utf-8")
        print("已保存 example.md，请打开核对正文")

if __name__ == "__main__":
    asyncio.run(main())

运行：

python first_crawl.py

预期结果是在当前目录得到 example.md。成功判定还需打开文件，确认包含目标页面正文，而非错误提示、登录页或空白内容。

第三步：替换为获准采集的真实页面

只改脚本里的 URL，再运行一次。把浏览器可见标题、正文段落与输出逐段核对，尤其关注表格、导航、日期和链接。

第一个可交付任务可以限定为“一篇文档转 Markdown，保存原始 URL，并标出遗漏内容”。不要在尚未验证内容完整性时直接扩展到整个站点。

初级用法

1. 区分浏览器配置与抓取配置

BrowserConfig 管浏览器行为，CrawlerRunConfig 管本次抓取参数。分开配置有助于判断问题发生在浏览器启动、网络访问还是内容提取阶段。

2. 对照原始与过滤后的 Markdown

官方文档区分 result.markdown 与经过过滤的 fit_markdown。过滤能减少导航噪音，也可能删除短段落；关键日期或价格段落必须对照原页。

3. 用错误信息建立失败记录

保留目标 URL、运行时间和 error_message，不要把失败结果写成成功正文。如果返回的是验证页，即使 HTTP 成功也不能视为目标文章采集成功。

高级玩法

1. 用 CSS/XPath 处理稳定页面

当商品卡片或目录结构稳定时，优先研究 JsonCssExtractionStrategy 或 JsonXPathExtractionStrategy。先对单页手工确认选择器，再把结果接入数据管道。

这种路径不依赖模型猜字段，但依赖页面结构。网站改版后必须复查，不能因为 JSON 能解析就认为字段正确。

2. 为动态页面设置明确等待条件

对于 JavaScript 加载的页面，先确认目标元素何时出现，再配置抓取等待逻辑。不要简单把所有页面的等待时间拉长，也不要把抓取工具当作绕过访问控制的手段。

3. 扩展到多 URL 时控制并发

官方提供 arun_many 等批量能力。先用少量 URL 观察错误率和内存，再设置站点级速率上限；失败重试要有次数限制，避免持续压迫目标站。

五个小技巧

1. 先用普通静态页面确认环境，再测试复杂前端站点，区分环境问题与站点问题。
2. Markdown 与来源 URL 一起保存，后续检索结果才有回到原页的路径。
3. 对关键字段保留原文片段，而不是只保存模型提取的结论。
4. 为不同域名分别设置访问节奏，不要用一个全局高并发覆盖全部来源。
5. 变更过滤器后对照固定样本，检查是否把正文误删成只有标题。

常见踩坑

• 踩坑 1：装了包却启动不了浏览器。 包安装不等于浏览器准备完成；先执行 crawl4ai-setup 和 crawl4ai-doctor，按诊断结果处理系统依赖。
• 踩坑 2：脚本能运行却正文为空。 页面可能依赖 JavaScript、登录或验证；先在普通浏览器确认访问权限，再检查等待和提取条件。
• 踩坑 3：抓到了旧内容却以为是新页面。 核对缓存配置和原页日期；需要新鲜内容时按官方文档研究 CacheMode.BYPASS，而非依赖默认行为猜测。
• 踩坑 4：过滤器删除了关键短段落。 把原始 Markdown 与过滤输出对照，调整过滤策略；不要只看字符数减少就认为质量更好。
• 踩坑 5：把开源库的免费理解为模型免费。 LLM 提取、云服务、代理和服务器资源可能收费，基础 HTML 转换与这些支出需分别预算。
• 踩坑 6：把 JSON 合法当作内容真实。 模型提取可能漏字段或改写数字；为每个重要字段保留原文依据，不确定时标空而不是补猜。
• 踩坑 7：批量抓取失控。 先设 URL 范围、数量和并发边界，遇到拒绝访问及时停止；不要自动追随无限分页或任意外链。

权限、安全与成本边界

只采集你有权访问和保存的内容，并遵守目标站服务条款、robots 约束及适用法律。公开可见不自动意味着允许批量再分发。

登录 Cookie、持久化浏览器配置和请求头都可能包含凭据。使用专门测试账户，限制配置目录权限，不把它们作为普通日志分享。

基础开源库本机运行不等于任何提取方式都离线。选择外部 LLM 时，页面片段可能被发送给模型服务；切换到云抓取时，URL 与相关数据进入云端链路。

云套餐和额度会变化，本文不写死促销价格。先估算抓取页数、模型调用和代理成本，再决定是否使用托管服务。

常见问题 FAQ

Q1：不配置模型密钥能用吗？

A：基础网页抓取与 Markdown 转换可以；使用 LLM 提取策略时才需相应模型配置和费用预算。

Q2：能保证所有 JavaScript 网页都成功吗？

A：不能。权限、反自动化措施、页面状态和等待条件都会影响结果，工具能力不等于访问授权。

Q3：已经有 Requests，为什么还考虑它？

A：当你需要浏览器渲染和面向模型的 Markdown 管道时可以评估；简单静态请求未必需要启动浏览器。

Q4：能直接把输出全部塞进知识库吗？

A：建议先去重、记录来源并检查正文完整性；错误页和过期内容进入索引会影响后续回答。

Q5：是否必须使用 Cloud？

A：不必。开源库、自己托管的服务与官方 Cloud 是不同部署选择，应按运维能力与数据边界决定。

局限与声明

本文基于公开资料整理，未进行浏览器安装、站点兼容性、吞吐或安全的独立实测。示例代码是可供读者执行的教学路径，不是已经跑通的本站测试记录；平台依赖和接口以当前官方文档为准。

参考链接

• Crawl4AI 官方网站
• 官方安装与部署说明
• 官方快速入门
• 快速入门文档源码