FAQ and Troubleshooting

常见问题与故障排查 (FAQ & Troubleshooting)

本文档整理了使用 BBDown 过程中最常见的问题、报错原因及对应的解决方案。

---

1. 混流与外部依赖问题

Q1: 提示 找不到可执行的ffmpeg文件 或 ffmpeg/mp4box 未找到？

• 原因：BBDown 下载分离的音频和视频流后，需要外部混流程序（FFmpeg 或 MP4Box）合并为最终 MP4 文件。
• 解决办法：
  1. 下载 FFmpeg（Windows 推荐 Gyan Builds）。
  2. 将 ffmpeg.exe 放置在与 BBDown.exe 相同的目录下，或将 ffmpeg 所在目录加入操作系统的环境变量 PATH。
  3. 也可在运行时显式通过 --ffmpeg-path "/path/to/ffmpeg" 指定。

Q2: 杜比视界 (Dolby Vision) 混流后画面发绿、偏色或播放黑屏？

• 原因：低版本的 FFmpeg（< 5.0）对杜比视界 Profile 8 / Profile 5 元数据的容器封装支持不完整。
• 解决办法：
  1. 升级 FFmpeg 至 5.0 或更高版本。
  2. 或者改用 MP4Box 进行混流：安装 MP4Box 并追加 --use-mp4box 参数。

---

2. 跨平台与运行时异常

Q3: Linux / macOS 下执行 login 报错 The type initializer for 'Gdip' threw an exception？

• 原因：扫码二维码渲染依赖底层 GDI+ 图像图形库。在 Linux/macOS 上缺少 libgdiplus。
• 解决办法：
  • Debian / Ubuntu: sudo apt-get install -y libgdiplus
  • CentOS / RHEL: sudo yum install -y libgdiplus
  • macOS: brew install mono-libgdiplus
  • 替代方案：可在 Windows/桌面端登录生成 BBDown.data 后直接复制到 Linux 服务器上使用，或通过 -c "SESSDATA=..." 手动传 Cookie。

---

3. 画质、权限与账号问题

Q4: 为什么下载的视频最高只有 480P / 720P，无法下载 1080P60 / 4K / 8K？

• 原因：B 站对未登录游客限制了清晰度；部分 1080P+ 及高帧率画质仅对大会员开放。
• 解决办法：
  • 执行 BBDown login（或 BBDown logintv）扫描登录拥有对应权限的账号。
  • 确认后再次下载即可获取对应画质。

Q5: 提示 [警告] 充电专属视频，接口只返回了试看片段 并退出？

• 原因：目标视频为 UP 主充电专属视频，但当前登录的账号未对该 UP 主进行充电。B 站接口会返回假时长并下发几分钟试看片段。
• 解决办法：
  • 登录已为该 UP 充电的账号后重新下载。
  • 若确实需要保存试看片段，追加 --allow-preview 参数。

Q6: 解析 UP 主空间全部投稿时非常慢？

• 原因：B 站空间投稿列表 API 仅返回稿件元数据，不包含具体分 P 的 cid 与时长。BBDown 需为每个视频单独发起请求展开多 P 结构，投稿数量庞大时请求耗时属于正常现象。
• 优化建议：
  • 可配合 -p 1-20 先分批解析下载。
  • 可配合 --save-archives-to-file 记录已完成历史，防止重复解析。

---

4. 下载速度与网络问题

Q7: 下载速度慢、频繁断流或卡在 99%？

• 优化技巧：
  1. 尝试强制 HTTP：加 --force-http（部分地区运营商 CDN 在 HTTPS 下有限速策略）。
  2. 调整并发分片：修改分片大小 --thread-segment-size 10 或 --thread-segment-size 30。
  3. 尝试 TV 端解析：加 -t（TV 接口的 CDN 调度节点与 Web 端不同）。
  4. 改用 aria2c：安装 aria2 并追加 --use-aria2c。
  5. 更换 UPOS 调度服务器：通过 --upos-host 指定更优的 CDN 节点。

---

5. 如何获取详细调试日志以反馈 Issue？

遇到未知异常或解析错误时，可在命令最后追加 --debug 参数：

BBDown --debug "<URL>"

控制台将打印出完整的 API 请求地址、返回 Header、原始 JSON Payload 及异常堆栈信息。在提交 GitHub Issue 时附带上述调试日志将极大方便定位与修复问题。