NanmiCoder/MediaCrawler

⭐ 26,761 🍴 6,929 Python📄 カスタムライセンス（非商用学習ライセンス） GitHubで見る →

主な特徴

7つの主要中国ソーシャルメディアプラットフォームをサポート
JavaScript逆向きエンジニアリング不要な設計
QRコード、電話番号、Cookieによる複数のログイン方式
キーワード検索、特定投稿ID、クリエイター主页の3つのクローリングモード
一次・二次コメントの完全取得
IPプロキシプール対応
CSV、JSON、MySQLデータベースへの複数形式での保存
コメントのワードクラウド生成機能
Chrome DevTools Protocol（CDP）モード対応

リポジトリ解析: NanmiCoder/MediaCrawler

基本情報

リポジトリ名: NanmiCoder/MediaCrawler
主要言語: Python
スター数: 26,761
フォーク数: 6,929
最終更新: 活発にメンテナンス中
ライセンス: カスタムライセンス（非商用学習ライセンス）
トピックス: web-scraping, social-media, crawler, xiaohongshu, douyin, bilibili, weibo, playwright, automation

概要

一言で言うと

複数の中国系ソーシャルメディアプラットフォームから公開情報を収集する、教育・研究目的の統合型クローラーツール。

詳細説明

MediaCrawlerは、小紅書（Xiaohongshu）、抖音（Douyin）、快手（Kuaishou）、Bilibili、微博（Weibo）、百度貼吧（Baidu Tieba）、知乎（Zhihu）などの主要な中国ソーシャルメディアプラットフォームからデータを収集するツールです。Playwrightブラウザ自動化フレームワークを使用し、JavaScriptの逆向きエンジニアリングを必要とせずに、ログイン状態を保持したブラウザコンテキストから署名パラメータを取得するアプローチを採用しています。

主な特徴

7つの主要中国ソーシャルメディアプラットフォームをサポート
JavaScript逆向きエンジニアリング不要な設計
QRコード、電話番号、Cookieによる複数のログイン方式
キーワード検索、特定投稿ID、クリエイター主页の3つのクローリングモード
一次・二次コメントの完全取得
IPプロキシプール対応
CSV、JSON、MySQLデータベースへの複数形式での保存
コメントのワードクラウド生成機能
Chrome DevTools Protocol（CDP）モード対応

使用方法

インストール

前提条件

Python 3.9以上
Node.js 16.0.0以上（抖音と知乎のクローリングで必要）
uv（推奨）またはpip
Chromiumブラウザ（Playwrightが自動インストール）

インストール手順

# 方法1: uv経由（推奨）
cd MediaCrawler
uv sync  # Python環境と依存関係を自動的に管理
uv run playwright install  # ブラウザドライバのインストール

# 方法2: pip経由
cd MediaCrawler
python -m venv venv
source venv/bin/activate  # Linux/Mac
# または
venv\Scripts\activate  # Windows
pip install -r requirements.txt
playwright install

基本的な使い方

Hello World相当の例

# 小紅書でキーワード検索して投稿を取得
uv run main.py --platform xhs --lt qrcode --type search
# QRコードが表示されるので、アプリでスキャン

実践的な使用例

# 設定ファイルを編集してから実行
# config/base_config.py:
# KEYWORDS = "美食,旅行"  # 検索キーワード
# ENABLE_GET_COMMENTS = True  # コメント取得を有効化
# CRAWLER_MAX_NOTES_COUNT = 20  # 最大20投稿を取得

# 検索実行
uv run main.py --platform xhs --lt qrcode --type search

# 特定の投稿IDから詳細情報を取得
# config/base_config.py:
# XHS_SPECIFIED_ID_LIST = ["投稿ID1", "投稿ID2"]
uv run main.py --platform xhs --lt cookie --type detail

高度な使い方

# プログラムからの使用例
import asyncio
from media_platform.xhs.core import XiaoHongShuCrawler
from cmd_arg.arg import parse_cmd

async def custom_crawl():
    # コマンドライン引数を解析
    args = parse_cmd()
    args.platform = "xhs"
    args.login_type = "qrcode"
    args.crawler_type = "search"
    
    # クローラーを初期化
    crawler = XiaoHongShuCrawler()
    crawler.init_config(
        platform=args.platform,
        login_type=args.login_type,
        crawler_type=args.crawler_type
    )
    
    # カスタム設定
    crawler.keywords = ["プログラミング", "Python"]
    crawler.max_notes_count = 50
    
    # クローリング実行
    await crawler.start()
    
# 実行
asyncio.run(custom_crawl())

ドキュメント・リソース

公式ドキュメント

README.md: プロジェクトの概要、クイックスタート、基本的な使用方法
docs/: 詳細なドキュメント（オンラインで公開）
- CDP模式使用指南.md: Chrome DevTools Protocol使用ガイド
- 代理使用.md: プロキシ設定ガイド
- 词云图使用配置.md: ワードクラウド生成の設定
- 项目代码结构.md: プロジェクト構造の説明
オンラインドキュメント: https://nanmicoder.github.io/MediaCrawler/

サンプル・デモ

main.py: メインエントリーポイント、使用例を含む
config/base_config.py: 設定例とコメント付き説明
各プラットフォームディレクトリ: プラットフォーム別の実装例

チュートリアル・ガイド

CrawlerTutorial: https://github.com/NanmiCoder/CrawlerTutorial （無料チュートリアル）
作者の知識付費コラム（有料）
微信（WeChat）交流グループ
MediaCrawlerPro（商用版）のドキュメント

技術的詳細

アーキテクチャ

全体構造

MediaCrawlerは抽象基底クラスを使用したオブジェクト指向設計を採用。各プラットフォームは共通インターフェースを実装し、プラグイン形式で拡張可能。Playwrightを中心としたブラウザ自動化により、実際のブラウザ環境でJavaScript実行を通じて必要なパラメータを取得。

ディレクトリ構成

MediaCrawler/
├── base/                     # 基底クラス定義
│   ├── __init__.py
│   └── base_crawler.py      # AbstractCrawler, AbstractLogin, AbstractStore
├── media_platform/          # プラットフォーム別実装
│   ├── xhs/                # 小紅書
│   ├── douyin/             # 抖音
│   ├── kuaishou/           # 快手
│   ├── bilibili/           # Bilibili
│   ├── weibo/              # 微博
│   ├── tieba/              # 百度貼吧
│   └── zhihu/              # 知乎
├── config/                  # 設定管理
│   ├── base_config.py      # 基本設定
│   └── db_config.py        # データベース設定
├── store/                   # データ保存層
├── cache/                   # キャッシュ実装
├── proxy/                   # プロキシ管理
├── tools/                   # ユーティリティ
│   ├── crawler_util.py     # クローラーヘルパー
│   ├── browser_launcher.py # ブラウザ起動
│   └── words.py            # ワードクラウド生成
├── model/                   # データモデル定義
├── cmd_arg/                 # コマンドライン引数処理
└── main.py                  # エントリーポイント

主要コンポーネント

AbstractCrawler: クローラーの基底クラス
- 場所: base/base_crawler.py
- 依存: Playwright, httpx
- インターフェース: start(), search(), launch_browser()
CrawlerFactory: クローラーのファクトリークラス
- 場所: main.py
- 依存: 各プラットフォームのクローラー実装
- インターフェース: create_crawler()
BrowserContext: ブラウザコンテキスト管理
- 場所: tools/browser_launcher.py
- 依存: Playwright
- インターフェース: launch_browser(), connect_cdp()
DataStore: データ永続化層
- 場所: store/
- 依存: aiomysql, pandas, redis
- インターフェース: store_content(), store_comment()

技術スタック

コア技術

言語: Python 3.9+（async/await、型ヒント使用）
フレームワーク:
- Playwright: ブラウザ自動化
- FastAPI: APIサーバー（SMS受信機能）
- asyncio: 非同期処理
主要ライブラリ:
- playwright (1.42.0): ブラウザ自動化とスクレイピング
- httpx (0.24.0): 非同期HTTPクライアント
- pandas (2.2.3): データ処理とCSV/JSON出力
- aiomysql (0.2.0): 非同期MySQLクライアント
- redis (4.6.0): キャッシュとセッション管理
- jieba (0.42.1): 中国語分かち書き
- wordcloud (1.9.3): ワードクラウド生成
- pyexecjs (1.5.1): JavaScript実行

開発・運用ツール

パッケージ管理: uv（推奨）またはpip + requirements.txt
コード品質: mypy.ini（型チェック設定）
ログ管理: Python logging（詳細なデバッグログ）
エラーハンドリング: カスタム例外クラスとリトライ機構

設計パターン・手法

抽象ファクトリーパターン: CrawlerFactoryによるプラットフォーム別クローラーの生成
テンプレートメソッドパターン: AbstractCrawlerで共通処理を定義、各プラットフォームで具体実装
ストラテジーパターン: ログイン方式（QRコード、電話、Cookie）の切り替え
シングルトンパターン: ブラウザインスタンスの管理
非同期プログラミング: asyncio/awaitによる並行処理

データフロー・処理フロー

初期化フェーズ
- コマンドライン引数の解析
- 設定ファイルの読み込み
- クローラーインスタンスの生成（ファクトリー経由）
認証フェーズ
- ブラウザ起動（Playwright）
- ログイン処理（QRコード/電話/Cookie）
- セッション保存
データ収集フェーズ
- 検索/詳細/クリエイターモードに応じた処理
- JavaScript実行による動的コンテンツ取得
- ページネーション処理
- レート制限の遵守
データ保存フェーズ
- データクリーニング
- 形式変換（CSV/JSON/DB）
- 画像ダウンロード（オプション）
- ワードクラウド生成（オプション）

API・インターフェース

公開API

AbstractCrawler インターフェース

目的: 全プラットフォーム共通のクローラーインターフェース
使用例:

class AbstractCrawler(ABC):
    @abstractmethod
    async def start(self) -> None:
        """クローラーを開始"""
        pass
    
    @abstractmethod
    async def search(self) -> None:
        """キーワード検索を実行"""
        pass
    
    @abstractmethod  
    async def get_specified_notes(self) -> None:
        """特定の投稿を取得"""
        pass

設定・カスタマイズ

設定ファイル

# config/base_config.py の主要設定項目

# プラットフォーム設定
PLATFORM = "xhs"  # xhs, dy, ks, bili, wb, tieba, zhihu

# クローリング設定
KEYWORDS = "Python,プログラミング"  # 検索キーワード（カンマ区切り）
CRAWLER_TYPE = "search"  # search, detail, creator
CRAWLER_MAX_NOTES_COUNT = 20  # 最大取得投稿数

# 機能設定
ENABLE_GET_COMMENTS = True  # コメント取得有効化
ENABLE_GET_SUB_COMMENTS = True  # 二次コメント取得
ENABLE_GET_IMAGES = False  # 画像ダウンロード
ENABLE_GET_WORD_CLOUD = True  # ワードクラウド生成

# パフォーマンス設定
MAX_CONCURRENCY_NUM = 5  # 並行処理数
CRAWLER_MAX_SLEEP_SEC = 3  # リクエスト間隔（秒）

# 保存設定
SAVE_DATA_OPTION = "csv"  # csv, db, json

拡張・プラグイン開発

新しいプラットフォームを追加する場合：

media_platform/に新しいディレクトリを作成
以下のファイルを実装：
- client.py: APIクライアント
- core.py: AbstractCrawlerを継承したクローラー
- login.py: AbstractLoginを継承したログイン処理
- field.py: データフィールド定義
main.pyのCrawlerFactoryに登録

パフォーマンス・スケーラビリティ

パフォーマンス特性

ベンチマーク結果:
- 1時間あたり約1000-2000投稿の処理が可能（設定による）
- メモリ使用量: 通常500MB-1GB（ブラウザインスタンス含む）
最適化手法:
- 非同期処理による並行実行
- ブラウザコンテキストの再利用
- レート制限による安定性確保
- キャッシュによる重複リクエスト削減

スケーラビリティ

水平スケーリング: 複数インスタンスの並列実行可能
プロキシプール: 複数IPによる分散処理
データベース分離: 読み書き分離対応
非同期処理: CPU/IOバウンドタスクの効率的処理

制限事項

技術的な制限:
- ブラウザベースのため、メモリ使用量が多い
- プラットフォーム側のレート制限に依存
- 動的コンテンツの読み込み待機が必要
運用上の制限:
- 大規模クローリングは推奨されない（教育目的）
- 各プラットフォームの利用規約を遵守する必要
- 商用利用は明確に禁止

評価・所感

技術的評価

強み

JavaScriptリバースエンジニアリング不要: 複雑な暗号化アルゴリズムの解析が不要で、技術的ハードルが低い
統一されたインターフェース: 7つのプラットフォームを同じAPIで操作可能
堅牢な設計: 抽象化レイヤーによる拡張性の高さ
豊富な機能: ログイン管理、プロキシ対応、多様なデータ保存形式
活発なメンテナンス: 頻繁な更新とコミュニティサポート

改善の余地

リソース消費: ブラウザベースのためメモリ使用量が多い
速度: ヘッドレスAPIと比較して処理速度が遅い
依存性: Playwrightへの強い依存
ドキュメント: 英語ドキュメントの充実度

向いている用途

研究・分析: ソーシャルメディアトレンドの研究
教育: Webスクレイピング技術の学習
小規模データ収集: 特定トピックの調査
プロトタイピング: データ収集システムの検証

向いていない用途

商用利用: ライセンスで明確に禁止
大規模クローリング: リソース効率とレート制限の問題
リアルタイム処理: ブラウザベースのため遅延が大きい
プロダクション環境: 安定性とスケーラビリティの観点

総評

MediaCrawlerは、中国系ソーシャルメディアプラットフォームのデータ収集において、技術的ハードルを大幅に下げる優れたツールです。JavaScriptの逆向きエンジニアリングを避け、ブラウザ自動化を活用するアプローチは革新的で、教育・研究目的には最適です。ただし、ブラウザベースの制約により大規模運用には向かず、あくまで学習・研究ツールとしての位置付けが明確です。コードの設計は優れており、新しいプラットフォームの追加も容易で、Webスクレイピング技術を学ぶ教材としての価値も高いプロジェクトです。