装好 Crawl4AI，跑通诊断，第一次把网页抓成 Markdown

第 1 步：建虚拟环境并安装

官方要求 Python 3.10 及以上（站内工具页与常见文档按 3.10 至 3.13 写；本课实测 3.13.5）。建议装在虚拟环境里，并锁定本课版本：

mkdir -p ~/crawl4ai-lab && cd ~/crawl4ai-lab
python3 -m venv .venv
source .venv/bin/activate
pip install crawl4ai==0.9.5
python -c "from crawl4ai.__version__ import __version__; print(__version__)"

对照结果：

0.9.5

可选地装「全家桶」依赖：pip install "crawl4ai[all]==0.9.5"。[all] 会带上 Torch、Transformers 等重量级包，磁盘和内存占用明显变大；本课只用核心功能，不装 [all]。

第 2 步：跑 setup 装好浏览器

安装完成后，官方要求再跑一次 setup，把 Playwright 浏览器和系统依赖补齐：

crawl4ai-setup

这一步会下载 Chromium（体积不小，需要能访问外网）。如果中途失败，按终端提示补系统库后重跑即可。本课测试机此前已经跑过 setup，浏览器可用，这里不再重复贴冗长日志。

第 3 步：用 crawl4ai-doctor 做健康检查

export CRAWL4AI_NO_CLOUD_NOTICE=1
crawl4ai-doctor

CRAWL4AI_NO_CLOUD_NOTICE=1 用来关掉终端里推广托管 Cloud 的提示，不影响抓取本身。对照结果（节选）：

[INIT].... → Running Crawl4AI health check...
[INIT].... → Crawl4AI 0.9.5
[TEST].... ℹ Testing crawling capabilities...
[EXPORT].. ℹ Exporting media (PDF/MHTML/screenshot) took 0.06s
[FETCH]... ↓ https://crawl4ai.com
| ✓ | ⏱: 1.26s
[SCRAPE].. ◆ https://crawl4ai.com
| ✓ | ⏱: 0.02s
[COMPLETE] ● https://crawl4ai.com
| ✓ | ⏱: 1.30s
[COMPLETE] ● ✅ Crawling test passed!

看到 Crawling test passed! 就说明本机浏览器、抓取和导出链路是通的。如果这里失败，先回到上一步重跑 crawl4ai-setup，再查官方 Installation 页的排错说明。

第 4 步：第一次 arun，抓 example.com

新建 first_crawl.py：

import asyncio
from crawl4ai import AsyncWebCrawler

async def main():
    async with AsyncWebCrawler() as crawler:
        result = await crawler.arun("https://example.com")
        print("SUCCESS", result.success)
        print("URL", result.url)
        md = result.markdown
        text = md.raw_markdown if hasattr(md, "raw_markdown") else str(md)
        print("MD_LEN", len(text))
        print(text[:280])
        print("...")
        print(text.splitlines()[-1])

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

运行：

export CRAWL4AI_NO_CLOUD_NOTICE=1
python first_crawl.py

对照结果（正文只保留英文首段、省略中间多语言段落，最后一行保留）：

SUCCESS True
URL https://example.com
MD_LEN 953
This domain is for use in documentation examples without needing permission. This is not a service; avoid relying on it for testing and monitoring purposes.
...
[Learn more](https://iana.org/help/example-domains)

读结果时注意三点：

1. result.success 为 True 表示抓取成功；失败时看 result.error_message。
2. result.markdown 在较新版本里常常是带 raw_markdown / fit_markdown 属性的对象，所以上面用 hasattr 兼容「字符串」和「对象」两种形态。
3. example.com 现在是多语言说明页，Markdown 里会有多段译文，末尾保留指向 IANA 的 Learn more 链接。

终端里还会夹几行 [FETCH] / [SCRAPE] / [COMPLETE] 进度日志，和 doctor 里看到的格式一样，属于正常输出。

第 5 步：用命令行再抓一次（可选核对）

同一个页面也可以不写 Python，直接用自带的 crwl：

crwl crawl https://example.com -o markdown -bc | head -n 2

对照结果：

This domain is for use in documentation examples without needing permission. This is not a service; avoid relying on it for testing and monitoring purposes.
هذا النطاق مُخصص للاستخدام في أمثلة التوثيق دون الحاجة إلى إذن. هذه ليست خدمة، يُرجى تجنب الاعتماد عليها لأغراض الاختبار والمراقبة.

-o markdown 只打印 Markdown；-bc 表示绕过缓存（bypass cache），保证拿到新鲜页面。官方文档里有时也写成 crwl https://example.com -o markdown（省略子命令 crawl），在 0.9.5 上两种写法都能跑。

小结

• 安装：pip install crawl4ai==0.9.5，再跑 crawl4ai-setup。
• 诊断：crawl4ai-doctor 通过后再写业务代码。
• 最短路径：async with AsyncWebCrawler() as crawler: 然后 await crawler.arun(url)。
• 读正文：优先取 result.markdown.raw_markdown；没有该属性时再退回 str(result.markdown)。
• 命令行核对：crwl crawl URL -o markdown -bc。