BilibiliDown 配置实战指南:app.config 全解析与下载仓库、命名格式、临时文件管理等常见问题排查

原创2026-10-14 15:23:401,859 阅读
文章标签:桌面应用音视频认证鉴权

BilibiliDown 配置实战指南:app.config 全解析与下载仓库、命名格式、临时文件管理等常见问题排查

本文基于 BilibiliDown 官方 FAQ(release/wiki/Q&A.md)整理而成,覆盖三个本地配置文件的作用、下载中断的恢复机制、下载目录/格式/线程池等核心参数、自定义文件命名语法、"下载记录仓库"的去重原理,以及临时文件清理、SOCKS 代理、分页查询等高频问题的排查步骤。读完之后,你可以针对实际使用场景准确修改 config/app.config,并理解每一项配置在源码中的真实生效位置,避免"改了不生效"的困惑。

三个本地配置文件:程序状态的持久化基础

FAQ 开篇即指明,使用非常规功能时需要了解三个配置文件:

  • config/app.config —— 主配置文件,绝大多数功能开关都在这里;
  • config/cookie.config —— 登录 Cookie 的本地保存位置,登录成功后用于维持登录态;
  • config/repo.config —— 下载成功记录仓库(v3.1 引入),每行一条已完成的下载记录,例如:
av9502825-16-p1
av9502825-16-p4
av9502825-16-p7
av9502825-16-p3
av9502825-16-p5

从源码结构看,app.config 的解析入口在 ConfigUtil.initConfigs:程序先用内置默认值初始化 Global.settings,再依次读取 config/app.config 与 config/user.config 覆盖,最后由 Global.init() 反射地把每个 @Config 注解字段绑定到配置值上(见 Global.init)。配置行必须匹配正则 ^<a href="https://link.gitcode.com/i/1738c2f2aa6e6e4f98f7725e9c1208a6" target="_blank"> ]*([0-9|a-z|A-Z|.|_]+)[ ]*=[ ]*([^ ]+.*$)([ConfigUtil.java#L22),即 key = value 形式,行内注释与空行会被原样保留。值得注意:Global.init 中对 boolean 类配置有 eq_true 映射,因此像 bilibili.repo = on 这类取值是合法值(valids = { "on", "off" }),而不是 true/false。

repo.config 的读写由 RepoUtil 实现,它对仓库文件只做追加操作(appendRecordToFile 以 FileWriter(fRepo, true) 追加写入),不需要的记录需要人工删除,也可以按格式人工添加——这与 FAQ 中"程序对该文件只存在 append 操作,不想要的记录请人工删除,也可以根据需要人工添加哦"的描述一致。

下载中断、手抖关掉程序,进度会丢吗?

FAQ 的答复是:不用慌,下载的临时文件还在,重新下载还是上次的进度。

这个结论在源码中有明确支撑。HttpRequestUtil.download 在下载文件时会先写入一个带 .part 后缀的临时文件:

// 文件下载中先添加.part后缀
File fileDownloadPart = new File(fileDownload.getParent(), fileDownload.getName() + ".part");
raf = new RandomAccessFile(fileDownloadPart, "rw");
// 获取下载进度
long offset = 0;
offset = modifyHeaderMapByDownloaded(headers, raf, fileDownloadPart, offset);

再次下载同一任务时,check 会检查目标文件是否已存在(包括 m4s 音视频合并后的成品 .mp4),若成品已存在则直接判定成功并跳过下载;否则通过 modifyHeaderMapByDownloaded 读取已下载的 .part 大小,向服务端请求 Range 续传。因此异常中断、断电、手动退出后,重新提交同一视频即可断点续传,无需担心已下载的字节作废。

怎样修改下载目录

修改 config/app.config:

# 相对路径
bilibili.savePath = download/
# 绝对路径(Windows 示例)
bilibili.savePath = D:\Workspace\bilibili\

本地测试中 / 和 \ 分隔符似乎都可以。实现上,Global.savePath 通过 @Config(key = "bilibili.savePath", pathType = "dir") 绑定,Global.init() 会统一把结尾分隔符规范为 /(Windows 反斜杠会被转换为正斜杠,见 Global.java#L269-L276),所以两种分隔符都能正常工作。相对路径基于程序运行目录解析(ResourcesUtil.resolve)。

怎样修改优先下载的视频格式

修改 config/app.config:

# 优先 MP4
bilibili.format = 0
# 优先 FLV
bilibili.format = 1

对应 Global.downloadFormat,合法取值为 0/1/2:0 为 MP4(合并分离的音视频,即 m4s 分流后 ffmpeg 合成),1 为 FLV,2 为直接下载 MP4(清晰度无法选择)。FAQ 特别强调,"设置的格式是优先下载,对应 HTML5/FLASH 两种播放方式"。

为什么设置了 MP4,下载出来的还是 FLV?

因为这是"优先"而非"强制":B 站如果没有对应的源,程序只能退回另一种格式,例如当年某些番剧只有 FLASH 源。这种情况下只能换种方式,介意的话请自行转换格式。从当前仓库实现看,M4SDownloader 负责 m4s 音视频分流下载并调用 ffmpeg 合并(见 M4SDownloader.download),FLV 分片则由 CmdUtil.convert(dstName, part) 合并;源端不支持哪种格式,客户端无从改变。

自定义下载文件的命名方式

通过 config/app.config 的 bilibili.name.format 可以完全自定义命名。FAQ 给出的基础占位符:

# 下载文件命名格式
## avId - av号 e.g. av1234567
## pAv - av 的第几个视频  e.g. p1
## pDisplay - 合集的第几个视频 e.g. pn2
## qn - 清晰度值  e.g. 80
## avTitle - av标题
## clipTitle - 视频小标题
###    pDisplay 和 pAv 可能不一致, 比如有的ss是分布在不同的av的第一个视频, 有的则是分布在同一av的不同p
###    建议使用pDisplay而不是pAv
bilibili.name.format = avTitle-pDisplay-clipTitle-qn
FLV==>                     av标题-pn2-视频小标题-80.flv
bilibili.name.format = 开头av标题-pDisplay中间pAv-qn-pAv结尾
MP4==>                     开头av标题-pn2中间p1-80结尾.mp4

当前仓库的实现 CmdUtil.genFormatedName 支持的占位符比 FAQ 更全(可对照 config/app.config 顶部注释):

  • avId:BV 号(FAQ 时代的 av 号已演进为 BV 号);
  • numAvId:老的数字 av 号,由 ConvertUtil.Bv2Av 从 BV 号本地计算得出;
  • pAv / pAv<a href="https://link.gitcode.com/i/cbfbc9e2e30c06615374eb1857dd914b" target="_blank">0-9]:av 的分 P 序号,数字后缀表示对齐长度,不足补零,如 pAv3 产生 p001/p002/p1234(实现见 [formatNumber);
  • pDisplay / pDisplay[0-9]:合集展示序号(pn1/pn2),对齐规则同上;
  • qn:清晰度值;
  • avTitle / clipTitle:av 标题与视频小标题,其中的 / 和 \ 会被替换为 _;
  • UpName / UpId:UP 主名字与 ID;
  • 仅在收藏夹/UP 主视频搜索时有效的字段:listName(集合名称)、listOwnerName(集合拥有者)、favTime(收藏时间)、cTime(发布时间),两个时间字段需配合 bilibili.name.date.favTime.pattern / bilibili.name.date.cTime.pattern(SimpleDateFormat 语法,如 yyMMdd)使用。

命名格式还支持条件语法,正则 splitUnit(CmdUtil.java#L389-L392)解析以下四种形式:

# (:条件 格式字符串)  条件成立时追加括号内格式(格式字符串中不能包含右括号`)`)
# (!条件 格式字符串)  条件不成立时追加
# [:条件 格式字符串]  条件成立时追加(不能包含右方括号`]`)
# [!条件 格式字符串]  条件不成立时追加
bilibili.name.format = (:listName listName-)avTitle-pDisplay-pAv-clipTitle-qn

仓库自带的完整示例(config/app.config#L33)展示了条件与目录结构的组合:

bilibili.name.format = 0_test/UpName/(:listName listName/)avTitle-(:cTime cTime-)pAv2-qn(avId)

条件判断的语义是:当占位符在参数表中存在(paramMap.get(condition) != null)视为成立。生成结束后,程序还会统一剔除文件名中的非法字符 |:*?<>"$,并把路径分隔符转换为当前系统分隔符(CmdUtil.java#L477-L481)。

自定义了重命名格式,为什么下载后文件没有变成想要的名字

修改 config/app.config:

# 下载后马上重命名
bilibili.name.doAfterComplete = true
# 人工重命名 => 运行下载目录下的 rename.bat

对应 Global.doRenameAfterComplete。两种模式的行为见 CmdUtil.convertOrAppendCmdToRenameBat:

  • true:下载完成后立即 renameTo 为格式化文件名;若目标名已存在,会自动追加 (01)、(02) 序号避免覆盖(受 bilibili.name.autoNumber 控制);
  • false:不重命名,而是把 rename "原文件名" "新文件名" 命令逐条追加写入下载目录下的 rename.bat(以 @echo off + chcp 65001 开头保证 UTF-8 中文不乱码),你人工运行它即可完成批量重命名。

换个主题:程序外观设置

修改 config/app.config:

# swing 默认
bilibili.theme = default
# 跟随系统
bilibili.theme = system

对应 Global.themeDefault(valids = { "default", "system" })。FAQ 的坦率回答是:还不满意的话,那就没法子了。

已经下过的视频,如何避免重复下载

这是 FAQ 中最核心的问题之一,涉及"仓库"(repo)机制。

默认行为:如果视频没有改名也没有移动,程序靠"成品文件已存在"就不会再下载(即上文 HttpRequestUtil.check 的跳过逻辑)。

仓库模式(v3.1+):修改 config/app.config:

# 开启仓库模式
bilibili.repo = on
# 同一视频已经有了某清晰度,不想再下
bilibili.definitionStrictMode = off
# 同一视频已经有了某清晰度,还想再下另一种清晰度
bilibili.definitionStrictMode = on

开启后,成功的下载记录会一直保存在 config/repo.config;仓库里的视频将不会再进行下载。源码实现细节:

  • RepoUtil.standardAvPattern 定义了合法记录格式:^((?:av|h|cv|opus|BV|season|au|edd_)[0-9a-zA-Z_]+)-([0-9]+)(-p[0-9]+)$,即 标识-清晰度-分P,这也解释了 FAQ 仓库样例中 av9502825-16-p1 的含义;
  • init 读取仓库时,历史 av 开头的记录会通过 ConvertUtil.Av2Bv 换算成 BV 号后存入内存集合,所以新旧格式记录可以共存;
  • isInRepo 是查询入口:当 definitionStrictMode 为 on 时按"完整记录(含清晰度)"精确匹配,为 off 时剥掉清晰度只按"标识+分P"匹配——这正是两种模式的语义来源;
  • 字幕/弹幕类文件(含 -800-/-801- 的记录)不计入下载记录(appendAndSave);
  • 写入是 synchronized 追加,保证多线程下载下仓库文件的完整性。

想下视频,却提示"我已经下载了"?(v3.1+)

按 FAQ 的排查顺序:

  1. 请确认你真的没有下载过;
  2. 请确认是否下过该视频的另一种清晰度版本:
    • 是 → 设 bilibili.definitionStrictMode = on(不同清晰度算不同记录);
    • 否 → 继续下一步;
  3. 找到 config/repo.config 里的那条记录,把它删除;或者
  4. 关闭仓库模式 bilibili.repo = off(无条件尝试下载)。

批量下载时弹出大量"已下载"确认框(v3.3+)

修改 config/app.config:

# 不想弹出提示
bilibili.alert.isAlertIfDownloded = false
# 限制提示框数量
bilibili.alert.maxAlertPrompt = 5
# 关闭仓库模式(无条件尝试下载)
bilibili.repo = off

对应 Global.isAlertIfDownloded / maxAlertPrompt。弹出控制逻辑在 JOptionPaneManager:只有 isAlertIfDownloded 为 true(或错误信息),且当前提示线程数小于 maxAlertPrompt 时才会真正弹窗,因此批量场景下把 maxAlertPrompt 调小、或直接关闭提示,是两条互不冲突的降噪手段。

我不想保存任何下载记录(v3.1+)

FAQ 给出了完整的"零记录"清单,逐项修改 config/app.config:

# 关闭仓库功能
bilibili.repo = off
# 关闭仓库记录功能
bilibili.repo.save = off

然后人工处理残留:

  • 删除 config/repo.config;
  • 视频下载完成后马上重命名 bilibili.name.doAfterComplete = true(避免成品长期保留原名可被识别);
  • 删除下载目录里的 rename.bat;
  • 下载目录的其它视频等文件请自行斟酌。

源码印证:Global.init 中有一行 Global.saveToRepo = Global.useRepo || Global.saveToRepo;,即 bilibili.repo = on 时强制记录,只有两者都为 off 才真正不落盘。

临时文件管理:strict mode 的取舍

下载过程中会产生若干临时文件:.part 续传文件、m4s 音视频分片(*_video.m4s / *_audio.m4s)、FLV 分片(-partN.flv)、ffmpeg 合并用的 concat 清单(avXXXX-qn-pN.flv.txt)。FAQ 对两个方向都给了答案。

临时文件太多? 开启严格模式:

bilibili.restrictTempMode = on

开启后,只要已存在下载好的视频(无论视频损坏与否),该视频对应的临时文件都会被删除。若出现预期外的异常残留,只能人工删除。

临时文件被莫名删除? 关闭严格模式:

bilibili.restrictTempMode = off

关闭后,只有"下载完成且视频大小达标"时才会删除对应临时文件,某些异常可能导致临时文件未被删除而一直存在——这正是两种模式的取舍。实现见 CmdUtil.deleteAllInactiveCmdTemp:

  • cmdTxtPattern(^(av[0-9]+-[0-9]+-p[0-9]+\.(flv|mp4))\.txt$)匹配 ffmpeg concat 清单,对应视频存在即可删除——该规则始终生效;
  • 只有 restrictTempMode 为 on 时,.part 分片(cmdPartPattern 匹配)与 cmdDonePartPattern 标记的"已分片完成"文件才会在成品存在时被清理。

另外注意 config/app.config 中的提醒:修改多线程下载配置后,若不清空缓存的 .part[0-9]* 文件,可能导致原来未完成的下载任务失败。

我在国外,没法下 B 站视频

使用代理(一般是 SOCKS 代理),修改 config/app.config:

# 设置代理host
socksProxyHost = 127.0.0.1
# 设置代理端口
socksProxyPort = 1080

其它代理方式类似,参见配置文件里的备注。当前仓库同时支持两类代理(config/app.config#L121-L129):

# 同时支持HTTP + HTTPS 代理
#proxyHost = 127.0.0.1
#proxyPort = 1080

# SOCKS 代理,支持 HTTP 和 HTTPS 请求
# 注意:如果设置了 SOCKS 代理就不要设 HTTP/HTTPS 代理
#socksProxyHost = 127.0.0.1
#socksProxyPort = 1080

生效机制在 Global.init:把四个值写入 JVM 系统属性 proxyHost/proxyPort/socksProxyHost/socksProxyPort,供 HttpURLConnection 全局使用。四对 @Config 字段(proxyHost、proxyPort、socksProxyHost、socksProxyPort,见 Global.java#L226-L233)默认值均为空串,不设置即不使用代理。

收藏夹/频道只打开前面 5 个页面?

分页大小由 bilibili.pageSize 控制(默认 5),所以默认只展示前 5 个。三种翻页方式:

  • 在链接后面加上 p=2,就是第 6 到 10 个;
  • 加上 p=3,就是第 11 到 15 个;
  • 想一次打开更多页面:bilibili.pageSize = 5 改大即可。

FAQ 给出的示例:

https://space.bilibili.com/8741628/favlist?fid=101422828&ftype=create p=2
ml101422828 p=3

从源码看,p=N 后缀由 InputParser.paramPattern(^(.*)p=(<a href="https://link.gitcode.com/i/dbe0e3c46622f0c9e2bf1426c2940109" target="_blank">0-9]+)$)统一解析为页码,再由各具体 Parser(MLParser、URL4FavlistParser、URL4ChannelParser 等)拼接到对应 API 的 pn/p 参数上。而"第 6 到 10 个"的计算逻辑在 [AbstractPageQueryParser.result:

int begin = (page - 1) * pageSize + 1;
int end = page * pageSize;

即按 pageSize 把目标区间映射到 B 站 API 的每页 20 条(API_PMAX = 20)分页请求上,跨页时自动多次请求并截取区间。

收藏夹/频道结果的展示方式

  • 一个页面显示(所有选项汇总到一个 Tab 页):bilibili.pageDisplay = listAll;
  • 弹出页面显示(每个 av 分别弹出 Tab 页):bilibili.pageDisplay = promptAll。

对应 Global.pageDisplay,listAll 为默认值,源码注释标明 promptAll 已逐渐弃用,建议保持 listAll。

同时下载很多个视频

修改 config/app.config:

# 修改线程池大小
bilibili.download.poolSize = 3

这个不是越大越好。实现上,Global.downloadPoolSize 决定 Global.downLoadThreadPool 的大小,Global.init 中通过 DownloadExecutors.newPriorityFixedThreadPool(downloadPoolSize) 创建优先级固定线程池——任务按优先级调度,池子越大,对服务器端的瞬时并发压力越大,容易触发限流或封禁风险。另外可配合两个"温柔一点"的参数(Global.java#L95-L98):

# 每个下载任务完成后的等待时间(ms)
bilibili.download.period.between.download = 0
# 每个关于下载的查询任务完成后的等待时间(ms)
bilibili.download.period.between.query = 0

av 页面打开后一直在等待转圈圈

FAQ 给出的排查路径:

  1. 对于已删除视频或违规视频,这是正常的;
  2. 再打开该 av 试一试,看是不是偶然情况;
  3. 试试其它 av;
  4. 如果都不行,请关闭程序,用浏览器打开 B 站某 av(让浏览器带上新的 Cookie/风控参数),再返回程序试一试;
  5. 老铁,打开 run-UI-debug.bat,重复操作,看看啥异常,蟹蟹。

关于第 5 条需要说明适用前提:FAQ 编写时期 Windows 包内附带的是 run-UI-debug.bat;在当前仓库的 release 目录中,对应的调试启动脚本是 Double-Click-to-Run-for-Win-debug.bat(非 Windows 平台可参考同目录的 Create-Shortcut-on-Desktop-for-Linux.sh / Create-Shortcut-on-Desktop-for-Mac.sh 以调试方式启动)。调试模式会把程序输出打到控制台,异常堆栈一目了然。

小结:一张配置速查表

配置项 作用 典型取值
bilibili.savePath 下载保存目录 download/、D:\Workspace\bilibili\
bilibili.format 优先下载格式 0(MP4)、1(FLV)、2(MP4直下)
bilibili.name.format 文件命名模板(支持条件语法/对齐/日期) avTitle-pDisplay-clipTitle-qn
bilibili.name.doAfterComplete 完成后立即重命名 or 写入 rename.bat true / false
bilibili.theme UI 主题 default / system
bilibili.repo 仓库去重开关 on / off
bilibili.repo.save 仅保存记录不拦截 on / off
bilibili.repo.definitionStrictMode 不同清晰度是否算不同记录 on / off
bilibili.alert.isAlertIfDownloded 已下载是否弹窗 true / false
bilibili.alert.maxAlertPrompt 批量下载最大弹窗数 5
bilibili.restrictTempMode 临时文件严格清理 on / off
socksProxyHost / socksProxyPort SOCKS 代理 127.0.0.1 / 1080
bilibili.pageSize 分页查询每页条数 5
bilibili.pageDisplay 分页结果展示方式 listAll / promptAll
bilibili.download.poolSize 并发下载线程池大小 3

所有配置默认值以当前仓库的 config/app.config(源码级默认)与 release/config/app.config(发行包实际下发)为准;行为变更时可对照本文引用的源码文件定位实现。FAQ 中标注 ver>=3.1 / ver>=3.3 的功能(仓库模式、批量弹窗控制等)在当前版本(v6.41)中均已生效,且命名占位符集合相比 FAQ 撰写时已扩展(新增 numAvId、UpName、UpId、listOwnerId、日期格式等),建议以仓库内配置文件注释为最新依据。

登录后查看全文
BilibiliDown