MediaCrawler 采集上手指南：10 分钟搞定首次数据抓取

快速安装环境准备

要开始使用 MediaCrawler 采集工具，先确认计算机已安装必要的软件。Python 版本必须保持在 3.11 左右，因为依赖清单专门锁定这个版本。打开终端，执行 uv --version 命令，查看 uv 版本号是否正常。接着检查 node -v，确认版本至少是 16 或更高，这是因为抖音和知乎的签名处理需要 Node 环境支持。

安装完成后，进入命令行界面。运行 git clone 命令拉取项目源码，然后进入项目目录。使用 uv sync 命令一次性安装所有 Python 依赖，这个步骤会严格按照 pyproject.toml 文件中的要求锁定版本，避免版本冲突。接着执行 uv run playwright install 命令，安装 Playwright 的浏览器驱动程序。如果后续使用默认的 CDP 模式连接自己电脑上的 Chrome 浏览器，这一步可以直接跳过。

完成这些后，你的开发环境就准备就绪了。整个过程简单直观，适合刚接触 Python 项目的朋友。安装完依赖后，接下来就该配置采集参数了。

启动首次采集任务

打开项目根目录下的 config/base_config.py 文件，把 KEYWORDS 参数改成你感兴趣的关键词，比如“美食教程”或“科技分享”。然后执行 uv run main.py --platform xhs --lt qrcode --type search 这条命令。其中 --platform 参数用于指定平台，取值包括 xhs（小红书）、dy（抖音）、ks（快手）、bili（B站）、wb（微博）、tieba（贴吧）和 zhihu（知乎）。--lt 参数选择登录方式，这里用 qrcode 表示二维码登录，--type 参数决定采集模式，search 模式适合关键词搜索。

执行后，终端会弹出浏览器窗口，你用手机扫描二维码登录。登录成功后，终端会逐行打印出采集到的笔记信息。这个过程非常直观，数据会自动保存到 data/ 目录下，生成 .jsonl 文件格式的文件。如果你想采集特定帖子的细节，可以把 type 参数改成 detail，并指定帖子的 ID；想采集创作者主页内容，则用 creator 模式。

运行完成后，你就看到 data/ 文件夹里出现了包含笔记和评论的 JSON 文件。这些文件记录了完整的内容，方便后续处理。首次运行通常只需几分钟，就能验证整个链路是否顺畅。

了解平台支持与数据采集模式

MediaCrawler 目前支持七个主流平台，每个平台都提供了三种采集方式。搜索模式通过关键词匹配获取内容，适合批量抓取热门话题；详情模式可以指定具体帖子的 ID，精准采集单个资源；创作者模式则聚焦某个人的所有发布，方便追踪个人动态。

对于内容类型，每个平台都能采集笔记、视频、帖子和评论。评论方面，你可以在 base_config.py 中找到 ENABLE_GET_SUB_COMMENTS 参数，控制是否抓取二级评论。这个设置非常实用，能让数据更全面。采集到的信息会以结构化的形式呈现，便于你后期分析或导入数据库。

不同平台的技术细节略有差异，但整体流程一致。举个例子，小红书和抖音的响应解析方式类似，都依赖浏览器环境下的签名验证。这些模式让你能根据需求灵活调整，避免盲目采集。

数据存储方式详解

采集完成后，数据默认保存在 data/ 目录里。--save_data_option 参数可以控制输出格式，jsonl 是最常用的，适合大批量数据导入；csv 或 json 则更方便用 Excel 或编程语言处理；excel 则直接生成表格文件。无论选择哪种格式，文件都放在 data/ 文件夹下，方便查找和管理。

如果你想用数据库存储，可以在 base_config.py 中配置数据库类型。支持 sqlite、mysql、postgres 和 mongodb 几种。使用 sqlite 的话，只需简单命令初始化表，然后数据会自动写入并自带去重功能。反复运行同一关键词时，不会产生重复记录，这对长期采集很有帮助。

数据库模式下，参数写作 db 格式，比如 --init_db sqlite。切换到 mysql 或 postgres 时，记得填入连接字符串。mongodb 则更灵活，适合存储灵活的 JSON 数据。无论哪种方式，数据结构都清晰，方便后续查询。

优化采集参数提升稳定性

为了让采集过程更稳健，调整几个关键参数效果明显。CRAWLER_MAX_SLEEP_SEC 默认是 2 秒，如果请求间隔太短，容易触发平台风控。建议改成 3 到 5 秒，既能保证速度，又减少出错概率。

CRAWLER_MAX_NOTES_COUNT 默认限制 15 条，首次运行可以先设成 5 条，确认输出正常后再放大。代理配置同样重要，ENABLE_IP_PROXY 总开关打开后，IP_PROXY_POOL_COUNT 设置池大小。IP_PROXY_PROVIDER_NAME 支持 kuaidaili、wandouhttp 或 static 模式，static 时把供应商提供的地址填入 STATIC_PROXY_URL。

这些调整能有效应对账号频繁触发验证码的情况。结合代理池和适度的请求间隔，采集任务就能长期运行而不被中断。参数都在 base_config.py 中集中管理，命令行参数还能覆盖配置，非常灵活。

常见问题排查与进阶技巧

遇到抖音或知乎报错 execjs ProgramError 时，大概率是缺少 Node.js。安装 16 以上版本的 Node 后，重启终端再试。扫码成功但滑块一直过不去，可能是环境未识别为真实登录。保持默认 CDP 模式连接自己 Chrome，HEADLESS 参数改成 False，手动操作滑块就能通过。

如果提示 Cannot connect to existing browser on port 9222，检查 chrome://inspect/#remote-debugging 页面，确保远程调试已启用。账号触发平台风控时，删除 browser_data/ 目录，换一个账号重新登录就能恢复。想深入修改某个平台的字段解析，查看 media_platform/ 目录下的 client.py 文件即可，所有参数都在 base_config.py 中。

这些小技巧能帮你快速解决大部分问题。坚持实验几次，你会发现采集的效率和准确性都大幅提升。接下来，根据需求切换存储方式，把数据存到 sqlite 中，利用去重功能轻松管理。