Bolly：Go语言开发的B站视频下载命令行工具详解

1. 项目概述：Bolly，一个为B站视频下载而生的利器

最近在折腾一些视频素材，发现B站上有很多高质量的创作者内容，无论是技术教程、生活Vlog还是创意短片，都很有参考和收藏价值。但有时候网络不稳定，或者想离线观看、进行二次创作剪辑，就需要一个可靠的下载工具。市面上工具不少，但要么功能单一，要么操作复杂，要么就是广告满天飞。直到我发现了triangle-int/bolly这个开源项目，它彻底改变了我的工作流。

Bolly，这个名字听起来就有点意思，像是“Bilibili”和“Hollywood”的结合体，暗示着它处理视频的“专业范儿”。这是一个用Go语言编写的命令行工具，核心目标就一个：高效、稳定、功能丰富地下载Bilibili的视频。对于像我这样经常需要处理视频素材的博主、内容创作者或者单纯想收藏视频的爱好者来说，它简直是个宝藏。你不用再忍受网页端各种限制，也不用担心第三方在线解析网站的安全性和稳定性问题。Bolly把下载的控制权完全交还给你，通过几条简单的命令，就能搞定从普通视频到大会员专享、从单P到整个合集的所有内容，并且支持最高画质和音质的选择。

它的出现，解决了一个很实际的痛点：我们如何以一种程序员友好、可脚本化、且尊重版权（仅限个人合理使用）的方式，获取我们需要的视频内容。接下来，我就结合自己这段时间的深度使用经验，从设计思路到实操细节，再到避坑指南，为你完整拆解Bolly这个工具。

2. 核心功能与设计理念解析

2.1 为什么选择命令行工具？

你可能会问，现在图形化工具那么多，为什么还要用命令行？这正是Bolly设计上的高明之处。首先，极致的高效与自动化。对于需要批量下载系列教程、UP主全部视频的场景，图形化工具需要你一次次地点击、粘贴。而Bolly只需要你写好一个包含所有视频ID的文本文件，一行命令就能自动排队下载，甚至可以结合cron任务实现定时抓取更新。其次，资源占用极低。没有复杂的GUI界面，Bolly作为一个单纯的二进制可执行文件，运行起来几乎不占内存，在服务器或低配设备上也能流畅运行，非常适合作为后端服务集成。最后，稳定与透明。命令行工具排除了图形界面可能带来的兼容性和渲染问题，所有操作日志、错误信息都直接输出在终端里，哪里出了问题一目了然，调试起来非常方便。

2.2 核心能力全景图

Bolly绝非一个简单的“下载器”。经过我的梳理，它的核心能力主要体现在以下几个维度：

1. 全面的资源覆盖：不仅支持普通的AV号/BV号视频，还支持：

   • 番剧（Season）与课程：输入番剧的ssid（季节ID）或epid（剧集ID），可以下载整季或单集。
   • 用户空间所有视频：通过UP主的mid（用户ID），可以遍历下载其发布的所有视频。
   • 收藏夹与播单：输入收藏夹ID或播单ID，即可下载其中全部内容。
   • 频道（Channel）：支持下载特定频道下的视频合集。

2. 精细化的下载控制：

   • 画质与音质选择：支持从流畅到4K、杜比视界（如果源有）等多种画质，以及不同码率的音频流。你可以指定“--quality 120”来下载1080P高码率，或者“--quality 80”下载1080P 60帧。
   • 多P视频与分集处理：自动识别多P视频，可以单独下载某一P，也可以批量下载全部。对于番剧，同样支持单集或全集下载。
   • 下载范围限定：支持通过“--start-page”和“--end-page”参数，只下载用户空间或收藏夹中特定页码的视频，避免一次性请求过多。

3. 增强的实用功能：

   • 信息探测：在不下载的情况下，使用“--info”参数可以快速查看视频的标题、作者、分P信息、所有可用的音视频流及其编码、分辨率、码率等详细信息。这在决定下载哪种画质时非常有用。
   • Cookie集成：这是下载大会员专享、高画质视频或私密视频的关键。Bolly支持通过“--cookies”参数指定从浏览器导出的cookies.txt文件，从而以登录状态访问资源。
   • 多线程与断点续传：利用Go语言的高并发特性，Bolly可以实现多线程分段下载，大幅提升速度。并且支持断点续传，网络中断后重新执行命令即可继续，不必重头开始。
   • 自定义输出：可以指定下载目录、自定义文件名模板（包含标题、UP主、分P序号等变量）。

2.3 技术栈选型背后的考量

项目选用Go语言开发，这是一个非常务实且高效的选择。高性能并发是Go的天然优势，对于需要同时处理多个视频流解析、分段下载的任务来说，Go的goroutine模型比传统线程轻量得多，能更好地利用多核CPU，实现高速下载。跨平台编译特性使得开发者能轻松编译出Windows、macOS、Linux等主流系统的可执行文件，用户无需配置复杂的运行时环境，真正做到开箱即用。强大的标准库与丰富的网络生态让处理HTTP请求、解析JSON数据、管理文件系统等操作变得异常简洁。此外，单一二进制文件的部署方式也极大地简化了分发和安装流程。这些特性共同支撑起了Bolly稳定、快速、易用的用户体验。

3. 从零开始：环境准备与安装部署

3.1 系统环境与依赖检查

Bolly本身是静态编译的二进制文件，理论上没有任何额外的运行时依赖。但在实际使用前，我建议你做好以下准备：

• 操作系统：Windows 10/11， macOS 10.14+， 或主流的Linux发行版（如Ubuntu 20.04+, CentOS 7+）均可。我的主要测试环境是macOS Ventura和Windows 11 WSL2下的Ubuntu。
• 网络环境：确保能正常访问Bilibili主站及其CDN节点。某些高画质资源可能需要更好的网络带宽。
• 存储空间：根据你要下载的视频数量和画质，预留足够的磁盘空间。一个10分钟的1080P 60帧视频，体积可能在300MB到800MB之间。
• 命令行终端：Windows用户建议使用PowerShell 7+ 或 Windows Terminal；macOS和Linux用户使用系统自带的终端即可。

3.2 多种安装方式详解

Bolly提供了几种安装方式，你可以根据自身情况选择。

方式一：直接下载预编译二进制文件（推荐新手）这是最快捷的方式。前往项目的GitHub Releases页面，找到最新版本。你会看到针对不同系统的压缩包，例如：

• bolly_windows_amd64.zip(Windows 64位)
• bolly_darwin_amd64.tar.gz(macOS Intel芯片)
• bolly_darwin_arm64.tar.gz(macOS Apple Silicon芯片)
• bolly_linux_amd64.tar.gz(Linux 64位)

下载对应压缩包，解压后就能得到一个名为bolly（Windows下为bolly.exe）的可执行文件。

实操心得：我习惯在用户目录下创建一个Tools文件夹，专门存放这些绿色软件。然后把这个文件夹的路径添加到系统的PATH环境变量中。这样，我就可以在任意位置的终端里直接输入bolly命令来运行它了。添加PATH变量的方法网上教程很多，这里不赘述。

方式二：通过Go工具链从源码安装（适合开发者）如果你本地已经配置好了Go开发环境（Go 1.19+），安装会更加简单。

go install github.com/triangle-int/bolly@latest

执行后，Go会自动下载、编译并将可执行文件安装到$GOPATH/bin或$GOBIN目录下。同样，请确保该目录已在你的PATH中。

方式三：使用包管理器（macOS/Linux）对于macOS用户，如果安装了Homebrew，可以通过添加第三方tap来安装：

brew tap triangle-int/tap brew install bolly

Linux用户如果使用Arch系，可能有AUR包可供安装。

3.3 验证安装与获取帮助

安装完成后，打开终端，输入以下命令验证：

bolly --version

如果成功输出版本号，如bolly version 1.2.0，说明安装成功。

接下来，强烈建议你浏览一下帮助文档：

bolly --help

这会列出所有可用的命令和全局参数。你可以看到bolly [OPTIONS] <VIDEO_URL_OR_ID>是基本的使用格式。每个命令（如info）也有自己的帮助，可以通过bolly info --help查看。

4. 核心操作流程与实战演练

理论讲得再多，不如动手操作一遍。下面我将以几个最典型的场景为例，带你走完完整的下载流程。

4.1 场景一：下载单个视频（AV/BV号）

这是最基础的操作。假设我们要下载这个视频：https://www.bilibili.com/video/BV1xx411c7mD。

步骤1：获取视频信息在决定下载前，先看看有什么可用的资源。

bolly info BV1xx411c7mD

或者直接用完整URL：

bolly info “https://www.bilibili.com/video/BV1xx411c7mD”

命令执行后，终端会输出一个结构清晰的列表，包含视频标题、作者、简介，以及最重要的——所有可用的音视频流。你会看到类似下面的信息：

Title: 【4K珍藏】XXXXXX Author: 某UP主 Video Streams: [120] 高清 1080P (H.264) - 大小: ~450MB [116] 高清 1080P 60帧 (H.264) - 大小: ~680MB [112] 高清 1080P+ (H.265) - 大小: ~380MB [80] 高清 1080P 60帧 (H.265) - 大小: ~550MB [64] 高清 720P (H.264) - 大小: ~220MB Audio Streams: [30280] 高品质音频 (AAC) - 大小: ~50MB [30232] 标准音频 (AAC) - 大小: ~30MB

这里的[120],[116]等就是画质代码。数字越大，通常画质越好（但未必，比如112是HEVC编码的1080P，体积更小）。你需要根据你的需求和设备解码能力来选择。例如，想在手机上看，选116或80（60帧更流畅）；想节省空间且设备支持HEVC，选112。

步骤2：执行下载假设我们选择画质代码116（1080P 60帧）和音频代码30280（高品质）。下载命令如下：

bolly -q 116 -a 30280 BV1xx411c7mD

• -q 116: 指定视频画质代码。
• -a 30280: 指定音频音质代码。
• 如果不指定-a，Bolly会自动选择默认的最高品质音频。

执行命令后，Bolly会开始解析链接、获取流信息，然后启动多线程下载。你会看到实时进度条、下载速度、已用时间等信息。下载完成后，视频和音频文件会自动合并（使用ffmpeg，Bolly已内置相关逻辑），并在当前目录生成一个最终的文件，如【4K珍藏】XXXXXX.mp4。

注意事项：默认情况下，文件会保存在你运行命令的当前目录。你可以使用-o参数指定输出目录，如-o ~/Videos/Bilibili。使用-f参数可以自定义文件名，例如-f “{title} - {owner}”，其中{title}和{owner}是模板变量。

4.2 场景二：使用Cookie下载大会员或高画质内容

很多高码率、杜比视界或大会员专享视频，在不登录的状态下是无法获取下载链接的。这时就需要用到Cookie。

步骤1：获取Cookie文件你需要从浏览器中导出当前登录B站后的Cookie。以Chrome浏览器为例，可以安装“Get cookies.txt”这类扩展程序。安装后，访问B站并确保已登录，然后点击扩展图标，将Cookie导出为cookies.txt文件。将其保存到一个安全的位置，例如~/.config/bolly/cookies.txt。

安全提示：Cookie文件包含了你的登录凭证，务必妥善保管，不要分享给他人或上传到任何公开场合。

步骤2：在下载命令中指定Cookie在下载命令中加入--cookies参数，指向你的Cookie文件。

bolly --cookies ~/.config/bolly/cookies.txt -q 120 BV1xx411c7mD

现在，Bolly就能以你的会员身份访问资源，成功获取高画质流了。

4.3 场景三：批量下载UP主全部视频或某个合集

这是Bolly自动化能力的集中体现。假设你想下载UP主mid=123456的所有视频。

方法A：直接使用--mid参数

bolly --mid 123456

这条命令会开始遍历该UP主的所有视频并依次下载。你可以用--start-page和--end-page来控制范围，比如只下载前3页：

bolly --mid 123456 --start-page 1 --end-page 3

方法B：结合文件列表进行更精细的控制有时你可能需要下载一个特定播单（playlist id）或收藏夹（favorite id）。可以先获取到这些合集里所有视频的ID列表。

1. 使用info命令查看播单信息，或者手动整理出ID列表，保存到一个文本文件list.txt中，每行一个ID或URL。

   BV1xx411c7mD av123456789 https://www.bilibili.com/video/BV1yy411d8nF

2. 使用-i参数指定输入文件进行批量下载。

   bolly -i list.txt -q 112

   Bolly会读取list.txt中的每一行，依次下载指定画质的视频。这种方式非常适合管理自己的下载队列。

实操心得：批量下载时，建议在命令中加入--output指定一个独立的目录，避免文件混杂。另外，可以使用--thread参数调整并发数（默认为4），在网络条件好且硬盘IO性能强的情况下（如NVMe SSD），可以适当调高（如8或16）以提升总体速度，但不宜过高，以免对B站服务器造成过大压力或被限制。

5. 高级技巧与配置文件管理

当使用频率变高，每次输入一长串参数会很麻烦。Bolly支持配置文件，可以让你设置默认选项。

5.1 创建与使用配置文件

Bolly会默认在以下位置查找配置文件config.yaml：

• Unix-like系统（macOS/Linux）:$HOME/.config/bolly/config.yaml
• Windows:%APPDATA%\bolly\config.yaml

你可以手动创建这个文件。一个基础的配置示例如下：

# ~/.config/bolly/config.yaml output: “~/Videos/Bilibili” # 默认下载目录 quality: 112 # 默认视频画质代码 (1080P HEVC) audio-quality: 30280 # 默认音频音质代码 cookies: “~/.config/bolly/cookies.txt” # 默认Cookie文件路径 thread: 8 # 默认下载线程数 retry: 3 # 失败重试次数 file-name-pattern: “{title}” # 默认文件名模板

保存后，之后运行命令时，这些选项就会自动生效。命令行中显式指定的参数会覆盖配置文件中的设置。

5.2 文件名模板的灵活运用

file-name-pattern参数非常强大，它允许你自定义输出文件的命名规则。支持的变量包括：

• {title}: 视频标题
• {owner}: UP主名称
• {bvid}: BV号
• {avid}: AV号
• {page}: 分P序号
• {quality}: 画质描述

例如，设置-f “{owner} - {title}”，下载的文件名就会是“某UP主 - 视频标题.mp4”。这能让你的媒体库变得非常整洁有序。

5.3 与媒体管理软件联动

下载下来的视频，你可能希望导入到像Jellyfin、Plex、Infuse这样的媒体库软件中。为了让这些软件正确识别元数据（如封面、简介），Bolly在下载时会尝试将视频的封面、描述等信息写入到MP4文件的“元数据标签”中。但并非所有播放器都支持读取这些内嵌标签。

一个更通用的做法是，利用Bolly下载后，再使用专门的工具（如tinyMediaManager）根据文件名（尤其是包含UP主和标题的文件名）去互联网上刮削更完整的元数据和海报。将Bolly作为可靠的“内容获取”环节，整合进你自己的媒体管理流水线，这才是发挥其最大价值的方式。

6. 常见问题排查与解决方案实录

在实际使用中，你可能会遇到一些问题。下面是我遇到过的一些典型情况及其解决方法。

6.1 下载速度慢或卡在某个进度

• 原因分析：可能是网络问题、B站CDN节点问题，或者线程数设置不合理。
• 解决方案：
  1. 检查网络：尝试用浏览器直接播放该视频，看是否同样缓冲缓慢。
  2. 更换网络环境：如果使用移动网络，尝试切换到Wi-Fi，或反之。
  3. 调整线程数：使用--thread 1尝试单线程下载，排除多线程可能导致的连接不稳定问题。如果单线程正常，再逐步增加线程数测试。
  4. 稍后重试：有时是B站服务器临时负载高，可以过一段时间再试。

6.2 提示“未找到视频流”或“需要大会员”

• 原因分析：最可能的原因是Cookie未设置或已过期。对于高画质（如4K、杜比视界、1080P高码率）和部分番剧，必须使用有效的登录Cookie。
• 解决方案：
  1. 确认Cookie有效性：在浏览器中访问B站，确认账号处于登录状态，且能正常播放目标画质的视频。
  2. 重新导出Cookie：使用浏览器扩展重新导出cookies.txt文件，旧的Cookie可能已失效。
  3. 检查命令参数：确保在下载命令中正确使用了--cookies /path/to/cookies.txt参数，且路径无误。
  4. 尝试更低画质：如果不追求高画质，可以尝试下载无需会员的流畅或720P画质（如-q 64）。

6.3 合并音视频时失败（FFmpeg错误）

• 原因分析：Bolly内部调用FFmpeg进行音视频合并。失败可能是由于下载的音视频流不完整、文件损坏，或者系统缺少必要的FFmpeg库（尽管Bolly尝试内置）。
• 解决方案：
  1. 检查下载文件：在输出目录中查找.video和.audio结尾的临时文件。如果它们大小异常小（如几KB），说明下载可能未完成。
  2. 重新下载：删除不完整的临时文件，重新执行下载命令。Bolly支持断点续传，会重新下载缺失的部分。
  3. 手动合并：如果临时文件看起来正常，可以尝试手动使用FFmpeg合并。首先确保系统安装了FFmpeg，然后执行：

     ffmpeg -i “video_file.video” -i “audio_file.audio” -c copy “output.mp4”

  4. 报告Issue：如果问题持续，可以保留临时文件和完整的命令行输出日志，到项目的GitHub仓库提交Issue，帮助开发者定位问题。

6.4 批量下载时，某个视频失败导致中断

• 原因分析：默认情况下，Bolly遇到错误会停止。在批量下载长列表时，我们希望它能跳过错误继续下一个。
• 解决方案：使用--skip参数。当某个视频下载失败时，Bolly会记录错误并继续处理列表中的下一个视频。

  bolly -i list.txt --skip

  所有成功和失败的任务都会在最后有一个总结报告。

6.5 在Windows PowerShell中执行，文件名乱码

• 原因分析：PowerShell的默认编码可能与Bolly输出的Unicode字符（如中文）不匹配。
• 解决方案：
  1. 尝试在Windows Terminal或CMD中运行命令。
  2. 或者，在PowerShell中执行命令前，先运行chcp 65001将控制台代码页改为UTF-8。
  3. 使用-f参数指定一个纯英文的文件名模板，避免中文。

问题现象	可能原因	排查步骤与解决方案
速度极慢/无速度	1. 网络问题 2. 线程数过高被限速 3. 资源热度低，CDN无缓存	1. 测试网络，切换环境 2. 降低--thread数 (如设为1或2) 3. 尝试下载其他热门视频对比
提示“access denied”或“403”	1. Cookie失效或未提供 2. IP地址被临时限制	1. 更新Cookie文件 2. 等待一段时间再试，或更换网络IP
下载完成但无法播放	1. 音视频合并失败 2. 播放器不支持该编码格式	1. 检查是否有.video/.audio临时文件，尝试手动合并 2. 尝试使用VLC、PotPlayer等万能播放器，或转换格式
命令执行报“command not found”	Bolly可执行文件不在系统PATH中	1. 使用完整路径执行，如./bolly 2. 将Bolly所在目录添加到系统PATH环境变量

7. 总结与最佳实践建议

经过这段时间的深度使用，Bolly已经成了我处理B站视频素材的标配工具。它的强大之处在于将复杂的功能封装在了简洁的命令行接口之下，既满足了极客对效率和自动化的追求，又通过清晰的文档和提示让新手也能快速上手。

最后，分享几条我个人总结的最佳实践，希望能帮你用得更加顺手：

1. Cookie管理是核心：专门建立一个文件夹存放你的cookies.txt，并在配置文件中设置好路径。定期（如每月）更新一次Cookie，避免因过期导致下载失败。切勿将此文件上传至任何公开的Git仓库或网盘。
2. 善用信息探测（info命令）：在批量下载前，先对列表中的头几个视频执行info，确认目标画质和音质可用，避免下载到一半才发现大会员资源无法获取。
3. 建立项目化下载目录：不要把所有视频都堆在“下载”文件夹。我习惯按主题或UP主建立文件夹，然后在配置文件中设置output目录为一个基础路径，实际下载时再用-o参数指定到具体项目文件夹。例如，基础路径是~/Media/Bilibili，某个系列教程就下载到~/Media/Bilibili/Go语言教程下。
4. 理性使用批量下载：虽然Bolly支持批量，但请尊重创作者和平台。不要用于大规模爬取，避免在短时间内发起大量请求，这既可能对你的账号造成风险，也可能给B站服务器带来不必要的压力。合理安排下载任务，间隔进行。
5. 关注项目更新：开源项目是不断迭代的。时不时去GitHub页面看看是否有新版本发布，新版本通常会修复已知问题、增加对新功能（如B站新推出的编码格式）的支持，甚至提升下载稳定性。

工具的本质是提升效率。Bolly正是这样一个将复杂过程简化的优秀工具。把它融入到你的内容收集、学习或创作流程中，相信它能为你节省大量时间，让你更专注于内容本身。如果在使用过程中发现了新的技巧或遇到了独特的问题，也欢迎在社区里分享交流。