很多玩B站的人迟早都会遇到同一个尴尬一个视频今天还好好的过几天点进去就显示“已失效”某个UP主换了赛道删掉了自己早期的作品或者你出门在外想看的番剧因为版权问题突然在列表中消失。更常见的是手机里的B站缓存在App里能看一旦清个缓存、换个手机那些视频就再也找不回来了。BiliTools v1.4.7 就是冲着这些痛点来的。它是一款开源的B站视频下载工具支持解析视频链接、批量拉取收藏夹、下载字幕和封面、合并本地缓存m4s文件等一系列操作。简单说它能把B站上你能访问到的视频资源抓下来、合并好、存进你自己的硬盘里。这篇文章我会从B站视频体系的底层逻辑讲起把BiliTools v1.4.7 的部署、实操、常见坑一次说清楚。1. 为什么下载B站视频这么麻烦先搞懂B站的视频体系刚开始接触这类工具的人最容易产生的疑问是为什么下载个B站视频不能像下载普通文件一样直接右键保存答案很简单B站从底层上就没打算让你“便捷地拿走视频”。它的视频分发体系里藏着三道坎理解这三道坎你才能明白 BiliTools 这类下载工具到底在解决什么问题。1.1 音视频分离画面和声音从来不是同一个文件我印象里很多第一次扒B站视频源码的朋友都会被一件事搞懵明明网页上播放的是一个视频结果抓到的接口数据里返回的却是两组URL列表一组是“video/avc1”另一组是“audio/mp4a”。这就是DASH流媒体协议的标准做法B站长期以来把视频流拆成视频轨和音频轨两条独立的流浏览器播放时再实时合成。这样做的好处对平台很明显可以根据用户设备和网络状况单独选择和组合不同清晰度的视频轨、不同码率的音频轨做到按需分发、节省带宽。但代价是下载者如果想得到完整视频就必须同时把两条流都抓下来然后再合并。B站客户端缓存也存在同样的情况。你用手机App看过视频后会留下缓存文件路径一般在Android/data/tv.danmaku.bili/download/下里面清一色是.m4s后缀的文件文件名类似30248、30280有的还带加密后缀。m4s 本身不是多么神秘的格式它本质上是 fMP4 的分段流扩展名是.m4s但文件内部遵循 MP4 容器规范。也就是说只要把音视频两条 m4s 流对齐时间戳、封装进同一个 MP4就能得到一个可以随便播放的文件。这是 BiliTools 合并模块存在的根本原因。1.2 清晰度与登录态权限决定你能抓到什么B站的视频清晰度不是一个单纯的技术参数而是和账号权限绑定的。未登录状态下你能调取到的视频流非常有限通常只有 360P 或 480P 这种低清晰度登录普通账号后大部分公开视频能拿到 720P 到 1080P而 1080P 高码率、1080P60、4K、杜比视界这些则明确需要大会员账号。这意味着下载工具必须处理登录态。BiliTools 的做法是引导用户扫码登录把随后的 Cookie 保存在本地之后所有 API 请求都带着这层身份信息。还有一个细节很值得注意即使你有了大会员下载时能拿到的最高清晰度也取决于当前视频本身提供的最高清晰度档位以及 B 站接口对你账号风控级别的评估。这两点会在后面的常见问题部分展开讲。1.3 防盗链与签名为什么直链不能直接用拆过B站接口的人大概率见过Referer校验的身影。即使你从API里成功拿到了一个视频流的CDN直链如果直接不带任何请求头去下载CDN大概率会甩给你一个 403。原因很简单视频流做了防盗链处理要求请求头里的Referer必须是B站的相关页面地址。另外B站的网页端接口请求也不是裸奔的请求参数里需要带签名。早期是用固定密钥拼参数算MD5后来演进成 WBI 签名机制把关键参数做混淆和时间戳绑定。B站接口一改很多老下载工具就立刻失效这也就是为什么B站下载工具必须保持更新。BiliTools v1.4.7 这类活跃开源项目的优势就在这作者会跟着接口变动持续打补丁而不是发布一个版本就再也不管。2. BiliTools v1.4.7 的功能拆解这个工具到底帮你做了哪些事把底层机制搞清楚之后再来看 BiliTools v1.4.7 的功能感知会完全不一样。它不是一个简单的“一键下载”脚本而是一套围绕B站视频体系的本地化归档工具。2.1 核心能力一览我整理了一下 v1.4.7 时期比较核心的能力模块你可以对着自己的需求看缺哪个功能模块能力说明适用场景视频下载单视频、多P视频、合集、收藏夹批量下载个人备份、字幕组/剪辑素材收集音频提取只下载DASH里的音频流转成m4a/mp3收藏BGM、播客类视频转音频字幕下载抓取视频的CC字幕并转换为srt格式外挂字幕、双语学习、剪辑弹幕保存获取弹幕XML可转ass录播存档、二创素材封面提取下载视频封面图做视频列表、归档整理m4s合并将本地缓存的视频/音频m4s合并成mp4手机缓存抢救、App缓存转本地永久文件这个工具的主要运行形态是交互式命令行。启动后会出现一个菜单按数字键选功能再按提示粘贴链接。没有Web界面也没有花哨的GUI但对经常写脚本、折腾服务器的人来说这种形式反而更可靠也更容易嵌入到自己的自动化流程里。2.2 命令行 模块化的设计思路为什么作者坚持做命令行工具而不是做一个图形界面我的理解是B站下载这种需求本身就带有“批量、自动化、可重复执行”的属性。命令行天然适合脚本调用你可以把 BiliTools 放进定时任务里定期备份某个收藏夹也可以把它打包进自己写的小工具里作为下载后端。BiliTools 的模块化做得也比较清晰。网络请求、API解析、下载调度、合并转封装、字幕转换这几个核心逻辑是分开的。这意味着就算B站某天改了接口通常只需要更新对应的解析模块而不需要把整个工具推倒重做。对用户来说这也是为什么要保持工具版本更新的原因——旧版往往不是你用坏了而是B站把接口改了旧版的解析逻辑不适用了。2.3 从输入一个链接到输出一个mp4中间发生了什么我以“下载一个普通视频”为例给没接触过这类工具的朋友完整串一遍内部流程第一步工具解析你粘贴的链接提取出BV号或av号。第二步拿着BV号请求视频详情API拿标题、UP主、分P列表、封面地址这些元信息。第三步带着登录Cookie请求播放地址API也就是获取DASH流列表的那个接口。第四步从返回的JSON里筛出指定清晰度的视频流URL和音频流URL。第五步分别下载视频流和音频流到临时目录。第六步调用 ffmpeg 把两条流封装成同一个mp4文件。第七步按你设定的命名规则重命名文件并把元信息存成一个json放在旁边。整个过程看起来流程不短但实测下来一个10分钟左右的1080P视频在正常网络环境下从解析到合并完成通常只需要一两分钟。耗时大头基本在网络下载解析和合并都是秒级操作。2.4 支持哪些链接形式BiliTools v1.4.7 能识别的链接范围比我最初预期的大。常规的bilibili.com/video/BV...自然没问题它还支持多P视频链接也就是视频网址后面带?p2这种分P地址可以整集下载或按指定P数下载收藏夹链接比如bilibili.com/medialist/detail/ml...可以直接把一个收藏夹里的所有视频同步到本地视频合集链接对应UP主做的合集列表部分直播间录播、番剧影视的播放页链接登录态满足的情况下3. BiliTools v1.4.7 部署与上手实操下面进入正题怎么把它跑起来。我假设你的电脑上什么开发环境都没有从零开始。3.1 准备环境Python 与 ffmpegBiliTools 是 Python 项目所以第一步是装 Python。建议直接装 3.9 以上的版本Windows 用户去Python官网下载安装包安装时记得勾选“Add Python to PATH”。Linux 用户用系统自带的包管理器安装即可macOS 用户我建议直接用 Homebrew 装。第二个必须装的是 ffmpeg。这个工具负责最终的音频视频合并。Windows 用户可以把 ffmpeg 的压缩包解压后把bin目录路径加进系统环境变量 PATHmacOS 用户执行brew install ffmpegUbuntu/Debian 执行sudo apt install ffmpeg。验证环境是否就绪在终端里分别执行python --version ffmpeg -version两条命令都不报错说明环境准备好了。3.2 获取源码与安装依赖BiliTools 是开源项目源代码直接放在 GitHub 上搜索“BiliTools”找到仓库即可。在终端里执行git clone https://github.com/upuporo/BiliTools.git cd BiliTools如果你是 Windows 用户没有安装 Git也可以直接在仓库页面下载 ZIP 压缩包解压效果一样。接着创建虚拟环境并安装依赖python -m venv .venv # Linux/macOS: source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt这里强调一下用虚拟环境而不是直接pip install到全局是我的个人习惯也是实操中值得养成的习惯。B站下载工具依赖的第三方库版本可能和你系统里其他 Python 项目冲突虚拟环境能把这种冲突隔离掉。3.3 登录与Cookie管理首次启动工具交互菜单里通常会有登录选项。选择扫码登录终端会输出一个二维码用B站手机客户端扫码确认即可。登录成功后工具会把Cookie数据保存在本地文件中。这里有两个实操要点。第一Cookie 是有有效期的过段时间可能就没用了工具会提示登录失效重新扫码就行。第二不要把这个包含 Cookie 的本地文件提交到公开的 Git 仓库里也不要随便发给别人。虽然现在B站的Cookie权限比过去收窄了不少但拿它来模拟你的身份做一些操作还是可能的别给自己找麻烦。3.4 第一次下载单视频实操登录完成后选择视频下载菜单粘贴一个视频链接然后按提示选择清晰度。还是以命令行的典型用法为例类似这样的指令python bilitools.py --url https://www.bilibili.com/video/BV1xx411c7mD -q 1080实际使用中菜单会一步步引导你选择不需要死记参数。下载开始后你会看到类似这样的输出视频流下载进度、音频流下载进度最后是 ffmpeg 合并的调用日志。第一次跑通的时候我建议你做一件事找一个普通的、非大会员限定的视频先下载 720P 试试水。确认整个链路畅通后再上高清晰度和批量任务。这样能避免因为一次失误浪费大量时间下载完才发现某一步配置错了。下载完成的目录里除了最终的 mp4 文件还有一个json文件。这个json里存的是视频标题、UP主、简介、发布时间等元信息。很多人会忽略这个文件但你做本地视频库归档的时候它就是检索和分类的重要依据值得保留。3.5 批量场景收藏夹与多P下载真正体现 BiliTools 价值的场景是批量备份。我自己的习惯是每隔一段时间就把收藏夹整体同步一次相当于给收藏的视频做一个本地副本。批量下载时注意两点一是B站对接口请求频率是有限制的短时间高并发很容易触发风控。工具一般会内置请求间隔的控制如果你自己加参数调并发不要调太激进。二是下载中断的问题。网络抖动可能导致某个视频下到一半失败工具多数支持断点续传或者跳过已下载文件重跑一遍同一任务通常能补完剩下的部分。我实测过一个300多个视频的收藏夹分几个批次跑完单批10到20个视频整个过程基本不用盯着。隔一段时间去看一眼有没有报错就行。4. 进阶玩法m4s合并、字幕、封面与弹幕跑通基本下载之后真正能提升归档效率的是接下来这几个功能。它们也许不是每个人都需要但对特定场景非常有用。4.1 m4s 缓存文件合并实操这是我个人用得最多的功能之一。平时在手机上缓存了视频时间久了想转移到电脑上永久保存直接从缓存目录把文件拷出来是不行的因为内容是分离的音视频轨。这时候 BiliTools 的 m4s 合并功能就能派上用场。合并的原理其实不复杂。B站的 m4s 文件尽管后缀特殊但里面是合法的 fMP4 流。ffmpeg 可以直接处理它ffmpeg -i video.m4s -i audio.m4s -c copy -copyts -avoid_negative_ts make_zero output.mp4参数解释一下-c copy表示不需要重新编码直接把原来的编码数据复制进新的容器速度极快画质无损-copyts是保留原始时间戳-avoid_negative_ts make_zero用来处理某些 m4s 文件的起始时间戳不是从零开始的问题不加这个参数合并后可能出现音画不同步。很多工具会把这条 ffmpeg 命令封装好你只要选中视频目录即可。如果你自己在命令行手动操作遇到音画不同步就优先试试加-copyts和-avoid_negative_ts。4.2 字幕下载与格式转换B站视频的字幕分两类UP主上传的CC字幕以及B站基于语音识别生成的AI字幕。BiliTools 可以抓取视频页面的字幕轨道信息并把字幕内容转成标准的 srt 文件。为什么要强调转 srt因为B站接口返回的字幕数据其实是 JSON 格式字段里包含每个片段的开始时间、结束时间和文本内容。直接看 JSON 是用不了的必须转换。srt 是几乎全平台播放器都支持的通用字幕格式转完之后你可以把字幕文件丢进 PotPlayer、Infuse、Plex 这些播放器里外挂。对学外语、做剪辑的人来说这个功能非常实用。把中文字幕和英文字幕导出来后甚至可以直接作为双语对照的学习材料。4.3 封面与视频元数据的整理视频封面在接口数据里就是一张图片的URL。BiliTools 可以把封面保存下来并和视频文件放在同一个目录里。封面这个功能单看很不起眼但当你本地积累了几千个视频的时候封面就变成了可视化目录的素材。配合前面提到的 json 元数据你完全可以自己写一个脚本生成一个网页形式的视频库索引每个视频配上封面、标题、UP主、发布日期检索起来非常直观。4.4 弹幕保存从xml到ass弹幕下载功能本质上是请求B站的弹幕接口拿到一段XML数据里面是时间轴、弹幕内容、字号颜色这些字段。XML文件虽然也能被部分播放器识别但兼容性一般所以工具通常还提供转成 ass 格式的能力。ass 格式是字幕处理领域很成熟的一种格式可以定义弹幕的字体、颜色、位置、滚动效果。转成 ass 之后你在本地播放器里看到的弹幕效果和B站网页端已经很接近了。做录播存档、二次创作的人对弹幕保存往往有刚需毕竟弹幕本身就是B站视频生态的一部分无数玩梗和三连的瞬间只在当时当刻有效。5. 常见问题与排查技巧实录工具用久了总会踩到一些坑。下面这些问题是我在实际使用中见过频率最高的按照“现象、原因、处理”的思路全部整理出来。5.1 登录态失效与账号风控现象前几天还能下载1080P今天突然只能拿到480P或者工具直接提示需要重新登录。原因有两个方向。一是 Cookie 真的过期了B站对登录态有效期做了限制这种情况重新扫码就行。二是触发了账号风控常见诱因包括短时间内大量下载、并发数开太高、在多个不同 IP 的设备上同时使用同一账号操作下载。处理办法也简单降低并发数两次请求之间加一点间隔换回常用网络环境重新扫码登录后再试。如果账号已经被风控到连网页端都要验证码的程度那就先停半天让风控降级再继续操作。5.2 清晰度被锁定怎么办现象视频明明有4K选项但下载时最高只能选到1080P甚至更低。这种情况先确认三件事账号是不是大会员、登录态有没有正确加载、当前视频是否真的提供目标清晰度。三者缺一个都不行。还有一种情况比较隐蔽你用的是第三方客户端或某些魔改版App登录的账号B站对这类账号的接口权限做了收紧导致即使有大会员也拿不到高清晰度。遇到这种情况用官方App重新扫码登录一次通常就能恢复。5.3 下载中断与重复文件现象批量下载时某几个视频一直下载失败或者磁盘里出现了重复的临时文件。网络波动、接口偶发报错、磁盘空间不足都可能导致下载中断。B站大视频的直链CDN有时候也会因为并发太高短暂拒绝连接重试几次就能解决。我的建议是批量任务失败后不要立刻从头重跑先用工具自带的“跳过已下载”能力续跑。如果工具没有这个功能检查一下下载目录里有没有已经生成的 mp4 文件把没下完的临时文件清掉再重试。5.4 合并失败与音画不同步现象下载都完成了但合并报错或者合并出来的文件声音和画面对不上。合并失败大概率是 ffmpeg 没装好或者不在 PATH 里终端里执行ffmpeg -version确认一下就知道了。音画不同步则多半是时间戳问题优先尝试我在 m4s 合并章节给的那条带-copyts和-avoid_negative_ts的 ffmpeg 命令。如果还是不同步那就不要用-c copy改成重新编码一次ffmpeg -i video.m4s -i audio.m4s -c:v libx264 -c:a aac -strict experimental output.mp4代价是耗时变长、文件变大但兼容性会好很多。等文件重新编码完音画同步通常就正常了。5.5 问题速查表问题现象最可能的原因首选解决方案下载只有480P/360P登录态失效或未登录重新扫码登录高清晰度选项缺失非大会员账号检查账号类型下载返回403防盗链校验失败更新工具到最新版合并报错ffmpeg未安装检查ffmpeg环境音画不同步m4s时间戳偏移加-copyts参数重新合并批量任务频繁失败并发过高触发风控增大请求间隔、降低并发打开视频提示损坏下载不完整删除临时文件后重下6. 关于这类开源工具的几点经验与建议最后聊一点我在使用B站下载开源工具过程中积累的个人体会希望对你有参考价值。第一保持工具版本更新。B站接口变动非常频繁一款下载工具的“保质期”可能只有几个月。如果哪天突然不能用了先去项目仓库看看是不是发布了新版看看 issue 里别人是否也遇到了同样的问题。很多“已失效”并不是永久失效只是你没跟进版本。第二尊重版权和使用边界。下载工具本身是中性的但你怎么用它是有边界的。我的习惯是只下载自己确实想看、想留存的内容比如收藏夹备份、下架风险高的视频、自己参与创作的作品素材。对于需要额外付费才能看的内容还是应该在平台上支持创作者而不是通过工具绕过付费逻辑。这样既对得起创作者也能让这类开源工具活得更久。第三本地化归档是一门细水长流的工程。不要等到视频失效了才想起来备份建议把“定期同步收藏夹”当成和清理手机缓存一样的习惯。一批批下载下来的视频按UP主、主题、年份分好目录配合json元数据和封面文件几年后回头看就是一个别人求都求不来的个人数据库。BiliTools v1.4.7 对我来说不只是一个下载脚本更是一把打开B站内容本地化管理的钥匙。希望这篇内容能帮你少走一些弯路顺利建立起自己的视频归档工作流。