BBDown实战手册：从零构建B站视频本地化工作流
BBDown 是一款基于 .NET 构建的跨平台命令行工具，专为高效获取哔哩哔哩（Bilibili）内容而设计。它不依赖图形界面，通过结构化命令与模块化架构，支持视频、音频、字幕、弹幕等多维度内容提取，并兼容普通投稿、番剧、课堂、收藏夹及UP主空间等多种内容形态。
核心优势与适用场景
相较于浏览器插件、在线转换服务或录屏方案，BBDown 在以下方面具备显著优势：
- 原始流直取：绕过转码环节，保留原始分辨率（最高达8K）与音质
- 协议级适配：内置 Web、APP、TV 三端接口模拟能力，应对B站API策略变动
- 无状态轻量部署：单二进制文件即可运行，无需安装复杂依赖（ffmpeg/aria2c 可选集成）
- 可编程扩展性：支持配置文件、HTTP API 服务、Docker 容器化及脚本批量调度
环境准备与快速验证
在任意终端中执行以下步骤完成初始化：
# 克隆源码（推荐用于获取最新功能）
git clone https://gitcode.com/gh_mirrors/bb/BBDown
cd BBDown
# 或直接下载预编译版本（Windows/macOS/Linux）
# 地址见项目主页：https://gitcode.com/gh_mirrors/bb/BBDown
# 验证运行时环境（需 .NET 6+）
dotnet --version
# 测试基础功能
./BBDown --version
常用操作模式
1. 单视频下载（自动最优画质）
./BBDown "https://www.bilibili.com/video/BV1AB4y1W7Zx"
该命令将自动解析视频元数据、选择可用最高清晰度流、分离音视频轨，并调用 ffmpeg 合成标准 MP4 文件。
2. 精确控制输出格式
# 指定画质并仅保留音频
./BBDown --audio-only -q "1080P" "https://www.bilibili.com/video/BV1CD4y1X7Yz"
# 下载第3个分P（适用于多P系列）
./BBDown -p 3 "https://www.bilibili.com/video/BV1kF411T7Jm"
# 自定义命名模板（支持动态变量）
./BBDown --file-pattern "{uploader}_{title}_{pubdate:yyyy-MM-dd}" "https://www.bilibili.com/video/BV1vL411H7Qr"
3. 批量内容抓取
# 获取指定UP主全部公开投稿（按上传时间排序）
./BBDown --space "35791394" --sort-by upload --limit 50
# 下载课程所有章节（cheese类型）
./BBDown --cheese "ep321098" --all-pages
# 同步收藏夹（支持增量更新）
./BBDown --fav "7890123" --only-new
增强功能实践
弹幕与字幕嵌入
使用 --download-danmaku 和 --download-subtitle 参数可分别导出 XML 格式弹幕和 SRT 字幕文件。部分播放器（如 VLC、MPV）支持加载外部弹幕轨道；亦可通过 ffmpeg 将字幕硬编码进视频：
ffmpeg -i input.mp4 -vf "subtitles=subtitle.srt" -c:a copy output_with_sub.mp4
会员内容访问
支持扫码登录或 Cookie 注入方式访问付费内容：
# 触发二维码登录流程
./BBDown --login
# 使用已有登录态（Cookie字符串需包含 SESSDATA）
./BBDown --cookie "SESSDATA=xxx; bili_jct=yyy;" "https://www.bilibili.com/bangumi/play/ep123456"
性能调优策略
针对不同网络环境与硬件条件，可组合启用以下优化项：
--multi-thread --threads 8：启用多线程分片下载（默认关闭）--use-aria2c：交由 aria2 并行管理 HTTP 请求（需系统已安装 aria2c）--tv或--app：切换至 TV 端或 APP 端接口，提升特定内容成功率--proxy "http://127.0.0.1:7890"：配置代理链路以绕过地域限制
工程化集成方案
配置驱动工作流
生成默认配置模板后，可集中管理全局行为：
./BBDown --gen-config
# 编辑生成的 bbdown.json：
{
"quality": "1080P",
"output": "./archive/",
"subtitle": true,
"danmaku": false,
"pattern": "{bvid}_{title}"
}
后续命令自动读取配置，无需重复传参：./BBDown --config bbdown.json "BV1xx4y1v7Sj"
API服务模式
启动轻量 HTTP 接口供其他系统调用：
./BBDown --api-server --port 8080 --cors
# POST /download
curl -X POST http://localhost:8080/download \
-H "Content-Type: application/json" \
-d '{"url":"BV1AB4y1W7Zx","quality":"4K"}'
Docker 化部署示例
利用官方 Dockerfile 构建容器镜像，实现环境隔离与一键分发：
docker build -t bbdown-cli .
docker run -v $(pwd)/output:/workspace/output bbdown-cli \
--output "/workspace/output" "BV1CD4y1X7Yz"
架构概览
BBDown 采用分层设计：
- Fetcher 层：按内容类型划分（Normal/Bangumi/Cheese/Space/Fav），各自封装对应 API 调用逻辑
- Parser 层：统一解析 Protobuf 响应体，提取标题、封面、流地址、分P索引等结构化字段
- Downloader 层：抽象下载器接口，支持内置 HttpClient 与 aria2c 插件两种实现
- Muxer 层：协调 ffmpeg/MP4Box 工具完成音视频合成、字幕嵌入、HDR 处理等后期任务
合规使用提醒
本工具仅面向个人学习、研究及非商业用途。请严格遵守《著作权法》及平台用户协议，不得用于传播盗版、规避版权保护措施或大规模爬取未授权内容。尊重创作者权益，是技术理性的重要体现。
