MediaCrawler 环境搭建与使用指南：基于 uv 的依赖管理、命令行运行与数据存储配置

本篇指南覆盖 MediaCrawler 从环境准备到首次跑通爬虫的完整路径：如何用 uv 同步 Python 依赖并安装 Playwright 浏览器驱动、如何通过 main.py 的命令行参数指定平台 / 登录方式 / 爬取类型启动采集任务、以及如何选择 CSV、JSON、SQLite、MySQL 等数据存储方案。读完本文，你可以独立完成本地环境初始化、理解 config/base_config.py 中各功能开关的作用，并根据 cmd_arg/arg.py 的参数定义正确构造任意平台的采集命令。

一、环境准备：uv 为推荐方案

1.1 前置依赖

MediaCrawler 的依赖基于 Python 3.11 构建，pyproject.toml 中声明了 requires-python = ">=3.11"。使用 uv 作为推荐的前置条件如下：

• 安装 uv：安装完成后用 uv --version 验证；
• Python 版本：建议使用 3.11，当前依赖基于该版本构建；
• Node.js：抖音（dy）、知乎（zhihu）平台的签名逻辑需要 Node.js 支持，版本需 >= 16.0.0。

1.2 同步 Python 依赖

# 进入项目根目录
cd MediaCrawler

# 使用 uv 保证 Python 版本和依赖一致性
uv sync

uv sync 会依据 pyproject.toml 创建隔离的虚拟环境并锁定依赖版本。当前依赖列表包含 playwright>=1.61.0、typer>=0.12.3、sqlalchemy>=2.0.43、aiosqlite、asyncmy（MySQL 异步驱动）、asyncpg（PostgreSQL 驱动）、motor（MongoDB）等，覆盖了全部 7 个平台客户端与 8 种存储后端所需的库。值得注意的是，该文件通过 [[tool.uv.index]] 配置了国内镜像源作为默认 PyPI 索引，可显著加速依赖下载。

1.3 安装 Playwright 浏览器驱动

uv run playwright install

MediaCrawler 的登录态获取、签名执行、页面交互均依赖 Playwright 驱动的浏览器环境。

项目已支持使用 Playwright 连接本地 Chrome。如需使用 CDP 方式，可在 config/base_config.py 中调整 xhs 和 dy 的相关配置。

从源码结构看，CDP 模式由一组集中配置控制，config/base_config.py 中的关键开关包括：

配置项	默认值	作用
ENABLE_CDP_MODE	True	启用 CDP 模式，使用用户本地 Chrome/Edge 浏览器进行爬取，具有更好的反检测能力
CDP_DEBUG_PORT	9222	CDP 调试端口，端口被占用时系统会自动尝试下一个可用端口
CUSTOM_BROWSER_PATH	""	自定义浏览器路径，为空时自动检测 Chrome/Edge 安装路径
CDP_HEADLESS	False	CDP 模式下的无头模式（注意：某些反检测功能在无头模式下可能无法正常工作）
CDP_CONNECT_EXISTING	True	连接用户已打开的浏览器而非启动新浏览器，反检测效果最好
AUTO_CLOSE_BROWSER	True	程序结束时是否自动关闭浏览器，设为 False 便于调试
BROWSER_LAUNCH_TIMEOUT	60	浏览器启动超时时间（秒）

CDP 模式在 main.py 的 async_cleanup() 中也有对应体现：程序退出时会优先清理 crawler.cdp_manager 资源，其次关闭 browser_context，并对"已关闭/已断开"类异常做了静默处理。更完整的 CDP 使用方式可参阅 CDP模式使用指南。

二、运行爬虫程序：命令行参数全解

2.1 基础运行命令

# 项目默认未开启评论爬取，如需评论请在 config/base_config.py 中修改 ENABLE_GET_COMMENTS
# 其他功能开关也可在 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

# 使用 SQLite 数据库存储数据（推荐个人用户使用）
uv run main.py --platform xhs --lt qrcode --type search --save_data_option sqlite

# 使用 MySQL 数据库存储数据
uv run main.py --platform xhs --lt qrcode --type search --save_data_option db

# 其他平台示例
uv run main.py --help

2.2 命令行参数如何生效

main.py 的执行链路是：main() 先调用 cmd_arg/arg.py 的 parse_cmd() 解析参数，若指定了 --init_db 则调用 db.init_db() 完成建表后直接退出；否则由 CrawlerFactory.create_crawler() 按 config.PLATFORM 实例化对应平台爬虫并执行 crawler.start()。

从源码看，参数解析基于 Typer 实现，所有 CLI 参数都以 config/ 包中的全局配置为默认值，解析完成后回写覆盖全局 config（如 config.PLATFORM = platform.value）。这意味着"改配置文件"和"传命令行参数"两种方式是等价的，命令行参数优先级更高。

完整参数清单（取值范围来自 cmd_arg/arg.py 中的枚举定义与 help 文本）：

参数	取值 / 说明	面板分组
--platform	xhs 小红书 | dy 抖音 | ks 快手 | bili B 站 | wb 微博 | tieba 百度贴吧 | zhihu 知乎	基础配置
--type	search 关键词搜索 | detail 指定帖子详情 | creator 创作者主页数据	基础配置
--lt	qrcode 扫码 | phone 手机号 | cookie Cookie 登录	账户配置
--keywords	搜索关键词，多个用逗号分隔	基础配置
--start	起始页码，默认 1	基础配置
--specified_id	detail 模式下的帖子/视频 ID 列表，逗号分隔（支持完整 URL 或纯 ID）	基础配置
--creator_id	creator 模式下的创作者 ID 列表，逗号分隔（支持完整 URL 或 ID）	基础配置
--crawler_max_notes_count	爬取的最大帖子/视频数量	基础配置
--get_comment	是否爬取一级评论，支持 yes/true/t/y/1 或 no/false/f/n/0	评论配置
--get_sub_comment	是否爬取二级评论，取值同上	评论配置
--max_comments_count_singlenotes	单条帖子/视频爬取的一级评论上限	评论配置
--headless	是否开启无头模式（对 Playwright 和 CDP 均生效），取值同上	运行配置
--max_concurrency_num	并发爬虫最大数量	性能配置
--save_data_option	csv | db(MySQL) | json | jsonl | sqlite | mongodb | excel | postgres	存储配置
--save_data_path	数据保存路径，默认空即保存到 data/ 目录	存储配置
--init_db	初始化数据库表结构，取值 sqlite | mysql | postgres，使用时无需携带其他可选参数	存储配置
--cookies	Cookie 登录方式所用的 Cookie 值	账户配置
--enable_ip_proxy	是否启用 IP 代理，取值同布尔开关	代理配置
--ip_proxy_pool_count	IP 代理池数量	代理配置
--ip_proxy_provider_name	代理服务商：kuaidaili | wandouhttp | static	代理配置
--static_proxy_url	静态代理地址，形如 http://user:password@host:port	代理配置

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

1. 配置值容错：_coerce_enum() 会把配置文件中的非法枚举值安全回退到默认值并打印黄色警告，而不是直接崩溃；
2. --init_db 裸参数兼容：_inject_init_db_default() 会检测裸写的 --init_db（不带取值），自动补上 sqlite 默认值以兼容历史用法；
3. 平台相关 ID 列表注入：--specified_id 解析后按平台写入不同配置项（如 XHS_SPECIFIED_NOTE_URL_LIST、DY_SPECIFIED_ID_LIST 等）；贴吧 ID 还会经过 _normalize_tieba_note_id() 归一化，既接受 /p/<id> 形式的 URL 也接受纯线程 ID。

2.3 配置文件中需要配合修改的项

命令只决定"怎么跑"，而"用什么关键词、多少条"由配置决定。以下开关集中在 config/base_config.py：

配置项	默认值	说明
KEYWORDS	"编程副业,编程兼职"	--type search 时的搜索关键词，英文逗号分隔
CRAWLER_MAX_NOTES_COUNT	15	爬取的帖子/视频数量上限
ENABLE_GET_COMMENTS	True	是否爬取评论（文档提示项目默认未开启评论爬取时，以此项为准）
ENABLE_GET_SUB_COMMENTS	False	是否爬取二级评论
CRAWLER_MAX_COMMENTS_COUNT_SINGLENOTES	10	单帖一级评论数量上限
HEADLESS	False	是否无头运行；若小红书扫码登录持续失败，建议打开浏览器手动通过滑动验证
SAVE_DATA_OPTION	"jsonl"	数据存储方式（可被命令行 --save_data_option 覆盖）
SAVE_DATA_PATH	""	保存路径，为空则存入 data/ 目录
START_PAGE	1	起始页码
MAX_CONCURRENCY_NUM	1	并发爬虫数

各平台还有专属配置：小红书平台的 SORT_TYPE（排序方式）与 XHS_SPECIFIED_NOTE_URL_LIST（笔记 URL 需携带 xsec_token 参数）定义在 config/xhs_config.py；抖音平台的 DY_SPECIFIED_ID_LIST 支持完整视频 URL、modal_id 形式 URL、短链接、纯视频 ID 等多种格式，定义在 config/dy_config.py。

三、数据存储：8 种后端与初始化流程

3.1 存储方式总览

项目支持多种数据存储方式：

• CSV 文件：保存至 CSV（位于 data/ 目录下）
• JSON 文件：保存至 JSON（位于 data/ 目录下）
• JSONL 文件：默认格式（SAVE_DATA_OPTION = "jsonl"），每行一个 JSON 对象，追加写入性能好
• Excel 文件：支持多工作表（内容、评论、创作者）与格式化输出
• 数据库存储：
  • 使用 --init_db 参数进行数据库初始化（使用 --init_db 时，无需其他可选参数）
  • SQLite：轻量级数据库，无需服务器，适合个人使用（推荐）。初始化 --init_db sqlite，存储 --save_data_option sqlite
  • MySQL：需提前创建数据库。初始化 --init_db mysql，存储 --save_data_option db（db 参数为兼容历史更新保留）
  • PostgreSQL：初始化 --init_db postgres，存储 --save_data_option postgres
  • MongoDB：--save_data_option mongodb，存储基类见 database/mongodb_store_base.py

完整参数取值来自 cmd_arg/arg.py 中的 SaveDataOptionEnum（csv、db、json、jsonl、sqlite、mongodb、excel、postgres）。各后端的典型命令示例（源自 docs/data_storage_guide.md）：

# 使用 Excel 存储数据
uv run main.py --platform xhs --lt qrcode --type search --save_data_option excel

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

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

# 初始化 PostgreSQL 数据库
uv run main.py --init_db postgres
# 使用 PostgreSQL 存储数据
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

3.2 建表机制：显式初始化与自动建表

从源码看，--init_db 的处理逻辑在 main.py 的 main() 中：

args = await cmd_arg.parse_cmd()
if args.init_db:
    await db.init_db(args.init_db)
    print(f"Database {args.init_db} initialized successfully.")
    return

# 数据库保存模式下自动建表，避免首次运行时出现 no such table 错误
if config.SAVE_DATA_OPTION in ("sqlite", "mysql", "db", "postgres"):
    await db.init_db(config.SAVE_DATA_OPTION)

两个要点：

1. --init_db 是"只建表、不爬取"的独立操作，执行后直接 return；建表实现是 database/db.py 中的 init_table_schema() → database/db_session.py 的 create_tables()，依据 ORM 模型（database/models.py）自动建表；
2. 即使不显式初始化，只要存储选项是数据库模式，main() 也会在爬取前自动建表，规避首次运行出现 no such table 的问题。因此文档中"使用 --init_db 时无需其他可选参数"的建议，是为了让初始化动作与爬取动作解耦，便于排查建表失败。

程序收尾时，async_cleanup() 会对 db/sqlite 存储模式执行 db.close() 释放数据库连接；Excel 模式则通过 _flush_excel_if_needed() 统一落盘，并打印 [Main] Excel files saved successfully；JSON/JSONL 模式在开启 ENABLE_GET_WORDCLOUD 时还会通过 AsyncFileWriter.generate_wordcloud_from_comments() 生成评论词云（停用词表与中文字体路径分别指向 docs/hit_stopwords.txt 与 docs/STZHONGS.TTF）。

3.3 存储方案选型建议

• 个人快速验证：JSONL（默认）或 CSV，零配置，直接落在 data/ 目录；
• 本地长期积累：SQLite，单文件数据库 + 具备去重能力，适合个人使用；
• 团队协作/生产环境：MySQL 或 PostgreSQL，可结合 database/db_config.py 配置连接信息；
• 数据分析场景：Excel 多工作表导出，详细格式说明见 docs/excel_export_guide.md。

四、备选方案：Python 原生 venv（不推荐）

如果爬取抖音或知乎，需要提前安装 Node.js，版本 >= 16。

# 进入项目根目录
cd MediaCrawler

# 创建虚拟环境（示例 Python 版本：3.11，requirements 基于该版本）
python -m venv venv

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

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

# 安装依赖与驱动
pip install -r requirements.txt
playwright install

# 运行爬虫程序（venv 环境）
python main.py --platform xhs --lt qrcode --type search
python main.py --platform xhs --lt qrcode --type detail
python main.py --platform xhs --lt qrcode --type search --save_data_option sqlite
python main.py --platform xhs --lt qrcode --type search --save_data_option db
python main.py --help

venv 方案依赖 requirements.txt 固定版本清单，而 uv 方案依赖 pyproject.toml 的声明式元数据加 uv.lock 锁文件，后者能保证跨机器环境完全一致，这也是文档将 uv 列为首选的原因。

五、使用边界与免责声明

免责声明： 请以学习为目的使用本仓库。本项目的所有内容仅供学习和参考之用，禁止用于商业用途。任何人或组织不得将本仓库的内容用于非法用途或侵犯他人合法权益；所涉及的爬虫技术仅用于学习和研究，不得用于对平台进行大规模爬取或其他非法行为。对于因使用本仓库内容而引起的任何法律责任，本仓库不承担任何责任。使用本仓库的内容即表示您同意本免责声明的所有条款和条件。

代码头文件（如 cmd_arg/arg.py 顶部注释）同样声明了使用原则：遵守目标平台使用条款与 robots.txt、不进行大规模爬取、合理控制请求频率。配置中的 CRAWLER_MAX_SLEEP_SEC（默认 2 秒）与 MAX_CONCURRENCY_NUM（默认 1）即为对请求节奏的基础约束，实际使用时建议保持保守取值。