微信公众号媒体下载器 WeChat Media Downloader

下载微信公众号文章（mp.weixin.qq.com）中的视频、音频和音乐卡片。适用于：用户想把公众号文章里的 1 个或多个视频、多个音频/音乐保存到本地；直接抓取被微信“环境异常/去验证”拦截；需要通过可见 Chrome + 人工验证 + 远程调试抓取真实媒体地址，再自动下载、提取标题、重命名并整理输出。优先用于中文微信公众号内容场景。

仅在用户有权访问和保存目标媒体时使用。

核心思路

不要和微信反爬硬碰硬。最稳的成功路径是：

1. 先试普通抓取。
2. 一旦页面返回“环境异常 / 去验证”，立即切换为：
   • 可见 Chrome
   • 用户手动完成验证
   • 通过 DevTools 远程调试连接已打开页面
   • 抓取真实视频/音频地址
   • 下载并按文章顺序重命名

执行流程

1) 先判定是否被拦截

• 直接请求文章链接。
• 若返回微信验证页，不继续 headless 硬爬，直接进入人工验证路线。

2) 安装最小工具

优先用户级安装，不要求 sudo。

需要：

• playwright
• yt-dlp（可选；有时直接 HTTP 下载更稳）

推荐命令：

bash

python3 -m pip install --user playwright yt-dlp

3) 让用户启动可见 Chrome

让用户执行：

bash

google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/openclaw-wechat-debug

然后让用户：

• 打开目标公众号文章
• 完成微信验证/登录
• 确认页面中的视频和音频能正常显示

4) 连接真实浏览器会话抓 URL

使用：

• scripts/capture_wechat_media.py

做法：

• 先读取 http://127.0.0.1:9222/json/version
• 取其中 webSocketDebuggerUrl
• 用 CDP 连入 Chrome
• 监听 request / response
• 同时保存页面 HTML

若只抓到视频没抓到音频：

• 让用户把每个音频都点一次播放
• 重新抓取

5) 下载媒体

• 视频：优先使用抓到的 mpvideo.qpic.cn 直链
• 音频：使用 https://res.wx.qq.com/voice/getvoice?mediaid=<voice_encode_fileid>

注意：

• 某些 MP4 直链用 yt-dlp 可能卡收尾；这时直接用 Python HTTP 流式下载反而更稳。

6) 提取标题并重命名

从文章 HTML 中提取：

• 文章标题
• <mp-common-mpaudio ... name="..." voice_encode_fileid="...">

按文章顺序输出成：

• 00. <视频标题>.mp4
• 01. <音频标题>.mp3
• 02. <音频标题>.mp3
• ...

7) 交付与清理

• 把最终文件放入一个干净的新目录
• 可以清理：临时 HTML、JSON、.part、乱码副本、抓取脚本输出
• 不要默认删除最终交付目录

经验规则

• 微信公众号抓取的关键不是“更强的爬虫”，而是“接管已通过验证的真实浏览器会话”。
• 纯 headless 路线经常失败。
• 音频 URL 经常只有播放后才出现。
• 如果 connect_over_cdp('http://127.0.0.1:9222') 返回 400，不要死磕；先取 /json/version 里的 websocket 地址再连接。

自带资源

• scripts/capture_wechat_media.py：连接 Chrome 调试端口，抓取视频/音频请求与页面 HTML
• scripts/download_wechat_media.py：下载视频和音频，并根据文章内容重命名
• references/reusable-workflow.md：可复用操作清单与故障处理