MediaCrawler 原生环境管理实战：基于 uv 与 Python venv 的依赖同步、浏览器驱动安装与爬虫运行指南

本篇技术指南基于 MediaCrawler 仓库的 原生环境管理文档，系统讲解如何在本地从零搭建该多平台爬虫项目的运行环境：先完成 Python 3.11 + uv（或 venv）的依赖同步与 Playwright 浏览器驱动安装，再结合 config/base_config.py 的功能开关和 main.py 的命令行参数启动小红书等平台爬虫。读完本文，你将掌握完整的“环境准备 → 依赖安装 → 配置调整 → 爬虫运行”全流程，并理解依赖版本约束、Node.js 前置要求（抖音/知乎签名）在源码层面的真实原因。

一、前置依赖：Python 3.11、uv 与 Node.js

按照 原生环境管理文档 的约定，运行 MediaCrawler 需要准备三类基础组件：

组件	版本要求	用途
Python	建议 3.11（依赖基于该版本构建）	项目解释器
uv	任意较新版本，用 uv --version 验证	依赖与 Python 环境管理（推荐方案）
Node.js	>= 16.0.0	抖音、知乎平台的 JS 签名计算

Node.js 这一前置条件并非文档凭空要求，源码可以印证：抖音与知乎模块通过 pyexecjs 调用外部 JS 文件完成请求签名——

• 抖音签名入口 中执行 douyin_sign_obj = execjs.compile(open('libs/douyin.js', ...).read())，签名算法实现在 libs/douyin.js；
• 知乎签名入口 同样以 execjs.compile 加载 libs/zhihu.js。

execjs 在运行时会调用系统 PATH 中的 node 命令，因此若不满足 Node.js >= 16，爬取抖音（dy）或知乎（zhihu）时会在签名环节失败。仅爬取小红书（xhs）等平台时，Node.js 并非硬性依赖，但建议一并安装以保证全平台可用。

二、推荐方案：使用 uv 管理依赖

MediaCrawler 将 uv 列为推荐的依赖管理方式，原因是它能同时锁定 Python 版本与依赖版本，保证多开发者之间环境一致。

2.1 依赖声明：pyproject.toml 与 uv 锁文件

项目根目录的 pyproject.toml 是 uv 同步依赖的唯一事实来源，其中与“原生环境”最相关的几处声明值得注意：

• requires-python = ">=3.11"：从源头约束解释器版本，与文档中“Python 建议使用 3.11”的说法一致；
• dependencies 列表锁定了关键运行时依赖，例如 playwright>=1.61.0、pyexecjs==1.5.1（Node.js 签名桥梁）、httpx==0.28.1、fastapi==0.110.2、motor>=3.3.0、xhshow>=0.2.0（小红书 Web 端解密）等；
• [[tool.uv.index]] 将默认包索引配置为清华镜像源，国内环境下 uv sync 的下载速度更稳定。

仓库同时附带了 uv.lock 锁文件，保证 uv sync 拉取的依赖版本可复现；另有一份 requirements.txt，与 pyproject 依赖基本对应，供 venv 备选方案使用。

2.2 同步 Python 依赖

进入项目根目录后执行：

# 进入项目根目录
cd MediaCrawler

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

uv sync 会依据 pyproject.toml 自动创建（或复用）项目级虚拟环境、按 uv.lock 安装全部依赖，无需手动 python -m venv 与 pip install。此后所有命令都建议通过 uv run 前缀执行，这样会始终运行在项目虚拟环境内。

2.3 安装 Playwright 浏览器驱动

uv run playwright install

MediaCrawler 的所有平台爬取都基于 Playwright 驱动浏览器，playwright install 负责下载 Chromium 等浏览器二进制。原 原生环境管理文档 中还特别提醒：

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

这一点在 config/base_config.py 中有完整的 CDP 配置段可以印证：ENABLE_CDP_MODE（当前默认为 True）、CDP_DEBUG_PORT = 9222、CDP_CONNECT_EXISTING（连接用户已打开的浏览器，反检测效果最好）、CUSTOM_BROWSER_PATH（自定义浏览器路径，留空时自动检测）等开关。浏览器自动检测与启动逻辑位于 BrowserLauncher（按 Windows/macOS 常见路径探测 Chrome/Edge），而 CDP 浏览器管理器 与 CDP模式使用指南 进一步说明了该模式的工作方式。开启 CDP 模式后，爬虫会复用你本地的 Chrome/Edge 而非 Playwright 自带浏览器，此时 playwright install 的产物更多作为兜底，但首次部署仍建议执行该命令。

三、配置功能开关并运行爬虫程序

环境就绪后，运行前的关键一步是检查 config/base_config.py 中的功能开关。文档中提示“项目默认未开启评论爬取，如需评论请在 config/base_config.py 中修改 ENABLE_GET_COMMENTS，其他功能开关也可在该文件查看，均有中文注释”。需要说明的是，就当前仓库源码而言，ENABLE_GET_COMMENTS 的默认值已调整为 True（注释明确写着“Comment crawling is enabled by default”），即当前版本默认开启一级评论爬取；二级评论 ENABLE_GET_SUB_COMMENTS、媒体资源 ENABLE_GET_MEIDAS、词云 ENABLE_GET_WORDCLOUD 则默认关闭。

该文件中与日常运行最相关的核心开关包括：

配置项	当前默认值	含义
PLATFORM	"xhs"	目标平台：xhs | dy | ks | bili | wb | tieba | zhihu
LOGIN_TYPE	"qrcode"	登录方式：二维码 / 手机 / Cookie
CRAWLER_TYPE	"search"	爬取类型：关键词搜索 / 帖子详情 / 创作者主页
HEADLESS	False	是否无头模式；扫码登录异常时建议打开浏览器手动处理
ENABLE_CDP_MODE / CDP_CONNECT_EXISTING	True / True	CDP 模式：连接本地 Chrome/Edge，降低风控检测风险
SAVE_DATA_OPTION	"jsonl"	数据落盘方式：csv | db | json | jsonl | sqlite | excel | postgres
CRAWLER_MAX_NOTES_COUNT	15	控制爬取的帖子/视频数量上限
CRAWLER_MAX_SLEEP_SEC	2	爬取间隔（秒）
KEYWORDS	"编程副业,编程兼职"	搜索关键词，英文逗号分隔
ENABLE_GET_COMMENTS	True	是否爬取一级评论
ENABLE_GET_SUB_COMMENTS	False	是否爬取二级评论

文件末尾还聚合导入了各平台专属配置（xhs_config、dy_config 等），如 xhs_config.py 中的 XHS_SPECIFIED_NOTE_URL_LIST、dy_config.py 中的 DY_SPECIFIED_ID_LIST，是 --type detail 模式下指定帖子清单的落点。

3.1 典型运行命令

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

# 从配置中读取指定帖子ID列表并爬取帖子与评论
uv run main.py --platform xhs --lt qrcode --type detail

# 其他平台与参数查看帮助
uv run main.py --help

这三条命令与 原生环境管理文档 完全一致。它们的参数语义由 cmd_arg/arg.py 中的 Typer 应用定义：

• --platform：平台枚举（xhs | dy | ks | bili | wb | tieba | zhihu），默认回落到 config.PLATFORM；
• --lt：登录方式（qrcode | phone | cookie）；
• --type：爬取类型（search | detail | creator）；
• 其余可选参数如 --keywords、--get_comment、--headless、--save_data_option、--specified_id、--creator_id、--enable_ip_proxy 等，全部以 config 模块的当前值为默认值。

从源码结构看，命令行参数的处理逻辑在 cmd_arg/arg.py 的 callback 中：解析结果会直接覆盖全局 config 模块的属性（如 config.PLATFORM = platform.value、config.ENABLE_GET_COMMENTS = ...），因此“配置文件定默认值、命令行做临时覆盖”的两层结构是项目约定——你既可以在 base_config.py 里长期调整，也可以不改文件直接用 --get_comment no 之类的参数覆盖本次运行。

3.2 main.py 的启动链路

main.py 展示了环境正确与否如何直接反映到运行时行为：

1. 入口处强制将 stdout/stderr 包装为 UTF-8（避免非 UTF-8 终端下中文输出报错），这是 Windows 默认 GBK 终端上容易踩的坑；
2. cmd_arg.parse_cmd() 解析命令行并覆盖 config；
3. 若传入 --init_db，调用 db.init_db 初始化表结构后退出；SAVE_DATA_OPTION 为 sqlite/db/postgres 时也会自动建表，避免首次运行出现 "no such table" 错误；
4. CrawlerFactory.create_crawler(platform) 按平台键值映射到具体爬虫类（xhs → XiaoHongShuCrawler、dy → DouYinCrawler 等，见 main.py 中的 CrawlerFactory.CRAWLERS），然后 await crawler.start()；
5. 退出前执行 Excel 落盘收尾与词云生成（仅在 json/jsonl 模式且开启词云时）；
6. 进程级生命周期由 tools/app_runner.py 的 run() 托管：捕获 SIGINT/SIGTERM、带 15 秒超时执行 async_cleanup 关闭浏览器上下文与 CDP 会话，第二次中断信号则强制退出（exit code 130）。

这意味着在虚拟环境外直接 python main.py（依赖未装齐）会在 import 阶段即报 ModuleNotFoundError；而 uv run main.py 始终使用 uv sync 构建的环境，能规避这类 PATH/解释器混淆问题——这正是文档将 uv 列为推荐方案的核心原因。

四、备选方案：Python 原生 venv

如果无法使用 uv（例如组织网络策略限制），也可以退回标准 venv 流程。原 原生环境管理文档 将其标注为“不推荐”（依赖锁定能力弱于 uv），但完整步骤仍然保留：

# 进入项目根目录
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

注意两条顺序要求：

• 若爬取抖音或知乎，需提前安装 Node.js（版本 >= 16），因为 requirements.txt 中的 pyexecjs==1.5.1 只是 Python 侧桥梁，实际执行依赖系统 node；
• requirements.txt 与 pyproject.toml 的依赖大体一致（如 httpx==0.28.1、playwright>=1.61.0、pandas==2.2.3），但版本约束以 pyproject + uv.lock 的锁文件更精确；venv 方案下 pip 解析出的具体版本可能与 uv 环境略有差异，排障时应留意。

激活虚拟环境后，运行方式与 uv 方案完全同构，只是去掉 uv run 前缀：

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

# 从配置中读取指定帖子ID列表并爬取帖子与评论
python main.py --platform xhs --lt qrcode --type detail

# 更多示例
python main.py --help

五、环境自检清单与常见问题

部署完成后，建议按以下顺序做一次自检，每步都有明确的“通过”判据：

1. 版本确认：uv --version 输出版本号；python --version（或 uv run python --version）应显示 3.11.x；node --version 应 >= 16（仅 dy/zhihu 必需）。
2. 依赖完整性：uv sync（或 pip install -r requirements.txt）无报错后，可执行 uv run main.py --help。该命令不触发任何网络请求，仅打印 cmd_arg/arg.py 中按“Basic / Account / Comment / Storage / Runtime / Proxy”分组的全部选项，是验证依赖装齐的最快方式。
3. 浏览器驱动：uv run playwright install 结束后，首次运行 main.py 若出现浏览器找不到，多半是驱动未装或 CDP 模式下本地 Chrome 路径未识别——可参照 config/base_config.py 中的 CUSTOM_BROWSER_PATH 手动指定路径（Windows/macOS 示例路径已写在注释里）。
4. 登录态异常：HEADLESS = False 下扫码登录若反复失败，文档与配置注释均建议打开浏览器手动通过滑块验证或手机号验证；登录态会按 SAVE_LOGIN_STATE 与 USER_DATA_DIR（%s_user_data_dir，按平台名替换）持久化，避免每次重新扫码。

六、小结

MediaCrawler 的原生环境管理路径非常收敛：以 Python 3.11 + uv + Node.js(>=16) 为前置，用 uv sync 一次完成依赖同步（依赖声明集中在 pyproject.toml，锁定在 uv.lock），用 uv run playwright install 补齐浏览器驱动，之后通过 uv run main.py --platform ... --lt ... --type ... 结合 config/base_config.py 的功能开关即可在七大平台间切换运行。venv + requirements.txt 作为备选路径保留了完整可用性，但依赖锁定与跨环境一致性上弱于 uv 方案。理解“config 定默认值、命令行参数覆盖 config”的两层配置机制，以及抖音/知乎对 Node.js 签名的真实依赖，是避免环境类故障的两个关键认知。