BilibiliDown 配置实战指南:app.config 全解析与下载仓库、命名格式、临时文件管理等常见问题排查
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 的排查顺序:
- 请确认你真的没有下载过;
- 请确认是否下过该视频的另一种清晰度版本:
- 是 → 设
bilibili.definitionStrictMode = on(不同清晰度算不同记录); - 否 → 继续下一步;
- 是 → 设
- 找到
config/repo.config里的那条记录,把它删除;或者 - 关闭仓库模式
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 给出的排查路径:
- 对于已删除视频或违规视频,这是正常的;
- 再打开该 av 试一试,看是不是偶然情况;
- 试试其它 av;
- 如果都不行,请关闭程序,用浏览器打开 B 站某 av(让浏览器带上新的 Cookie/风控参数),再返回程序试一试;
- 老铁,打开
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、日期格式等),建议以仓库内配置文件注释为最新依据。