MediaCrawler

一、项目简介：什么是 MediaCrawler？

MediaCrawler 是由 NanmiCoder 开发维护的一款多平台自媒体数据采集工具，支持小红书、抖音、快手、B站、微博、百度贴吧、知乎七大主流平台的公开信息抓取。截至2026年8月，该项目在 GitHub 上已获得超过 58,000 Stars 和 11,500+ Forks，是中文社交媒体爬虫领域最具影响力的开源项目之一。

该项目最核心的设计理念是：用真实浏览器代替复杂的 JS 逆向。MediaCrawler 基于 Playwright 浏览器自动化框架，通过复用真实浏览器的登录态和 Cookie，以 CDP（Chrome DevTools Protocol）模式连接用户已有的 Chrome 浏览器，大幅降低了爬虫开发的技术门槛。正如其 README 所言——“无需逆向复杂的加密算法，大幅降低技术门槛”。

官方资源：

• GitHub 仓库：https://github.com/NanmiCoder/MediaCrawler
• 项目官网：https://nanmicoder.github.io/MediaCrawler/

⚠️ 重要声明：本项目仅供学习和研究使用，禁止用于商业用途或侵犯他人合法权益。使用前请仔细阅读项目免责声明。

二、功能特性一览

2.1 多平台全覆盖

MediaCrawler 对七个主流平台的支持涵盖了以下核心功能：

2.2 核心技术架构

MediaCrawler 采用模块化架构设计，主要包含五大功能模块：

• 平台适配器（media_platform/）：各社交平台专用爬虫实现
• 代理管理系统（proxy/）：IP池构建与动态调度
• 数据存储引擎（store/）：多类型数据库适配
• 工具函数库（tools/）：验证码处理、时间工具等辅助功能
• 配置中心（config/）：环境变量与参数管理

2.3 MediaCrawler Pro

项目还推出了MediaCrawler Pro付费版本，相较于开源版本的核心优势包括：

• 自媒体内容拆解 Agent
• 断点续爬功能
• 多账号 + IP代理池支持
• 去除 Playwright 依赖，使用更简单
• 完整 Linux 环境支持
• AI Agent Skill 支持（OpenClaw / Claude Code / Cursor 一键安装）

三、使用教程：从零开始搭建

3.1 前置依赖

在开始之前，请确保您的系统满足以下要求：

3.2 安装步骤

第一步：克隆项目

git clone https://github.com/NanmiCoder/MediaCrawler.git
cd MediaCrawler

第二步：安装 uv 包管理器（推荐）

uv 是 MediaCrawler 推荐的依赖管理工具，安装地址：https://docs.astral.sh/uv/getting-started/installation

# 验证 uv 是否安装成功
uv --version

第三步：安装项目依赖

uv sync

如果使用传统的 pip 方式：

pip3 install -r requirements.txt

第四步：安装 Playwright 浏览器驱动

playwright install
# 或仅安装 Chromium
playwright install chromium

第五步：配置 Chrome CDP 模式（关键步骤）

MediaCrawler 默认使用 CDP 模式连接用户已有的 Chrome 浏览器。需要先启动 Chrome 并开启远程调试：

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

# Linux
google-chrome --remote-debugging-port=9222

3.3 首次运行

验证安装是否成功：

# 查看帮助信息
python3 main.py --help

# 示例：小红书关键词搜索（二维码登录）
python3 main.py --platform xhs --lt qrcode --type search --keyword "数据分析" --page 1

命令行参数说明：

• --platform：平台代码（xhs/douyin/kuaishou/bilibili/weibo/tieba/zhihu）
• --lt：登录方式（qrcode/cookie/phone）
• --type：采集类型（search/creator/detail）
• --keyword：搜索关键词
• --page：爬取页数

3.4 配置详解

数据存储配置：

MediaCrawler 默认数据保存格式为 JSONL。如需导出为 Excel，可在 config/base_config.py 中修改：

SAVE_DATA_OPTION = "excel"

或启动时添加参数：

python3 main.py --platform xhs --lt qrcode --type search --save_data_option excel

数据库配置：

项目支持 MySQL、PostgreSQL、MongoDB、Redis 等多种数据库，配置文件位于 config/db_config.py。

代理池配置：

代理系统采用三层架构，通过 Redis 维护 IP 生命周期。需在 proxy/proxy_ip_provider.py 中配置 API 密钥。

3.5 新手推荐流程

建议按照以下顺序逐步验证：

1. 先选一个平台（小红书、B站、微博、贴吧或知乎），不要同时开启多个平台
2. 选一个低风险关键词或公开内容 ID，限制采集量
3. 只开启必要功能，先验证能否拿到主内容
4. 确认主内容稳定后，再开启评论采集
5. 确认一级评论稳定后，再开启二级评论
6. 确认本机网络可跑通后，再评估是否需要代理
7. 确认输出字段满足分析需求后，再接数据库

四、实用建议与避坑指南

4.1 常见问题及解决方案

问题1：Playwright browser not found

# 解决方案：重新安装 Playwright 浏览器驱动
playwright install

问题2：小红书扫码后提示“无登陆信息”

这通常是由滑块验证码触发的风控导致。解决方案：

• 关闭无头模式：CDP_HEADLESS = False
• 降低爬取速度
• 在非 headless 模式下完成滑块验证

问题3：数据保存为 JSONL 而非 Excel

修改 config/base_config.py 中的 SAVE_DATA_OPTION 为 "excel"。

问题4：采集过程中频繁出现 403 错误

• 检查代理 IP 是否可用
• 降低请求频率
• 检查 Cookie 是否过期
• 尝试切换登录方式

4.2 风控规避建议

1. 使用测试账号：CDP 模式会复用 Chrome 的 Cookie 和账号状态，建议使用独立的测试账号和浏览器用户配置
2. 控制采集频率：避免短时间内发送大量相同模式的请求
3. 关闭无头模式调试：在测试阶段建议关闭 headless 模式，以便观察和完成验证码
4. 逐步扩大范围：单任务稳定后再考虑多账号、断点续爬和 IP 代理池

4.3 学习建议

MediaCrawler 的价值不仅在于“能爬数据”，更在于其工程化设计思路。它展示了一种“业务逻辑/平台适配层/数据存储”三层解耦架构，对于想学习爬虫框架设计的开发者来说是极佳的参考源码。

对于初学者，建议：

• 先通读项目的 README 和文档
• 从单个平台、单个关键词的小规模采集开始
• 遇到问题先在 GitHub Issues 中搜索（已有大量踩坑记录）
• 理解 CDP 模式的工作原理，这是项目最核心的设计决策

五、总结

MediaCrawler 是目前中文社交媒体爬虫领域的事实标准（reference implementation）。它用 Playwright + CDP 模式绕开了复杂的 JS 逆向，将七个主流平台的数据采集统一到了一个框架之下。无论你是数据分析师需要获取社媒样本，还是开发者想学习爬虫架构设计，MediaCrawler 都是一个值得投入时间研究的项目。

最后再次提醒：请以学习为目的使用，尊重各平台的使用条款和用户隐私。