# 微信视频号批量下载工具配置指南

> 工具：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，可用于编程式批量操作和自动化集成

---

> ⚠️ **版权提醒**：下载的视频仅供个人收藏、学习使用，请勿二次上传到公共平台或用于商业用途，尊重原创。