故障排查 · BiliFlow

开始排查

先记录操作系统、CPU 架构、软件版本，以及 full / lite / 源码运行方式。使用一个无需登录即可完整播放的短视频，将环境问题与作品权限问题区分开。

将并发降低到 1，并换用本地磁盘的新目录，有助于排除限流、同步盘、权限与文件占用。升级后出问题时先备份配置和断点，不要直接删除任务数据库。

当前发布包默认未经 Apple 公证。核对 Release 来源及校验值后，到「系统设置 → 隐私与安全性」查看该应用的打开提示。已经签名或公证的版本会在发行说明中注明。

当前预构建包没有商业代码签名。先确认 ZIP 来自本项目 Release 并完整解压，查看 SmartScreen 的应用详细信息。不要使用第三方重新打包版本。

确认虚拟环境已激活，并安装项目依赖：

bash

python -m pip install -c constraints.txt -e ".[dev]"
python -m bilibili_downloader

full 包应使用内置 FFmpeg。重新完整解压，核对 SHA-256，并检查安全软件是否隔离了依赖文件。设置中的自定义 FFmpeg 路径会覆盖内置版本，清空可恢复。

lite 包与源码运行可以先检查：

bash

ffmpeg -version

终端可用但软件找不到时，在「设置 → 工具与存储」选择实际可执行文件。合并失败时确认目录可写、空间足够，并关闭占用同名目标文件的程序。

Windows v0.7.0 full 包存在内置 FFmpeg 依赖问题，升级到 v0.7.1 或更新版本即可，避免单独下载来源不明的 DLL。

视频与 ep 单集使用单个解析；合集、系列、收藏夹与 ss / md 使用批量导入；直播使用独立直播页。国际站、课程、动态与稍后再看不支持。

b23.tv 需要联网展开。私密或账号专属内容先登录。部分来源失败可在预览中查看原因；风控或限流时降低并发并等待，不要连续重试。

接口只返回作品和当前账号可用的流。会员、地区、购买状态、播放窗口及 DRM 都会影响结果。重新登录并解析后仍不存在的规格，不会被软件额外解锁。

试看、无完整播放权或无完整未加密流会在创建媒体文件前停止；请使用官方渠道观看受限内容。

手动登录可以输入 SESSDATA 或完整 Cookie 字符串，必须包含有效 SESSDATA。网页退出或凭据过期后需重新登录。

扫码接口可能因平台变化暂时不可用。系统凭据库未解锁或不可用时，凭据只存在于当前进程，不会回退写入配置文件；重启后需要重新登录。

不要将真实 Cookie 粘贴到 Issue、日志或公开截图中。

续传取决于断点、Range 支持和重新获取的有效流。降低并发至 1–3，检查代理、网络和磁盘空间，优先使用本地目录。

HEVC 与 AV1 文件需要播放器支持对应解码；优先选择 AVC 可以提高播放兼容性。

任务中心重启后显示「已暂停」是正常恢复行为，点击继续即可。记录存在但文件被移动时，「打开」会提示不存在。

附加项必须由作品实际提供，部分字幕轨还需要登录。主媒体成功但附加项失败时显示「部分完成」，查看具体警告，不需要因此重新下载主视频。

检查配套引擎与 FFmpeg 是否可用，确认应用仍在运行且没有睡眠。磁盘保留空间不足、目录失效、风控和网络中断都可能停止或延迟录制。

历史中的缺口与警告表示异常场次，不能补录已丢失内容。HLS-fMP4 片段在部分播放器中可能显示时间偏移，导出 MP4 可以得到普通播放容器。详见直播录制。

配置损坏会备份为 config.json.bak 并恢复默认值。确认损坏的任务数据库会被隔离，保留隔离文件供排查；更新版本创建的任务库需要使用对应或更新的软件版本。

配置路径和缓存说明见任务与设置。

在 GitHub Issues提供版本、系统和架构、安装方式、最短复现步骤、完整错误及已尝试的方法。公开前移除账号、个人路径、Cookie 和带鉴权参数的媒体 URL。

安全漏洞使用仓库安全报告渠道，避免公开提交凭据或漏洞细节。