MediaCrawler 多平台自媒体爬虫：环境搭建、CDP 模式、命令行参数与数据存储全解析

本文基于 MediaCrawler 仓库的 README.md 及其配套文档与源码，系统讲解这个多平台自媒体数据采集工具的技术原理、完整安装流程、CDP 浏览器模式配置、全部命令行参数、核心配置项与各平台数据存储方案。读完本文，你可以独立完成从环境准备、登录态管理、参数化启动爬虫到数据落库/导出 Excel 的全流程操作，并理解每一步背后对应的源码实现。

一、项目定位与技术原理

MediaCrawler 是一个功能强大的多平台自媒体数据采集工具，支持小红书、抖音、快手、B 站、微博、贴吧、知乎等主流平台的公开信息抓取。根据 README.md 与 docs/项目架构文档.md 的说明，其核心设计有三点：

• 核心技术：基于 Playwright 浏览器自动化框架登录并保存登录态；
• 无需 JS 逆向：利用保留登录态的浏览器上下文环境，通过执行 JS 表达式的方式直接获取接口签名参数，从而避免逆向各平台复杂的加密算法，大幅降低技术门槛；
• 反检测能力：默认的 CDP 模式复用用户真实 Chrome/Edge 浏览器环境（Cookie、扩展、浏览历史），降低被平台风控检测的风险，并内置 IP 代理池机制。

功能特性矩阵

README 中给出的各平台能力支持情况如下（全部平台均支持关键词搜索、指定帖子 ID 爬取、二级评论、指定创作者主页、登录态缓存、IP 代理池与评论词云图）：

平台	关键词搜索	指定帖子ID爬取	二级评论	指定创作者主页	登录态缓存	IP代理池	生成评论词云图
小红书	✅	✅	✅	✅	✅	✅	✅
抖音	✅	✅	✅	✅	✅	✅	✅
快手	✅	✅	✅	✅	✅	✅	✅
B 站	✅	✅	✅	✅	✅	✅	✅
微博	✅	✅	✅	✅	✅	✅	✅
贴吧	✅	✅	✅	✅	✅	✅	✅
知乎	✅	✅	✅	✅	✅	✅	✅

平台与命令行代号的对应关系定义在 cmd_arg/arg.py 的 PlatformEnum 中：xhs（小红书）、dy（抖音）、ks（快手）、bili（B 站）、wb（微博）、tieba（百度贴吧）、zhihu（知乎）。

二、运行链路：从 main.py 到平台爬虫

理解 README 中"运行爬虫程序"命令背后的执行链路，有助于排查问题。整个流程集中在 main.py：

1. 参数解析：main() 调用 cmd_arg/arg.py 中的 parse_cmd()，使用 Typer 构建 CLI，解析后的命令行参数会直接覆盖 config 模块中的同名全局配置（见 cmd_arg/arg.py 的 "override global config" 段落），因此"命令行参数优先级高于配置文件"；
2. 数据库初始化：若携带 --init_db 参数则初始化对应数据库表结构后直接退出；若 SAVE_DATA_OPTION 为 sqlite/mysql/db/postgres，则自动建表以避免首次运行出现 no such table 错误（main.py）；
3. 工厂创建爬虫：CrawlerFactory.create_crawler() 依据平台代号从注册表中取出对应爬虫类（main.py），如 xhs -> XiaoHongShuCrawler、dy -> DouYinCrawler 等；
4. 执行爬取：调用 crawler.start()，爬取结束后若为 Excel 存储则统一 flush 落盘，若开启词云且存储格式为 json/jsonl 则基于评论生成词云图（main.py）。

每个平台爬虫都继承自 base/base_crawler.py 中的 AbstractCrawler 抽象基类，必须实现 start()、search() 与标准 Playwright 模式的 launch_browser()；基类还提供了一个可选的 launch_browser_with_cdp() 钩子，其默认实现回退到标准模式——各平台在需要时覆写该方法以接入 CDP 浏览器管理。

目录结构速览

结合 docs/项目架构文档.md 与仓库实际目录，核心模块职责如下：

目录	职责
config/	全局配置（base_config.py）与各平台专属配置（如 config/xhs_config.py）
media_platform/	七个平台的爬虫实现，每个平台包含 client.py（API 客户端）、core.py（爬取逻辑）、login.py（登录）、field.py（字段枚举）
store/	各平台数据落盘实现，另有 store/excel_store_base.py 提供 Excel 存储基类
database/	ORM 模型、数据库会话与 MongoDB 存储基类
proxy/	IP 代理池管理（proxy_ip_pool.py）与代理刷新混入（proxy_mixin.py）
tools/	CDP 浏览器管理（cdp_browser.py）、浏览器启动（browser_launcher.py）、异步文件写入（async_file_writer.py）等
webui/	基于 React + Vite 的可视化操作界面（前端），配合 api/ 后端
libs/	JS 脚本库，含反检测脚本 stealth.min.js 及各平台签名脚本

三、前置依赖与环境安装

3.1 安装 uv（推荐方式）

README 推荐以 uv 管理 Python 环境。安装后执行 uv --version 验证。推荐理由是 uv 速度快、依赖解析准确，可通过 uv sync 保证 Python 版本与依赖包的一致性。项目对 Python 版本的实际要求可从 pyproject.toml 确认：requires-python = ">=3.11"，且 pyproject.toml 中已配置 uv 默认使用清华镜像源加速安装。

3.2 安装 Node.js

项目依赖 Node.js（抖音、知乎等平台需要执行 JS 签名脚本，如 libs/douyin.js、libs/zhihu.js），README 要求版本 >= 16.0.0。

3.3 安装 Python 依赖

# 进入项目目录
cd MediaCrawler

# 使用 uv sync 命令来保证 python 版本和相关依赖包的一致性
uv sync

3.4 安装浏览器驱动（仅标准 Playwright 模式需要）

如果使用默认的 CDP 模式（连接已有 Chrome 浏览器），无需安装浏览器驱动。仅在使用标准 Playwright 模式时需要：

# 仅在标准 Playwright 模式下需要安装浏览器驱动
uv run playwright install

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

项目默认使用 CDP 模式连接用户已有的 Chrome 浏览器，可以复用浏览器已有的登录状态、Cookie、扩展等，大幅降低平台风控检测风险。使用前需要：

1. 安装最新版 Chrome 浏览器（版本 >= 144）；
2. 开启远程调试功能：在 Chrome 地址栏输入 chrome://inspect/#remote-debugging，勾选 "Allow remote debugging for this browser instance"；
3. 页面显示 Server running at: 127.0.0.1:9222 表示已就绪。

提示：运行爬虫后，Chrome 浏览器会弹出确认对话框，点击"接受"即可。程序会等待用户确认，60 秒内操作完成即可。

如果不想使用 CDP 模式，可以在 config/base_config.py 中设置 ENABLE_CDP_MODE = False 切换为标准 Playwright 模式。

四、CDP 模式：两种使用方式与完整配置项

CDP（Chrome DevTools Protocol）模式是 MediaCrawler 的核心反检测手段，详细指南见 docs/CDP模式使用指南.md。其优势在于：使用用户真实安装的浏览器（含扩展与个人设置）、浏览器指纹更真实、自动继承登录状态/Cookie/浏览历史、可利用用户安装的代理扩展等，行为模式更接近真实用户。

CDP 模式支持两种使用方式：

模式	说明	适用场景
连接已有浏览器（默认推荐）	连接用户正在使用的 Chrome 浏览器，复用真实的 Cookie、扩展和浏览历史	反检测要求高，需要最大程度降低风控风险
启动新浏览器	自动检测并启动一个新的 Chrome/Edge 浏览器实例	不需要复用浏览器状态的场景

• 方式一（连接已有浏览器）：即上文 3.5 节的流程，配置为 ENABLE_CDP_MODE = True + CDP_CONNECT_EXISTING = True，调试端口需与 chrome://inspect 页面显示的一致（默认 9222）；
• 方式二（启动新浏览器）：将 CDP_CONNECT_EXISTING 置为 False，程序自动检测并启动新的 Chrome/Edge 实例。

对应配置项及其默认值（均可在 config/base_config.py 中查看）：

配置项	类型	默认值	说明
ENABLE_CDP_MODE	bool	True	是否启用 CDP 模式
CDP_CONNECT_EXISTING	bool	True	是否连接已有浏览器（推荐开启）
CDP_DEBUG_PORT	int	9222	CDP 调试端口
CDP_HEADLESS	bool	False	CDP 模式下的无头模式（注意：部分反检测功能在无头模式下可能失效）
AUTO_CLOSE_BROWSER	bool	True	程序结束时是否关闭浏览器（置 False 可保留浏览器便于调试）
CUSTOM_BROWSER_PATH	str	""	自定义浏览器路径，为空时自动检测 Chrome/Edge 安装位置（仅"启动新浏览器"模式有效）
BROWSER_LAUNCH_TIMEOUT	int	60	浏览器启动/连接超时时间（秒）

支持的浏览器包括 Windows/macOS 上的 Google Chrome 与 Microsoft Edge（稳定版、Beta、Dev、Canary）以及 Linux 上的 Chrome/Chromium、Edge。CDP 浏览器管理的实现位于 tools/cdp_browser.py，浏览器路径检测逻辑位于 tools/browser_launcher.py。

五、命令行参数完整参考

所有命令行参数在 cmd_arg/arg.py 中通过 Typer 定义，默认值均取自 config 全局配置，解析后覆盖回 config 模块。完整参数如下：

参数	说明	默认值来源
--platform	平台选择：xhs/dy/ks/bili/wb/tieba/zhihu	config.PLATFORM
--lt	登录方式：qrcode（扫码）/phone（手机号）/cookie	config.LOGIN_TYPE
--type	爬取类型：search（关键词搜索）/detail（帖子详情）/creator（创作者主页）	config.CRAWLER_TYPE
--start	起始页码	config.START_PAGE（默认 1）
--keywords	搜索关键词，多个用英文逗号分隔	config.KEYWORDS
--get_comment	是否爬取一级评论，支持 yes/true/t/y/1 或 no/false/f/n/0	config.ENABLE_GET_COMMENTS
--get_sub_comment	是否爬取二级评论，取值同上	config.ENABLE_GET_SUB_COMMENTS
--headless	是否无头模式（同时作用于 Playwright 与 CDP），取值同上	config.HEADLESS
--save_data_option	存储方式：csv/db/json/jsonl/sqlite/mongodb/excel/postgres	config.SAVE_DATA_OPTION
--init_db	初始化数据库表结构：sqlite/mysql/postgres；单独使用时默认为 sqlite（cmd_arg/arg.py）	无
--cookies	Cookie 登录方式所用的 Cookie 值	config.COOKIES
--specified_id	detail 模式的帖子/视频 ID 列表，逗号分隔，支持完整 URL 或纯 ID	空
--creator_id	creator 模式的创作者 ID 列表，逗号分隔，支持完整 URL 或纯 ID	空
--max_comments_count_singlenotes	单条帖子/视频最多爬取的一级评论数	config.CRAWLER_MAX_COMMENTS_COUNT_SINGLENOTES（默认 10）
--crawler_max_notes_count	最多爬取的视频/帖子数	config.CRAWLER_MAX_NOTES_COUNT（默认 15）
--max_concurrency_num	最大并发爬虫数	config.MAX_CONCURRENCY_NUM（默认 1）
--save_data_path	数据保存路径，为空则保存到 data 目录	config.SAVE_DATA_PATH
--enable_ip_proxy	是否启用 IP 代理，取值同布尔参数	config.ENABLE_IP_PROXY
--ip_proxy_pool_count	IP 代理池数量	config.IP_PROXY_POOL_COUNT（默认 2）
--ip_proxy_provider_name	代理服务商：kuaidaili/wandouhttp/static	config.IP_PROXY_PROVIDER_NAME
--static_proxy_url	静态代理 URL，例如 http://user:password@host:port	config.STATIC_PROXY_URL

几个值得注意的实现细节：

• --specified_id 的平台映射：解析后按平台写入对应的配置列表，如 xhs -> XHS_SPECIFIED_NOTE_URL_LIST、dy -> DY_SPECIFIED_ID_LIST、bili -> BILI_SPECIFIED_ID_LIST 等（cmd_arg/arg.py）；
• 贴吧 ID 归一化：贴吧平台支持直接传 /p/<数字ID> 形式的 URL，内部会自动提取纯 ID；--creator_id 传纯数字时会自动拼接为 https://tieba.baidu.com/home/main?id=<id> 形式（cmd_arg/arg.py）；
• 非法枚举值兜底：若配置值不在枚举范围内，会打印黄色警告并回退到默认值，而不是直接崩溃（cmd_arg/arg.py）。

运行命令示例

# 在 config/base_config.py 查看配置项目功能，写的有中文注释

# 从配置文件中读取关键词搜索相关的帖子并爬取帖子信息与评论
uv run main.py --platform xhs --lt qrcode --type search

# 从配置文件中读取指定的帖子ID列表获取指定帖子的信息与评论信息
uv run main.py --platform xhs --lt qrcode --type detail

# 打开对应APP扫二维码登录

# 其他平台爬虫使用示例，执行下面的命令查看
uv run main.py --help

六、核心配置文件 base_config.py 详解

config/base_config.py 是全局配置的主体，按功能分组讲解：

6.1 基础配置

PLATFORM = "xhs"  # 平台: xhs | dy | ks | bili | wb | tieba | zhihu
XHS_INTERNATIONAL = False  # 是否使用海外版小红书 (rednote.com)，开启后 API 走 webapi.rednote.com
KEYWORDS = "编程副业,编程兼职"  # 关键词搜索配置，英文逗号分隔
LOGIN_TYPE = "qrcode"  # qrcode | phone | cookie
COOKIES = ""
CRAWLER_TYPE = "search"  # search (关键词搜索) | detail (帖子详情) | creator (创作者主页)

6.2 浏览器与登录态

HEADLESS = False          # True 为无头模式；小红书扫码失败或抖音需手机验证时，建议开浏览器手动过验证
SAVE_LOGIN_STATE = True   # 是否保存登录状态（登录态缓存的关键开关）
USER_DATA_DIR = "%s_user_data_dir"  # 浏览器文件缓存目录，%s 会被平台名替换

6.3 IP 代理池

ENABLE_IP_PROXY = False              # 是否启用 IP 代理
IP_PROXY_POOL_COUNT = 2              # 代理 IP 池数量
IP_PROXY_PROVIDER_NAME = "kuaidaili" # kuaidaili | wandouhttp | static
STATIC_PROXY_URL = ""                # 静态代理地址（provider 为 static 时生效）

代理池的实现位于 proxy/proxy_ip_pool.py，各服务商客户端在 proxy/providers/。当使用企业代理、Burp Suite、mitmproxy 等会注入自签名证书的中间人代理时，可将 DISABLE_SSL_VERIFY 设为 True（注意其带来的中间人攻击风险，见 config/base_config.py 的注释）。

6.4 数据保存与抓取控制

SAVE_DATA_OPTION = "jsonl"   # csv | db | json | jsonl | sqlite | excel | postgres
SAVE_DATA_PATH = ""          # 保存路径，为空则保存到 data 目录
START_PAGE = 1               # 起始页码
CRAWLER_MAX_NOTES_COUNT = 15      # 控制爬取的视频/帖子数量
MAX_CONCURRENCY_NUM = 1           # 并发爬虫数量
ENABLE_GET_MEIDAS = False         # 是否爬取媒体资源（图片/视频），默认关闭
ENABLE_GET_COMMENTS = True        # 是否爬取评论（README 提示：原生 venv 方式下需手动开启）
CRAWLER_MAX_COMMENTS_COUNT_SINGLENOTES = 10  # 单帖一级评论上限
ENABLE_GET_SUB_COMMENTS = False   # 是否爬取二级评论，默认关闭
CRAWLER_MAX_SLEEP_SEC = 2        # 爬取间隔（秒）

注意：README 在"原生 venv 方式"章节特别提醒——项目默认没有开启评论爬取模式（该说法对应旧版本行为），如需评论请在 config/base_config.py 中确认 ENABLE_GET_COMMENTS 为 True。

6.5 评论词云

ENABLE_GET_WORDCLOUD = False    # 是否生成评论词云
CUSTOM_WORDS = {
    "零几": "年份",              # 自定义词组: 词:所属分组
    "高频词": "专业术语",
}
STOP_WORDS_FILE = "./docs/hit_stopwords.txt"  # 停用词文件
FONT_PATH = "./docs/STZHONGS.TTF"             # 中文字体文件

从 main.py 的实现可以看到，词云生成仅在使用 json/jsonl 存储且开启 ENABLE_GET_WORDCLOUD 时，于爬取完成后执行。

6.6 平台专属配置

base_config.py 末尾通过 from .xxx_config import * 引入各平台配置（config/base_config.py）。以小红书为例，config/xhs_config.py 包含三项：

• SORT_TYPE：搜索结果排序方式，枚举值定义在 media_platform/xhs/field.py；
• XHS_SPECIFIED_NOTE_URL_LIST：detail 模式下指定的笔记 URL 列表，必须携带 xsec_token 参数；
• XHS_CREATOR_ID_LIST：creator 模式下指定的创作者主页 URL 列表，需携带 xsec_token 与 xsec_source 参数。

七、数据存储方案

MediaCrawler 支持 CSV、JSON、JSONL、Excel、SQLite、MySQL、PostgreSQL、MongoDB 等多种存储方式，详细指南见 docs/data_storage_guide.md。各方案的适用建议：

存储方式	特点	使用命令
CSV/JSON/JSONL 文件	保存到 data/ 目录；JSONL 为默认格式，每行一个 JSON 对象，追加写入性能好	--save_data_option csv / json / jsonl
Excel 文件	多工作表（内容、评论、创作者）、标题样式/自动列宽/边框等格式化	--save_data_option excel
SQLite	轻量级、无需服务器，适合个人使用（推荐）	先 --init_db sqlite，再 --save_data_option sqlite
MySQL	关系型数据库，需提前创建数据库（db 参数为兼容历史保留）	先 --init_db mysql，再 --save_data_option db
PostgreSQL	高级关系型数据库，推荐生产环境使用	先 --init_db postgres，再 --save_data_option postgres
MongoDB	NoSQL 文档存储	--save_data_option mongodb

命令示例（继承自 docs/data_storage_guide.md）：

# 使用 Excel 存储数据（推荐用于数据分析）
uv run main.py --platform xhs --lt qrcode --type search --save_data_option excel

# 初始化 SQLite 数据库，并使用 SQLite 存储数据
uv run main.py --init_db sqlite
uv run main.py --platform xhs --lt qrcode --type search --save_data_option sqlite

# 初始化 MySQL 数据库（db 参数为适配历史更新而沿用）
uv run main.py --init_db mysql
uv run main.py --platform xhs --lt qrcode --type search --save_data_option db

# 初始化 PostgreSQL 数据库并存储
uv run main.py --init_db postgres
uv run main.py --platform xhs --lt qrcode --type search --save_data_option postgres

# 使用 CSV / JSON / JSONL 存储数据
uv run main.py --platform xhs --lt qrcode --type search --save_data_option csv
uv run main.py --platform xhs --lt qrcode --type search --save_data_option json
uv run main.py --platform xhs --lt qrcode --type search --save_data_option jsonl

源码层面的佐证：--init_db 使用时无需携带其他可选参数，解析后会在 main.py 中完成建表即退出；而数据库类存储（sqlite/mysql/db/postgres）在每次运行时会自动建表（main.py）；Excel 数据则在程序退出前由 _flush_excel_if_needed() 统一 flush 落盘（main.py），其格式化实现位于 store/excel_store_base.py，Excel 导出细节另见 docs/excel_export_guide.md。

八、WebUI 可视化操作界面

MediaCrawler 提供了基于 Web 的可视化操作界面（前端位于 webui/，后端 API 位于 api/），无需命令行也能配置和运行爬虫。

开发调试（推荐）

开发时需要同时启动后端 API 服务和前端 Vite 开发服务器：

# 终端 1：启动 API 服务器（默认端口 8080）
uv run uvicorn api.main:app --port 8080 --reload

# 终端 2：启动前端开发服务器
cd webui
npm install
npm run dev        # 默认在 5173 端口启动，并代理 /api 到 8080

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

首次打开会进行环境检测（调用 /api/env/check），请确保后端服务已启动；如果检测失败，可点击「跳过检测」临时跳过。

构建生产资源

如果希望通过 API 服务器直接提供 WebUI 静态资源，需要先构建前端：

cd webui
npm install
npm run build      # 产物输出到 api/webui/

构建完成后，只需启动 API 服务器：

uv run uvicorn api.main:app --port 8080 --reload

然后访问 http://localhost:8080 即可。

WebUI 的功能特性包括：可视化配置爬虫参数（平台、登录方式、爬取类型等）、实时查看爬虫运行状态和日志（基于 WebSocket，见 api/routers/websocket.py）、数据预览和导出（前端组件位于 webui/src/components/data/）。

九、使用 Python 原生 venv 管理环境（备选方案）

如果不使用 uv，也可以走原生 venv 流程（README 标注为"不推荐"，因为 requirements.txt 基于 Python 3.11 编写，其他版本可能存在依赖兼容性问题）：

# 进入项目根目录
cd MediaCrawler

# 创建虚拟环境
python -m venv venv

# macOS & Linux 激活虚拟环境
source venv/bin/activate

# Windows 激活虚拟环境
venv\Scripts\activate

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

# 安装 playwright 浏览器驱动
playwright install

# 项目默认是没有开启评论爬取模式，如需评论请在 config/base_config.py 中的 ENABLE_GET_COMMENTS 变量修改
# 一些其他支持项，也可以在 config/base_config.py 查看功能，写的有中文注释

# 从配置文件中读取关键词搜索相关的帖子并爬取帖子信息与评论
python main.py --platform xhs --lt qrcode --type search

# 从配置文件中读取指定的帖子ID列表获取指定帖子的信息与评论信息
python main.py --platform xhs --lt qrcode --type detail

# 打开对应APP扫二维码登录

# 其他平台爬虫使用示例，执行下面的命令查看
python main.py --help

十、合规使用声明

最后需要强调 README 中的免责声明：本项目以学习和研究为目的，供技术交流使用。下载、安装和使用本项目时应严格遵守所在地相关法律法规与目标平台的使用条款；本项目严禁用于任何非法目的或非学习、非研究的商业行为，不得用于大规模爬取或对平台造成运营干扰，使用者应自行控制请求频率并承担相应法律责任。完整的免责声明条款见 README.md 末尾及根目录 LICENSE 文件。

---

小结：MediaCrawler 的设计思路可以概括为"配置驱动 + 工厂模式 + 抽象基类"——config/base_config.py 定义所有行为开关，命令行参数（cmd_arg/arg.py）可按需覆盖，CrawlerFactory（main.py）按平台代号路由到具体爬虫，AbstractCrawler（base/base_crawler.py）统一约束各平台实现。掌握"CDP 模式配置 + 命令行参数 + 存储方案"这三块，就掌握了 MediaCrawler 的日常使用与二次扩展能力。