MediaCrawler 是一个功能强大的多平台自媒体数据采集工具 ，支持小红书、抖音、快手、B站、微博、贴吧、知乎等主流平台的公开信息抓取。其核心技术基于 Playwright 浏览器自动化框架，通过保留登录态的浏览器上下文获取数据，无需逆向复杂的加密算法，大幅降低了技术门槛。

本教程将指导您完成从环境准备到成功运行爬虫的全过程。

1. 系统要求与前置依赖

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

  • 操作系统：Windows、macOS 或 Linux。
  • Python 版本：3.11 或更高版本（推荐）。
  • Node.js 版本：>= 16.0.0（抖音和知乎平台爬取必需）。
  • Chrome 浏览器：最新版本（>= 144），用于 CDP 模式（推荐）。

1.1 安装 uv 包管理器（推荐）

uv 是目前最快的 Python 包管理工具之一，能显著加速依赖安装和环境管理。

1
2
3
4
5
6
7
8
# macOS & Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 验证安装
uv --version

1.2 安装 Node.js

项目依赖 Node.js 环境，请前往 Node.js 官网 下载并安装 LTS 版本。

1
2
3
# 验证安装
node --version
npm --version

2. 项目安装与依赖配置

2.1 克隆项目

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

2.2 使用 uv 安装 Python 依赖（推荐）

uv sync 命令会根据 pyproject.toml 和 uv.lock 自动创建虚拟环境并安装所有依赖。

1
uv sync

2.3 传统 venv 方式（备选）

如果希望使用传统的 venv 和 pip：

1
2
3
4
5
6
7
8
9
10
11
# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# macOS/Linux:
source venv/bin/activate
# Windows:
venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

2.4 安装 Playwright 浏览器驱动（可选）

注意：如果使用默认的 CDP 模式（连接已有 Chrome 浏览器），无需安装此驱动。仅当您在 config/base_config.py 中设置 ENABLE_CDP_MODE = False，切换到标准 Playwright 模式时才需要安装。

1
2
3
4
5
# 使用 uv
uv run playwright install

# 或使用 venv
playwright install

3. Chrome 浏览器配置（推荐 CDP 模式）

项目默认使用 CDP 模式（Chrome DevTools Protocol）连接您已有的 Chrome 浏览器，这样可以复用浏览器的登录状态、Cookie 和扩展，大幅降低被平台风控检测的风险。

配置步骤

  1. 安装最新版 Chrome 浏览器（版本 >= 144）：下载地址
  2. 开启远程调试功能：
    • 在 Chrome 地址栏输入 chrome://inspect/#remote-debugging。
    • 勾选 “Allow remote debugging for this browser instance”。
    • 页面应显示 Server running at: 127.0.0.1:9222，表示调试端口已就绪。
  3. 运行爬虫：启动爬虫后，Chrome 浏览器会弹出确认对话框，点击 “接受” 即可。程序会等待用户确认（60秒超时）。

备选方案：如果您不想使用 CDP 模式，可以在 config/base_config.py 中设置 ENABLE_CDP_MODE = False，切换为标准 Playwright 模式（此时需确保已安装 Playwright 浏览器驱动）。

4. 配置爬虫参数

所有主要配置项集中在 config/base_config.py 文件中，包含详细的中文注释。

4.1 基础配置示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# config/base_config.py

# 是否开启评论爬取
ENABLE_GET_COMMENTS = True  # True: 爬取评论, False: 不爬取

# 数据保存格式
SAVE_DATA_OPTION = "json"  # 可选: csv, json, jsonl, excel, sqlite, mysql

# 是否使用 CDP 模式（连接已有 Chrome）
ENABLE_CDP_MODE = True  # True: 使用 CDP, False: 使用 Playwright

# 爬取数量限制
CRAWLER_MAX_COUNT = 50  # 最大爬取条数

# 关键词列表（用于 search 模式）
KEYWORDS = ["人工智能", "机器学习"]

4.2 数据存储配置

项目支持多种数据存储方式，包括 CSV、JSON、JSONL、Excel、SQLite 和 MySQL。详细配置请参考：数据存储指南。

5. 运行爬虫程序

5.1 命令行模式

项目通过 main.py 提供命令行接口。基本用法如下：

1
2
3
4
5
6
7
8
9
10
11
# 通用命令格式
uv run main.py --platform <平台> --lt <登录方式> --type <爬取类型>

# 示例1: 小红书 - 搜索关键词爬取（使用二维码登录）
uv run main.py --platform xhs --lt qrcode --type search

# 示例2: 抖音 - 指定帖子ID详情爬取（使用手机扫码登录）
uv run main.py --platform dy --lt qrcode --type detail

# 查看所有支持的平台和参数
uv run main.py --help

参数说明：

  • --platform：平台名称，如 xhs(小红书)、dy(抖音)、bili(B站)、weibo(微博)、tb(贴吧)、zh(知乎)。
  • --lt：登录方式，如 qrcode(扫码登录)、phone(手机号登录)。
  • --type：爬取类型，search(关键词搜索) 或 detail(指定帖子ID)。

5.2 WebUI 可视化界面

项目还提供了一个基于 Web 的可视化操作界面，无需命令行即可使用。

启动方式

开发调试模式（推荐）：

1
2
3
4
5
6
7
# 终端1: 启动后端 API 服务（默认端口 8080）
uv run uvicorn api.main:app --port 8080 --reload

# 终端2: 启动前端开发服务器
cd webui
npm install
npm run dev  # 默认在 5173 端口启动

启动成功后，访问 http://localhost:5173/ 即可打开 WebUI 界面。

生产模式（仅后端提供前端资源）：

1
2
3
4
5
6
7
8
9
# 1. 构建前端
cd webui
npm install
npm run build  # 产物输出到 api/webui/

# 2. 仅启动 API 服务器
uv run uvicorn api.main:app --port 8080 --reload

# 3. 访问 http://localhost:8080

WebUI 功能

  • 可视化配置爬虫参数（平台、登录方式、爬取类型等）。
  • 实时查看爬虫运行状态和日志。
  • 数据预览和导出。

6. 高级配置与优化

6.1 配置代理 IP 池

在 config/base_config.py 中配置代理，可降低 IP 被限制的风险：

1
2
3
4
5
6
7
8
9
10
11
12
13
# 启用代理
ENABLE_IP_PROXY = True

# 代理提供商（如：kuaidaili, zdaye）
IP_PROXY_PROVIDER_NAME = "kuaidaili"

# 代理配置（根据提供商填写）
PROXY_CONFIG = {
    "host": "your-proxy-host",
    "port": "your-proxy-port",
    "username": "your-username",
    "password": "your-password"
}

6.2 多账号支持（Pro 版本特性）

开源版本支持单账号登录态缓存。Pro 版本进一步支持多账号轮换和 IP 代理池，适合大规模采集场景。

7. 常见问题排查

问题 可能原因 解决方案
uv 命令未找到 uv 未正确安装 重新安装 uv 或使用 venv + pip 备选方案
ModuleNotFoundError Python 依赖未完整安装 运行 uv sync 或 pip install -r requirements.txt 重新安装
Chrome 连接失败 CDP 模式未正确开启 1. 确认 Chrome 已开启远程调试 (chrome://inspect)。2. 检查防火墙是否允许本地 9222 端口
登录二维码不显示 终端或网络问题 尝试切换登录方式 (--lt phone)，或检查网络是否能访问对应平台
数据爬取为 0 关键词无结果、或触发风控 1. 检查关键词是否有效。2. 更换代理 IP。3. 降低 CRAWLER_MAX_COUNT 值
抖音/知乎爬取失败 Node.js 未安装或版本过低 安装 Node.js >= 16.0.0，并确保其在系统 PATH 中

8. 免责声明与注意事项

⚠️ 重要提醒：本工具仅限用于学习和技术研究，严禁用于任何商业用途或侵犯他人合法权益的行为。使用者应严格遵守中华人民共和国相关法律法规，包括但不限于《网络安全法》。因不当使用而产生的所有法律责任由使用者自行承担。详细免责声明请查看项目 README 中的完整条款。

9. 总结

通过本教程，您应该已经成功部署并可以运行 MediaCrawler 了。该项目提供了一套相对完整的、无需深入逆向工程的自媒体数据采集方案。

核心优势在于：

  1. 技术门槛低：通过浏览器自动化而非逆向加密，易用性较好。
  2. 平台覆盖广：支持国内主流的社交媒体和内容平台。
  3. 使用方式灵活：既支持命令行，也提供了 WebUI 可视化界面。

部署完成后，建议您先尝试使用 --type search 搜索少量公开内容进行测试，熟悉流程后再进行更复杂的采集任务。如果在使用中遇到问题，可以查阅项目文档或提交 Issue。

项目地址：https://github.com/NanmiCoder/MediaCrawler