微信视频号下载器 wx_channels_download v251202：零依赖 MP3 转码、封面修复与下载流优化完全指南

微信视频号下载器 wx_channels_download v251202：零依赖 MP3 转码、封面修复与下载流优化完全指南

【免费下载链接】wx_channels_download 微信视频号下载器 项目地址: https://gitcode.com/gh_mirrors/wx/wx_channels_download

wx_channels_download（微信视频号下载器）于 2025 年 12 月发布 v251202：封面下载恢复可用、浏览器内零 ffmpeg 依赖转 MP3、下载不阻断观看、中转服务下载免去新 tab 绕行，升级即可直接受益。

本版本到底改了什么

变更项	影响范围	是否需要重启
🎬 封面下载修复	后台下载链路（视频/图集）	否，cover 支持热更新
🔊 浏览器内转 MP3	前端下载模式（frontend: true）	否，frontend 支持热更新
⏸️ pauseWhenDownload 新配置	视频号页面内视频播放状态	否，支持热更新
📦 中转服务下载免新 tab	页内下载面板与任务创建流程	否

下文按「场景 → 配置 → 机制」三层递进，带你逐项拆开看。

下载封面：配置、行为与后台任务链路

开启 cover 配置

channels:
  download:
    cover: false

• 默认值：false；设为 true 后，后台下载视频或图集时会同时生成封面任务
• 生效范围：仅在后台下载时生效；前端下载模式下封面由注入脚本直接处理
• 热更新：字段在 Schema 中注册为 HotReload: true，改完即生效（见 internal/adapter/wxchannels/config.go）
• 页面入口：视频内容（mediaType === 4）的下载菜单中会出现「下载封面」项

行为差异

维度	v251202 之前	v251202 之后
点击「下载封面」	封面任务无法正确创建/落盘	后台面板出现 .jpg 任务并正常落盘
任务标识	—	封面任务唯一 ID 固定为 外部ID_cover，与普通视频任务隔离，不产生覆盖冲突

机制要点

后台侧以「任务后缀」识别封面类型，jpg/jpeg 后缀被判定为封面任务，并据此构造独立任务记录（见 internal/adapter/wxchannels/model.go）：

func config_suffix_is_cover(config map[string]any) bool {
	suffix := normalized_config_suffix(config)
	return suffix == "jpg" || suffix == "jpeg"
}

注入脚本侧在后台模式下向本地下载服务创建后缀为 .jpg 的任务，这正是修复前链路断裂的位置（见 pkg/scraper/wxchannels/inject/channels.utils.js）：

if (!WXU.config.downloadInFrontend) {
  var [err, data] = await WXU.downloader.create([feed], {
    platform: "wxchannels",
    suffix: ".jpg",
  });
  WXU.toast("创建下载任务成功");

设计意图：把封面建模为一种带固定后缀的独立任务类型，让「视频 + 封面」可被任务系统分别调度、分别去重。

浏览器内转 MP3：告别本地 ffmpeg

开启 frontend 下载

channels:
  download:
    frontend: true

• 默认值：false（后台下载）；改为 true 后解密、下载、转码全部在浏览器内完成
• 依赖：前端模式零依赖，无需安装 ffmpeg；后台模式仍需要 ffmpeg 做 mp4 → mp3 转码
• 热更新：支持，配置定义见 internal/adapter/wxchannels/config.go
• 入口：仅视频内容（mediaType === 4）的菜单显示「下载为MP3」（见 docs/feature/wxchannels/mp3.md）

行为差异

维度	后台下载（frontend: false）	前端下载（frontend: true）
转码位置	服务端 ffmpeg	浏览器 AudioContext
本地依赖	需要 ffmpeg	无任何依赖
面板显示大小	与最终 mp3 不一致（过程文件是 mp4）	与实际产物一致
文件保存	落入下载目录	浏览器直接保存 .mp3

机制要点

整条管线三步走：decodeAudioData 解码 → 手写 RIFF/WAVE 容器 → 动态加载 frontend/public/recorder.min.js 以 48kHz 采样率、96kbps 编码出 MP3 Blob（见 frontend/inject/audio-converter.js）：

async function mediaToMp3(buf) {
  var audioCtx = new AudioContext();
  return new Promise((resolve) => {
    audioCtx.decodeAudioData(buf, async function (buffer) {
      var blob = mediaBufferToWav(buffer);
      var [err, data] = await wavBlobToMP3(blob);
      // ...

模块按需懒加载：WXU.load_audio_converter() 动态插入脚本并缓存 Promise 防重复加载（见 frontend/inject/utils.js）。设计意图：把转码器做成可选的运行时组件，只在触发 MP3 下载时才付出加载成本。

边看视频号边下载：暂停播放与自动续播

配置 pauseWhenDownload

channels:
  download:
    pauseWhenDownload: false

• 默认值：false（下载时不暂停）；设为 true 后，点击下载先暂停当前视频，下载完成自动恢复
• 生效范围：页内注入脚本的下载动作，与 frontend 取值无关——只要点击发生在浏览器里就会检查该开关
• 热更新：支持；服务端渲染前端时把该值写入 downloadPauseWhenDownload 变量（见 internal/api/handler_frontend.go）

行为差异

维度	默认（false）	开启（true）
点击下载时	视频继续播放	当前视频暂停
下载完成时	无变化	自动续播
观看节奏	下载与播放并行	下载期间无画面声音干扰

机制要点

下载主流程在起止两处对称地挂接了暂停/恢复钩子，底层直接调用页面播放器实例的 play/pause 方法（见 pkg/scraper/wxchannels/inject/channels.utils.js）：

if (WXU.config.downloadPauseWhenDownload) {
  WXU.pause_cur_video();   // 下载开始前
}
// ... 下载、解密、保存 ...
if (WXU.config.downloadPauseWhenDownload) {
  WXU.play_cur_video();    // 下载完成后
}

该逻辑同时对外开放为 WXU.pause_cur_video / WXU.play_cur_video，自定义菜单脚本（参考 docs/feature/wxchannels/custom-menu.md）可直接复用同一套控制。

本地中转服务下载：去掉「开新 tab 再关闭」的割裂体验

开启 remoteServer

download:
  remoteServer:
    enabled: false
    protocol: "http"
    hostname: "192.168.1.118"
    port: 2022

• 默认值：enabled: false；启用后下载任务由中转服务执行，页面操作不再被阻塞（该能力由 v251201 引入，参考 docs/releases/251201.md）
• 配置注入：服务端把 remoteServerEnabled 与 remoteServerOrigin（protocol://hostname:port）写入前端变量（见 internal/api/handler_frontend.go）；脚本侧默认值见 frontend/inject/env.js
• 重启建议：该组参数不在 channels 插件热更新范围内，修改后建议重启再验证（见 docs/config/download.md）

行为差异

维度	v251202 之前	v251202 之后
任务创建/刷新	需临时打开一个新 tab 再关闭来驱动	页内弹层常驻，WebSocket 实时刷新
进度可见性	割裂，跳 tab 才能看状态	弹层内直接展示，图标上带连接状态点
打开新 tab 的场景	日常下载也会触发	仅剩「管理下载任务」菜单会显式打开管理页

机制要点

下载面板改为 Popover 弹层承载，通过监听 .home-header / .page-profile 节点插入页面，任务状态经 /ws/v1/download_task 长连接推送（见 frontend/inject/download/panel.js）。保留 window.open 的只有这一处（见 frontend/inject/download/model.js）：

new Timeless.vm.MenuItemCore({
  label: "管理下载任务",
  onClick() {
    ui.dropdown$.hide();
    window.open(DownloaderOrigin + "/", "_blank");
  },
}),

设计意图：把「状态展示」与「完整管理页」分层，日常路径零跳转，只有需要全量管理时才付出一次 tab 成本。

功能间的联动与互斥

• 🔊 「浏览器内转 MP3」以 channels.download.frontend: true 为前置；后台模式下 mp3 仍走 ffmpeg 转码
• 🎬 channels.download.cover 只约束后台下载任务；前端模式下封面由注入脚本直接保存
• ⏸️ pauseWhenDownload 与 frontend 相互独立，任意组合下都作用于页内点击下载
• 📦 download.remoteServer 只改变任务执行宿主，页内面板与 WebSocket 刷新逻辑不受其开关影响
• 自定义菜单（global.js）可与 pauseWhenDownload 组合，复用同一暂停/恢复 API

配置速查与升级验证

配置键	类型	默认值	热更新	一句话说明	文档路径
channels.download.cover	bool	false	是	后台下载时是否同时下载封面	docs/config/channels/cover.md
channels.download.frontend	bool	false	是	前端解密下载，启用后 MP3 转换零依赖	docs/config/channels/frontend.md
channels.download.pauseWhenDownload	bool	false	是	点击下载时暂停播放，完成后续播	docs/config/channels/pause-when-download.md
download.remoteServer.enabled	bool	false	否（建议重启）	启用本地下载中转服务	docs/config/download.md

升级后按序验证：在视频页点开下载菜单确认出现「下载封面」，点击后后台面板出现 .jpg 任务并落盘；把 frontend 置 true 后点「下载为MP3」，在无 ffmpeg 的机器上确认得到 .mp3；把 pauseWhenDownload 置 true，点击下载观察视频暂停、完成后续播；最后开启 remoteServer 重启服务，下载一次确认全程无新 tab 弹出。完整字段 Schema 见 internal/adapter/wxchannels/config.go，配置模板见 internal/config/config.template.yaml。

写在最后

v251202 把视频号下载链路中「封面不可用、转码依赖重、下载打断观看、tab 跳转割裂」四个体验断点一次补齐，属于可直接受益的功能型迭代。建议你升级后先把 frontend: true 与 pauseWhenDownload: true 配上，感受最明显的体验变化。后续版本若继续打磨批量下载与中转服务的组合玩法，可关注 docs/releases/251202.md 之后的发布说明；需要源码可自行 git clone https://gitcode.com/gh_mirrors/wx/wx_channels_download 获取仓库。

【免费下载链接】wx_channels_download 微信视频号下载器 项目地址: https://gitcode.com/gh_mirrors/wx/wx_channels_download