MediaCrawler Documentation

File: README.md Copy Chapter

🔥 MediaCrawler - 自媒体平台爬虫 🕷️

免责声明：

大家请以学习为目的使用本仓库⚠️⚠️⚠️⚠️，爬虫违法违规的案件

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

点击查看更为详细的免责声明。点击跳转

📖 项目简介 Copy Chapter

一个功能强大的多平台自媒体数据采集工具，支持小红书、抖音、快手、B站、微博、贴吧、知乎等主流平台的公开信息抓取。

🔧 技术原理 Copy Section

• 核心技术：基于 Playwright 浏览器自动化框架登录保存登录态
• 无需JS逆向：利用保留登录态的浏览器上下文环境，通过 JS 表达式获取签名参数
• 优势特点：无需逆向复杂的加密算法，大幅降低技术门槛

✨ 功能特性 Copy Chapter

MediaCrawlerPro 重磅发布！开源不易，欢迎订阅支持

专注于学习成熟项目的架构设计，不仅仅是爬虫技术，Pro 版本的代码设计思路同样值得深入学习！

MediaCrawlerPro 相较于开源版本的核心优势：

🎯 核心功能升级

• ✅ 自媒体内容拆解Agent（新增功能）
• ✅ 断点续爬功能（重点特性）
• ✅ 多账号 + IP代理池支持（重点特性）
• ✅ 去除 Playwright 依赖，使用更简单
• ✅ 完整 Linux 环境支持

🏗️ 架构设计优化

• ✅ 代码重构优化，更易读易维护（解耦 JS 签名逻辑）
• ✅ 企业级代码质量，适合构建大型爬虫项目
• ✅ 完美架构设计，高扩展性，源码学习价值更大

🎁 额外功能

• ✅ 自媒体视频下载器桌面端（适合学习全栈开发）
• ✅ 多平台首页信息流推荐（HomeFeed）
• ✅ AI Agent Skill 支持（OpenClaw 🦞 / Claude Code / Cursor 一键安装，让 Agent 自动爬取数据）
• 基于评论分析AI Agent正在开发中 🚀🚀

点击查看：MediaCrawlerPro 项目主页 更多介绍

🚀 快速开始 Copy Chapter

💡 如果这个项目对您有帮助，请给个 ⭐ Star 支持一下！

📋 前置依赖 Copy Chapter

🚀 uv 安装（推荐） Copy Section

在进行下一步操作之前，请确保电脑上已经安装了 uv：

• 安装地址：uv 官方安装指南
• 验证安装：终端输入命令 uv --version，如果正常显示版本号，证明已经安装成功
• 推荐理由：uv 是目前最强的 Python 包管理工具，速度快、依赖解析准确

🟢 Node.js 安装 Copy Section

项目依赖 Node.js，请前往官网下载安装：

• 下载地址：https://nodejs.org/en/download/
• 版本要求：>= 16.0.0

📦 Python 包安装 Copy Section

# 进入项目目录
cd MediaCrawler

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

🌐 浏览器驱动安装（可选） Copy Section

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

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

🌍 Chrome 浏览器配置（推荐） Copy Section

项目默认使用 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 模式。

🚀 运行爬虫程序 Copy Chapter

# 在 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

🖥️ WebUI 可视化操作界面

MediaCrawler 提供了基于 Web 的可视化操作界面，无需命令行也能轻松使用爬虫功能。

开发调试（推荐）

开发时需要同时启动后端 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 功能特性

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

界面预览

🔗 使用 Python 原生 venv 管理环境（不推荐）

创建并激活 Python 虚拟环境

如果是爬取抖音和知乎，需要提前安装 nodejs 环境，版本大于等于：16 即可

# 进入项目根目录
cd MediaCrawler

# 创建虚拟环境
# 我的 python 版本是：3.11 requirements.txt 中的库是基于这个版本的
# 如果是其他 python 版本，可能 requirements.txt 中的库不兼容，需自行解决
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

💾 数据保存 Copy Chapter

MediaCrawler 支持多种数据存储方式，包括 CSV、JSON、JSONL、Excel、SQLite 和 MySQL 数据库。

📖 详细使用说明请查看：数据存储指南

🚀 MediaCrawlerPro 重磅发布 🚀！更多的功能，更好的架构设计！开源不易，欢迎订阅支持！

💬 交流群组 Copy Chapter

• 微信交流群：点击加入
• B站账号：关注我，分享AI与爬虫技术知识

💰 赞助商展示 Copy Chapter

🤝 成为赞助者 Copy Chapter

成为赞助者，可以将您的产品展示在这里，每天获得大量曝光！

联系方式：

• 微信：relakkes
• 邮箱：[email protected]

☕ 请作者喝杯咖啡 Copy Chapter

如果这个项目对您有帮助，欢迎打赏支持，您的每一份支持都是我持续更新的动力 ❤️

📚 其他 Copy Chapter

• 常见问题：MediaCrawler 完整文档
• 爬虫入门教程：CrawlerTutorial 免费教程
• 新闻爬虫开源项目：NewsCrawlerCollection

⭐ Star 趋势图 Copy Chapter

如果这个项目对您有帮助，请给个 ⭐ Star 支持一下，让更多的人看到 MediaCrawler！

📚 参考 Copy Chapter

• 小红书签名仓库：Cloxl 的 xhs 签名仓库
• 小红书客户端：ReaJason 的 xhs 仓库
• 短信转发：SmsForwarder 参考仓库
• 内网穿透工具：ngrok 官方文档

免责声明

1. 项目目的与性质 Copy Chapter

本项目（以下简称“本项目”）是作为一个技术研究与学习工具而创建的，旨在探索和学习网络数据采集技术。本项目专注于自媒体平台的数据爬取技术研究，旨在提供给学习者和研究者作为技术交流之用。

2. 法律合规性声明 Copy Chapter

本项目开发者（以下简称“开发者”）郑重提醒用户在下载、安装和使用本项目时，严格遵守中华人民共和国相关法律法规，包括但不限于《中华人民共和国网络安全法》、《中华人民共和国反间谍法》等所有适用的国家法律和政策。用户应自行承担一切因使用本项目而可能引起的法律责任。

3. 使用目的限制 Copy Chapter

本项目严禁用于任何非法目的或非学习、非研究的商业行为。本项目不得用于任何形式的非法侵入他人计算机系统，不得用于任何侵犯他人知识产权或其他合法权益的行为。用户应保证其使用本项目的目的纯属个人学习和技术研究，不得用于任何形式的非法活动。

4. 免责声明 Copy Chapter

开发者已尽最大努力确保本项目的正当性及安全性，但不对用户使用本项目可能引起的任何形式的直接或间接损失承担责任。包括但不限于由于使用本项目而导致的任何数据丢失、设备损坏、法律诉讼等。

5. 知识产权声明 Copy Chapter

本项目的知识产权归开发者所有。本项目受到著作权法和国际著作权条约以及其他知识产权法律和条约的保护。用户在遵守本声明及相关法律法规的前提下，可以下载和使用本项目。

6. 最终解释权 Copy Chapter

关于本项目的最终解释权归开发者所有。开发者保留随时更改或更新本免责声明的权利，恕不另行通知。

File: docs/data_storage_guide.md Copy Chapter

数据保存指南 / Data Storage Guide

💾 数据保存 Copy Section

MediaCrawler 支持多种数据存储方式，您可以根据需求选择最适合的方案：

存储方式

• CSV 文件：支持保存到 CSV 中（data/ 目录下）
• JSON 文件：支持保存到 JSON 中（data/ 目录下）
• JSONL 文件：支持保存到 JSONL 中（data/ 目录下）— 默认格式，每行一个 JSON 对象，追加写入性能好
• Excel 文件：支持保存到格式化的 Excel 文件（data/ 目录下）✨ 新功能
  • 多工作表支持（内容、评论、创作者）
  • 专业格式化（标题样式、自动列宽、边框）
  • 易于分析和分享
• 数据库存储
  • 使用参数 --init_db 进行数据库初始化（使用--init_db时不需要携带其他optional）
  • SQLite 数据库：轻量级数据库，无需服务器，适合个人使用（推荐）
    1. 初始化：--init_db sqlite
    2. 数据存储：--save_data_option sqlite
  • MySQL 数据库：支持关系型数据库 MySQL 中保存（需要提前创建数据库）
    1. 初始化：--init_db mysql
    2. 数据存储：--save_data_option db（db 参数为兼容历史更新保留）
  • PostgreSQL 数据库：支持高级关系型数据库 PostgreSQL 中保存（推荐生产环境使用）
    1. 初始化：--init_db postgres
    2. 数据存储：--save_data_option postgres

使用示例

# 使用 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 存储数据
uv run main.py --platform xhs --lt qrcode --type search --save_data_option csv

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

# 使用 JSONL 存储数据（默认格式，无需指定）
uv run main.py --platform xhs --lt qrcode --type search --save_data_option jsonl

详细文档

• Excel 导出详细指南：查看 Excel 导出指南
• 数据库配置：参考 常见问题

File: docs/excel_export_guide.md Copy Chapter

Excel Export Guide

Overview Copy Chapter

MediaCrawler now supports exporting crawled data to formatted Excel files (.xlsx) with professional styling and multiple sheets for contents, comments, and creators.

Features Copy Chapter

• Multi-sheet workbooks: Separate sheets for Contents, Comments, and Creators
• Professional formatting:
  • Styled headers with blue background and white text
  • Auto-adjusted column widths
  • Cell borders and text wrapping
  • Clean, readable layout
• Smart export: Empty sheets are automatically removed
• Organized storage: Files saved to data/{platform}/ directory with timestamps

Installation Copy Chapter

Excel export requires the openpyxl library:

# Using uv (recommended)
uv sync

# Or using pip
pip install openpyxl

Usage Copy Chapter

Basic Usage Copy Section

1. Configure Excel export in config/base_config.py:

SAVE_DATA_OPTION = "excel"  # Change from jsonl/json/csv/db to excel

2. Run the crawler:

# Xiaohongshu example
uv run main.py --platform xhs --lt qrcode --type search

# Douyin example
uv run main.py --platform dy --lt qrcode --type search

# Bilibili example
uv run main.py --platform bili --lt qrcode --type search

3. Find your Excel file in data/{platform}/ directory:
   • Filename format: {platform}_{crawler_type}_{timestamp}.xlsx
   • Example: xhs_search_20250128_143025.xlsx

Command Line Examples Copy Section

# Search by keywords and export to Excel
uv run main.py --platform xhs --lt qrcode --type search --save_data_option excel

# Crawl specific posts and export to Excel
uv run main.py --platform xhs --lt qrcode --type detail --save_data_option excel

# Crawl creator profile and export to Excel
uv run main.py --platform xhs --lt qrcode --type creator --save_data_option excel

Excel File Structure Copy Chapter

Contents Sheet Copy Section

Contains post/video information:

• note_id: Unique post identifier
• title: Post title
• desc: Post description
• user_id: Author user ID
• nickname: Author nickname
• liked_count: Number of likes
• comment_count: Number of comments
• share_count: Number of shares
• ip_location: IP location
• image_list: Comma-separated image URLs
• tag_list: Comma-separated tags
• note_url: Direct link to post
• And more platform-specific fields...

Comments Sheet Copy Section

Contains comment information:

• comment_id: Unique comment identifier
• note_id: Associated post ID
• content: Comment text
• user_id: Commenter user ID
• nickname: Commenter nickname
• like_count: Comment likes
• create_time: Comment timestamp
• ip_location: Commenter location
• sub_comment_count: Number of replies
• And more...

Creators Sheet Copy Section

Contains creator/author information:

• user_id: Unique user identifier
• nickname: Display name
• gender: Gender
• avatar: Profile picture URL
• desc: Bio/description
• fans: Follower count
• follows: Following count
• interaction: Total interactions
• And more...

Advantages Over Other Formats Copy Chapter

vs CSV Copy Section

• ✅ Multiple sheets in one file
• ✅ Professional formatting
• ✅ Better handling of special characters
• ✅ Auto-adjusted column widths
• ✅ No encoding issues

vs JSON Copy Section

• ✅ Human-readable tabular format
• ✅ Easy to open in Excel/Google Sheets
• ✅ Better for data analysis
• ✅ Easier to share with non-technical users

vs Database Copy Section

• ✅ No database setup required
• ✅ Portable single-file format
• ✅ Easy to share and archive
• ✅ Works offline

Tips & Best Practices Copy Chapter

1. Large datasets: For very large crawls (>10,000 rows), consider using database storage instead for better performance

2. Data analysis: Excel files work great with:

   • Microsoft Excel
   • Google Sheets
   • LibreOffice Calc
   • Python pandas: pd.read_excel('file.xlsx')

3. Combining data: You can merge multiple Excel files using:

   python Copy

   import pandas as pd
   df1 = pd.read_excel('file1.xlsx', sheet_name='Contents')
   df2 = pd.read_excel('file2.xlsx', sheet_name='Contents')
   combined = pd.concat([df1, df2])
   combined.to_excel('combined.xlsx', index=False)

4. File size: Excel files are typically 2-3x larger than CSV but smaller than JSON

Troubleshooting Copy Chapter

"openpyxl not installed" error Copy Section

# Install openpyxl
uv add openpyxl
# or
pip install openpyxl

Excel file not created Copy Section

Check that:

1. SAVE_DATA_OPTION = "excel" in config
2. Crawler successfully collected data
3. No errors in console output
4. data/{platform}/ directory exists

Empty Excel file Copy Section

This happens when:

• No data was crawled (check keywords/IDs)
• Login failed (check login status)
• Platform blocked requests (check IP/rate limits)

Example Output Copy Chapter

After running a successful crawl, you'll see:

[ExcelStoreBase] Initialized Excel export to: data/xhs/xhs_search_20250128_143025.xlsx
[ExcelStoreBase] Stored content to Excel: 7123456789
[ExcelStoreBase] Stored comment to Excel: comment_123
...
[Main] Excel file saved successfully

Your Excel file will have:

• Professional blue headers
• Clean borders
• Wrapped text for long content
• Auto-sized columns
• Separate organized sheets

Advanced Usage Copy Chapter

Programmatic Access Copy Section

from store.excel_store_base import ExcelStoreBase

# Create store
store = ExcelStoreBase(platform="xhs", crawler_type="search")

# Store data
await store.store_content({
    "note_id": "123",
    "title": "Test Post",
    "liked_count": 100
})

# Save to file
store.flush()

Custom Formatting Copy Section

You can extend ExcelStoreBase to customize formatting:

from store.excel_store_base import ExcelStoreBase

class CustomExcelStore(ExcelStoreBase):
    def _apply_header_style(self, sheet, row_num=1):
        # Custom header styling
        super()._apply_header_style(sheet, row_num)
        # Add your customizations here

Support Copy Chapter

For issues or questions:

• Check 常见问题
• Open an issue on GitHub
• Join the WeChat discussion group

Note: Excel export is designed for learning and research purposes. Please respect platform terms of service and rate limits.

File: docs/index.md Copy Chapter

MediaCrawler使用方法

项目文档 Copy Chapter

• 项目架构文档 - 系统架构、模块设计、数据流向（含 Mermaid 图表）

推荐：使用 uv 管理依赖 Copy Chapter

1. 前置依赖 Copy Section

• 安装 uv，并用 uv --version 验证。
• Python 版本建议使用 3.11（当前依赖基于该版本构建）。
• 安装 Node.js（抖音、知乎等平台需要），版本需 >= 16.0.0。

2. 同步 Python 依赖 Copy Section

# 进入项目根目录
cd MediaCrawler

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

3. 安装 Playwright 浏览器驱动 Copy Section

uv run playwright install

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

4. 运行爬虫程序 Copy Section

# 项目默认未开启评论爬取，如需评论请在 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

备选：Python 原生 venv（不推荐） Copy Chapter

如果爬取抖音或知乎，需要提前安装 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

💾 数据存储 Copy Chapter

支持多种数据存储方式：

• CSV 文件: 支持保存至 CSV (位于 data/ 目录下)
• JSON 文件: 支持保存至 JSON (位于 data/ 目录下)
• 数据库存储
  • 使用 --init_db 参数进行数据库初始化 (使用 --init_db 时，无需其他可选参数)
  • SQLite 数据库: 轻量级数据库，无需服务器，适合个人使用 (推荐)
    1. 初始化: --init_db sqlite
    2. 数据存储: --save_data_option sqlite
  • MySQL 数据库: 支持保存至关系型数据库 MySQL (需提前创建数据库)
    1. 初始化: --init_db mysql
    2. 数据存储: --save_data_option db (db 参数为兼容历史更新保留)

免责声明 Copy Chapter

免责声明：

大家请以学习为目的使用本仓库，爬虫违法违规的案件：https://github.com/HiddenStrawberry/Crawler_Illegal_Cases_In_China

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