freedakgmail
461 lines
15 KiB
Markdown
461 lines
15 KiB
Markdown
# 微信视频号批量下载工具配置指南
|
||
|
||
> 工具：ltaoo/wx_channels_download v260706
|
||
> 平台：macOS Apple Silicon (arm64)
|
||
> 微信版本：4.1.11 (App Store 版)
|
||
> 监控视频号：剑哥聊餐饮（finder: `sphnu5kSqZT224x`）
|
||
> 下载目录：`/Volumes/Projects/视频/剑哥聊餐饮`
|
||
> 整理日期：2026-07-14（更新于 2026-07-14）
|
||
|
||
---
|
||
|
||
## 一、工具简介
|
||
|
||
`wx_channels_download` 是一个开源的微信视频号视频下载工具，支持：
|
||
|
||
- 单个视频下载
|
||
- 批量下载某创作者的全部视频
|
||
- 自动解密加密视频
|
||
- Web 管理页面管理下载任务
|
||
- 自动去重，避免重复下载
|
||
|
||
**GitHub 地址**：https://github.com/ltaoo/wx_channels_download
|
||
|
||
---
|
||
|
||
## 二、下载与安装
|
||
|
||
### 1. 下载预编译版本
|
||
|
||
```bash
|
||
# 创建目录
|
||
mkdir -p /Users/freedak/WorkBuddy/2026-07-14-07-31-44/wx_video_download
|
||
|
||
# 下载 macOS arm64 版本（v260706）
|
||
cd /Users/freedak/WorkBuddy/2026-07-14-07-31-44/wx_video_download
|
||
curl -L -o wx_video_download_darwin_arm64.zip \
|
||
"https://github.com/ltaoo/wx_channels_download/releases/download/v260706/wx_video_download_v260706_darwin_arm64.zip"
|
||
```
|
||
|
||
### 2. 解压
|
||
|
||
```bash
|
||
unzip -o wx_video_download_darwin_arm64.zip
|
||
```
|
||
|
||
### 3. 移除 macOS 隔离标记
|
||
|
||
```bash
|
||
xattr -d com.apple.quarantine wx_video_download
|
||
```
|
||
|
||
### 4. 文件结构
|
||
|
||
```
|
||
wx_video_download/
|
||
├── wx_video_download # 可执行文件
|
||
└── config.yaml # 配置文件
|
||
```
|
||
|
||
---
|
||
|
||
## 三、配置文件详解
|
||
|
||
配置文件路径：`wx_video_download/config.yaml`
|
||
|
||
```yaml
|
||
# 调试模式（排查问题时开启）
|
||
debug:
|
||
error: true
|
||
echolog: true
|
||
|
||
# 下载设置
|
||
download:
|
||
defaultHighest: false # 是否下载最高画质
|
||
filenameTemplate: "{{filename}}_{{spec}}"
|
||
dir: "/Volumes/Projects/视频/剑哥聊餐饮" # 下载目录（自定义）
|
||
pauseWhenDownload: false # 下载时是否暂停视频播放
|
||
playDoneAudio: true # 下载完成时播放提示音
|
||
frontend: false
|
||
|
||
# API 服务
|
||
api:
|
||
protocol: "http"
|
||
hostname: "127.0.0.1"
|
||
port: 2022 # Web 管理页面端口
|
||
|
||
# 代理设置
|
||
proxy:
|
||
system: true # 是否设置系统代理
|
||
hostname: "127.0.0.1"
|
||
port: 2023 # 代理服务端口
|
||
tun: true # TUN 模式（关键！必须开启）
|
||
skipInstallRootCert: false # 是否跳过根证书安装
|
||
|
||
# Cloudflare 配置（可选，用于 API 解析模式）
|
||
cloudflare:
|
||
accountId: ""
|
||
apiToken: ""
|
||
sphCookie: "561553b295037d16=..." # 从 yuanbao.tencent.com 获取（已配置）
|
||
```
|
||
|
||
### 关键配置说明
|
||
|
||
| 配置项 | 推荐值 | 说明 |
|
||
|--------|--------|------|
|
||
| `proxy.tun` | `true` | TUN 模式通过虚拟网卡拦截流量，是 macOS 上的必选项 |
|
||
| `debug.error` | `true` | 排查问题时开启，正常运行可关闭 |
|
||
| `debug.echolog` | `true` | 排查问题时开启，正常运行可关闭 |
|
||
| `download.dir` | `/Volumes/Projects/视频/剑哥聊餐饮` | 自定义下载目录，可设为任意路径 |
|
||
| `download.defaultHighest` | `false` | 设为 `true` 可下载最高画质 |
|
||
| `cloudflare.sphCookie` | 从 yuanbao.tencent.com 获取 | 用于 API 解析模式，可选配置 |
|
||
|
||
---
|
||
|
||
## 四、启动步骤
|
||
|
||
### 第 1 步：禁用 IPv6（macOS 关键步骤！）
|
||
|
||
> ⚠️ **这是 macOS 上工具能否正常工作的关键！**
|
||
>
|
||
> macOS 微信视频号浏览器 (WeChatAppEx) 默认使用 IPv6 进行所有网络连接。
|
||
> TUN 模式仅拦截 IPv4 流量，IPv6 流量会完全绕过工具，导致下载按钮无法注入。
|
||
|
||
```bash
|
||
# 禁用 Wi-Fi 接口的 IPv6
|
||
sudo networksetup -setv6off Wi-Fi
|
||
|
||
# 验证是否已禁用
|
||
networksetup -getinfo Wi-Fi
|
||
# 应显示：IPv6: Off
|
||
```
|
||
|
||
> 📌 **恢复 IPv6**（使用完毕后执行）：
|
||
> ```bash
|
||
> sudo networksetup -setv6automatic Wi-Fi
|
||
> ```
|
||
|
||
### 第 2 步：关闭 VPN / 代理软件
|
||
|
||
> ⚠️ 如果运行了 LetsVPN、Clash、Surge 等代理软件，必须先关闭！
|
||
>
|
||
> 这些软件会占用代理端口或干扰 TUN 虚拟网卡，导致工具无法正常拦截流量。
|
||
|
||
```
|
||
# 检查 7890 端口是否被占用（LetsVPN 默认端口）
|
||
lsof -i :7890
|
||
|
||
# 如有占用，退出对应的 VPN 软件
|
||
```
|
||
|
||
### 第 3 步：以管理员身份启动工具
|
||
|
||
```bash
|
||
sudo /Users/freedak/WorkBuddy/2026-07-14-07-31-44/wx_video_download/wx_video_download
|
||
```
|
||
|
||
首次运行会自动安装 SunnyNet 根证书（用于 HTTPS 解密），输入电脑密码即可。
|
||
|
||
### 第 4 步：确认启动成功
|
||
|
||
终端应出现以下提示：
|
||
|
||
```
|
||
v260706
|
||
问题反馈 https://github.com/ltaoo/wx_channels_download/issues
|
||
|
||
配置文件 /Users/freedak/WorkBuddy/2026-07-14-07-31-44/wx_video_download/config.yaml
|
||
下载目录 /Users/freedak/Downloads
|
||
|
||
API服务启动成功, 地址: 127.0.0.1:2022
|
||
代理服务启动成功, 地址: 127.0.0.1:2023
|
||
已启用 TUN 模式，流量将通过虚拟网卡自动转发
|
||
请打开需要下载的视频号页面进行下载
|
||
|
||
按 Ctrl+C 退出...
|
||
```
|
||
|
||
### 第 5 步：重启微信
|
||
|
||
1. 右键 Dock 微信图标 → **退出**（确保完全关闭）
|
||
2. 等待几秒
|
||
3. 重新打开微信
|
||
|
||
### 第 6 步：打开视频号
|
||
|
||
1. 微信 → **发现** → **视频号**
|
||
2. 等首页视频刷出来
|
||
3. 视频播放后暂停，查看视频下方操作栏是否出现 **下载按钮**
|
||
|
||
---
|
||
|
||
## 五、SunnyNet 根证书信任设置
|
||
|
||
如果首次运行后证书未自动信任，需要手动设置：
|
||
|
||
### 方法一：终端命令
|
||
|
||
```bash
|
||
# 从钥匙串导出证书
|
||
security find-certificate -c "SunnyNet" -a -p /Library/Keychains/System.keychain > /tmp/SunnyNet.pem
|
||
|
||
# 添加到系统信任
|
||
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /tmp/SunnyNet.pem
|
||
|
||
# 添加到用户信任
|
||
security add-trusted-cert -r trustRoot -k ~/Library/Keychains/login.keychain /tmp/SunnyNet.pem
|
||
```
|
||
|
||
### 方法二：钥匙串访问 GUI
|
||
|
||
1. `Cmd + Space` 搜索 **钥匙串访问**，打开它
|
||
2. 左侧选择 **系统** 钥匙串
|
||
3. 上方标签选 **证书**
|
||
4. 找到 **SunnyNet** → 双击打开
|
||
5. 展开 **信任** 那一栏
|
||
6. 把"使用此证书时"改为 **始终信任**
|
||
7. 关闭窗口，输入电脑密码确认
|
||
|
||
---
|
||
|
||
## 六、下载方式
|
||
|
||
### 方式一：单个视频下载
|
||
|
||
1. 在视频号首页刷视频
|
||
2. 每个视频的操作栏（点赞/评论/转发旁边）会多出一个 **下载按钮**
|
||
3. 页面右侧也有一个 **悬浮下载按钮**
|
||
4. 点击即可下载当前视频
|
||
|
||
### 方式二：微信内批量下载（推荐）
|
||
|
||
1. 在视频号中找到目标创作者 → 点击头像/名称进入 **TA 的个人主页**
|
||
2. 主页右上角有一个 **下载图标**（向下箭头按钮）
|
||
3. **向下滚动**主页，让更多视频加载出来
|
||
> 每刷出一批视频，工具就会自动检测到
|
||
4. 点击右上角 **下载图标** → 弹出下载面板
|
||
5. 面板中会列出已检测到的所有视频 → **勾选要下载的视频** → 点击下载
|
||
|
||
### 方式三：Web 管理页面批量下载
|
||
|
||
**访问地址**：http://127.0.0.1:2022/download
|
||
|
||
1. 在微信视频号中浏览/播放视频（工具会自动检测）
|
||
2. 打开浏览器访问 Web 管理页面
|
||
3. 页面中会列出所有已检测到的视频
|
||
4. **全选/多选**视频 → 点击批量下载
|
||
5. 实时查看下载进度
|
||
|
||
---
|
||
|
||
## 七、下载文件位置
|
||
|
||
| 配置 | 路径 |
|
||
|------|------|
|
||
| 当前下载目录 | `/Volumes/Projects/视频/剑哥聊餐饮/` |
|
||
| 默认下载目录 | `%UserDownloads%`（即 `/Users/freedak/Downloads/`） |
|
||
| 自定义方法 | 修改 `config.yaml` 中 `download.dir` 字段，重启工具生效 |
|
||
|
||
> 修改下载目录后需重启工具才能生效。在终端 `Ctrl+C` 停止工具，重新运行启动命令即可。
|
||
|
||
文件命名格式：`视频标题_画质.mp4`
|
||
|
||
示例文件：
|
||
```
|
||
餐饮赚钱的本质就是读懂人性#餐饮 #餐饮人_xWT111.mp4
|
||
连锁餐饮如何解决餐厅统采统配问题_xWT111.mp4
|
||
餐厅从单店到连锁必须经过的五个阶段_xWT111.mp4
|
||
```
|
||
|
||
---
|
||
|
||
## 八、完整排查过程记录
|
||
|
||
本次配置过程中遇到的问题及解决方案，按排查顺序记录：
|
||
|
||
### 问题 1：nobiyou/wx_channel 不支持 macOS
|
||
|
||
- **现象**：nobiyou 版仅提供 Windows 可执行文件
|
||
- **解决**：改用 ltaoo/wx_channels_download，明确支持 macOS
|
||
|
||
### 问题 2：SunnyNet 证书信任设置不完整
|
||
|
||
- **现象**：证书已安装到钥匙串，但 `trust settings: 0`（未设为"始终信任"）
|
||
- **解决**：导出证书并手动添加信任
|
||
```bash
|
||
security find-certificate -c "SunnyNet" -a -p /Library/Keychains/System.keychain > /tmp/SunnyNet.pem
|
||
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /tmp/SunnyNet.pem
|
||
security add-trusted-cert -r trustRoot -k ~/Library/Keychains/login.keychain /tmp/SunnyNet.pem
|
||
```
|
||
|
||
### 问题 3：LetsVPN 占用 7890 端口
|
||
|
||
- **现象**：微信视频号浏览器将流量发到 `127.0.0.1:7890`（LetsVPN 代理），完全绕过工具
|
||
- **解决**：关闭 LetsVPN
|
||
|
||
### 问题 4：微信沙箱绕过系统代理
|
||
|
||
- **现象**：微信 Mac 客户端运行在 App Sandbox 中，系统代理模式（`tun: false`）下部分流量不走代理
|
||
- **解决**：启用 TUN 模式（`tun: true`），通过虚拟网卡在网络层拦截流量
|
||
|
||
### 问题 5：微信视频号走 IPv6 绕过 TUN（根因！）
|
||
|
||
- **现象**：TUN 模式仅拦截 IPv4 流量，而 macOS 微信视频号浏览器 (WeChatAppEx) 所有连接走 IPv6，完全绕过 TUN 虚拟网卡
|
||
- **诊断**：
|
||
```bash
|
||
lsof -i -n -P | grep WeChatApp | grep ESTABLISHED
|
||
# 所有连接均为 IPv6：[2409:8a00:...] -> [2409:8c02:...]:443
|
||
```
|
||
- **解决**：禁用 Wi-Fi 接口的 IPv6
|
||
```bash
|
||
sudo networksetup -setv6off Wi-Fi
|
||
```
|
||
- **验证**：禁用后 WeChatApp 所有连接从 `10.99.99.1`（TUN 虚拟网卡）发出
|
||
```bash
|
||
lsof -i -n -P | grep WeChatApp | grep ESTABLISHED
|
||
# 所有连接均为 IPv4：10.99.99.1:xxxxx -> x.x.x.x:443
|
||
```
|
||
|
||
### 问题 6：`[FRONTEND ERROR]没有获取到视频详情`
|
||
|
||
- **现象**：工具拦截到流量，JS 注入正常，但前端无法获取视频详情
|
||
- **原因**：间歇性问题（GitHub Issue #415），多刷新几次视频可解决
|
||
- **解决**：在视频号中上下滑动切换几个视频，错误会自行消失
|
||
|
||
---
|
||
|
||
## 九、常见问题
|
||
|
||
| 问题 | 解决方案 |
|
||
|------|---------|
|
||
| 没看到下载按钮 | 1. 检查 IPv6 是否已禁用：`networksetup -getinfo Wi-Fi` 应显示 `IPv6: Off`；2. 检查 VPN 是否已关闭；3. 重启微信 |
|
||
| 代理服务启动失败 | 检查端口 2022/2023 是否被占用：`lsof -i :2022` |
|
||
| 与 VPN/翻墙软件冲突 | 关闭 VPN 软件，或设置 `proxy.tun: true` 使用 TUN 模式 |
|
||
| 证书安装失败 | 确保以 `sudo` 运行，参考第五节手动信任证书 |
|
||
| 下载的视频无法播放 | 工具会自动解密，如仍无法播放检查版本是否为最新 |
|
||
| 想下载最高画质 | `config.yaml` 中设 `download.defaultHighest: true` |
|
||
| `channels.available: false` | 不影响微信内下载按钮使用，Web 搜索功能可能受限 |
|
||
| `[FRONTEND ERROR]没有获取到视频详情` | 间歇性问题，在视频号中多切换几个视频即可 |
|
||
|
||
---
|
||
|
||
## 十、使用完毕后恢复
|
||
|
||
```bash
|
||
# 1. 在工具终端按 Ctrl+C 停止工具
|
||
|
||
# 2. 恢复 IPv6
|
||
sudo networksetup -setv6automatic Wi-Fi
|
||
|
||
# 3. 如需要，重新打开 VPN 软件
|
||
```
|
||
|
||
---
|
||
|
||
## 十一、sphCookie 配置（API 解析模式）
|
||
|
||
sphCookie 用于工具的 API 解析模式，可以在不依赖微信客户端 WebSocket 连接的情况下解析视频号分享链接。
|
||
|
||
### 获取方法
|
||
|
||
1. 使用 Chrome 浏览器访问 `https://yuanbao.tencent.com` 并登录
|
||
2. 打开 Chrome 开发者工具（F12）→ Application → Cookies
|
||
3. 找到 `yuanbao.tencent.com` 域名下的所有 cookie
|
||
4. 复制完整 cookie 字符串
|
||
|
||
### 配置方法
|
||
|
||
将 cookie 写入 `config.yaml`：
|
||
|
||
```yaml
|
||
cloudflare:
|
||
sphCookie: "561553b295037d16=...; _TDID_CK=..."
|
||
```
|
||
|
||
### 自动提取脚本
|
||
|
||
工具目录下提供了 Python 脚本可自动从 Chrome 提取 cookie：
|
||
|
||
```bash
|
||
python3 /Users/freedak/WorkBuddy/2026-07-14-07-31-44/wx_video_download/extract_sph_cookie.py
|
||
```
|
||
|
||
> 注意：cookie 有时效性，过期后需重新获取。配置后需重启工具生效。
|
||
|
||
---
|
||
|
||
## 十二、API 接口说明
|
||
|
||
工具启动后提供以下 API 接口（基地址 `http://127.0.0.1:2022`）：
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/channels/version` | GET | 获取工具版本信息 |
|
||
| `/api/channels/parse_sph` | GET | 解析视频号分享链接（需 `url` 参数） |
|
||
| `/api/channels/feed/profile` | GET | 获取创作者信息（需微信客户端连接） |
|
||
| `/api/channels/contact/feed/list` | GET | 获取创作者视频列表（需微信客户端连接） |
|
||
| `/api/channels/shared_feed/profile` | GET | 获取分享链接对应的创作者信息 |
|
||
| `/api/sph` | GET | SPH 相关功能 |
|
||
| `/api/open_download_dir` | GET | 打开下载目录 |
|
||
| `/api/task/create_batch` | GET | 创建批量下载任务 |
|
||
|
||
### 测试 API
|
||
|
||
```bash
|
||
# 检查工具是否运行
|
||
curl -s http://127.0.0.1:2022/api/channels/version
|
||
|
||
# 解析视频号分享链接
|
||
curl -s "http://127.0.0.1:2022/api/channels/parse_sph?url=https://weixin.qq.com/sph/xxxxx"
|
||
```
|
||
|
||
> 注意：`feed/profile` 和 `contact/feed/list` 接口需要微信客户端通过 WebSocket 连接到工具才能工作。使用前需确保微信已打开且工具成功拦截到微信流量。
|
||
|
||
---
|
||
|
||
## 十三、自动监控下载（规划中）
|
||
|
||
### 目标
|
||
|
||
每日自动监控指定视频号（剑哥聊餐饮），发现新视频后自动下载。
|
||
|
||
### 监控目标
|
||
|
||
- **视频号**：剑哥聊餐饮
|
||
- **Finder 用户名**：`sphnu5kSqZT224x`
|
||
- **下载目录**：`/Volumes/Projects/视频/剑哥聊餐饮/`
|
||
|
||
### 方案设计
|
||
|
||
由于工具获取视频号完整视频列表的 API（`contact/feed/list`）依赖微信客户端的 WebSocket 连接，全自动方案需要微信保持运行状态。
|
||
|
||
**流程**：
|
||
1. 检查工具和微信是否在运行
|
||
2. 通过 `/api/channels/contact/feed/list` API 获取视频号的完整视频列表
|
||
3. 与已下载文件比对，找出新视频
|
||
4. 自动下载新视频
|
||
5. 通过定时任务每日执行
|
||
|
||
**前提条件**：
|
||
- 工具以 `sudo` 运行
|
||
- IPv6 已禁用
|
||
- 微信保持后台运行（无需手动操作）
|
||
- VPN 已关闭
|
||
|
||
---
|
||
|
||
## 十四、关键技术要点总结
|
||
|
||
1. **IPv6 是 macOS 上的最大坑**：微信视频号浏览器默认走 IPv6，必须禁用 IPv6 才能让 TUN 拦截到流量
|
||
2. **TUN 模式优于系统代理模式**：系统代理模式无法拦截 WebSocket 连接，TUN 模式可以完整拦截所有流量
|
||
3. **VPN 软件冲突**：LetsVPN、Clash 等代理软件会占用端口或干扰 TUN，使用前必须关闭
|
||
4. **必须 sudo 运行**：TUN 模式需要创建虚拟网卡，必须以管理员权限运行
|
||
5. **首次运行需信任证书**：SunnyNet 根证书用于 HTTPS 解密，必须设为"始终信任"
|
||
6. **下载目录可自定义**：修改 `config.yaml` 中 `download.dir` 字段，支持绝对路径，重启生效
|
||
7. **sphCookie 可选配置**：从 yuanbao.tencent.com 获取，配置后可使用 API 解析模式
|
||
8. **API 接口可用**：工具提供 REST API，可用于编程式批量操作和自动化集成
|
||
|
||
---
|
||
|
||
> ⚠️ **版权提醒**：下载的视频仅供个人收藏、学习使用，请勿二次上传到公共平台或用于商业用途，尊重原创。
|