CLI Reference

命令行参数详解 (CLI Reference)

本文档列出 BBDown 主下载命令的所有参数选项、语法规范、分类详解以及进程退出码定义。

---

命令行语法

BBDown [选项] <URL或标识符>

<URL或标识符> 支持的输入格式：

• 普通视频：https://www.bilibili.com/video/BV1qt4y1X7TW、BV1qt4y1X7TW、av170001
• 番剧/国创/电影/电视剧：https://www.bilibili.com/bangumi/play/ss33073、ss33073、ep12345
• 课程/课堂 (Cheese)：https://www.bilibili.com/cheese/play/ep12345
• UP主空间：https://space.bilibili.com/163637592
• 播单/媒体列表：https://www.bilibili.com/medialist/play/ml123456
• 收藏夹：https://space.bilibili.com/163637592/favlist?fid=123456

---

完整参数汇总大表

短选项	长选项	类型/默认值	说明
-t	--use-tv-api	bool (false)	使用 TV 端解析模式（通常无平台水印）
-a	--use-app-api	bool (false)	使用移动端 APP 解析模式
	--use-intl-api	bool (false)	使用国际版（东南亚/泰国等）解析模式
-I	--only-show-info	bool (false)	仅解析并展示媒体流与分 P 信息，不下载
-i	--interactive	bool (false)	交互式命令行菜单挑选清晰度与音视频流
	--show-all	bool (false)	展示所有分 P 标题与元数据
	--hide-streams	bool (false)	控制台隐藏可用音视频流详情列表
-p	--select-page	string ("")	分 P 选择表达式（如 1,3,5-10,ALL,LAST）
-q	--dfn-priority	string?	视频画质优先级列表（逗号分隔）
-e	--encoding-priority	string?	视频与音频编码优先级列表（逗号分隔）
	--video-ascending	bool (false)	视频流升序排列（最小文件体积优先）
	--audio-ascending	bool (false)	音频流升序排列（最小文件体积优先）
	--video-only	bool (false)	仅下载视频流（不下载音频且不混流）
	--audio-only	bool (false)	仅下载音频流（不下载视频且不混流）
	--danmaku-only	bool (false)	仅下载弹幕文件
	--cover-only	bool (false)	仅下载封面图片
	--sub-only	bool (false)	仅下载外挂字幕文件
-d	--download-danmaku	bool (false)	开启弹幕下载（默认保存为 XML）
	--download-danmaku-formats	string?	弹幕格式列表（如 xml,protobuf）
	--danmaku-filter	string?	弹幕关键词黑名单过滤（逗号分隔）
	--danmaku-filter-user	string?	弹幕发送者 midHash 黑名单过滤（逗号分隔）
	--comments	bool (false)	同时下载视频评论区，保存为 JSON
	--allow-preview	bool (false)	允许下载充电专属视频的试看片段
	--decrypt-drm	bool (false)	启用原生 C# CDM 尝试解密 DRM 保护视频
	--key	string?	手动指定 DRM 解密 Key（16进制字符串）
	--kid	string?	手动指定 DRM 密钥 ID（16进制字符串）
	--wvd-path	string ("")	手动指定 device.wvd 文件路径
	--mp4decrypt-path	string ("")	手动指定 mp4decrypt 可执行文件路径
	--skip-mux	bool (false)	跳过混流步骤，保留单独的音视频源文件
	--simply-mux	bool (false)	精简混流（混流时不注入视频描述、UP主等元数据）
	--skip-subtitle	bool (false)	跳过字幕下载
	--skip-cover	bool (false)	跳过封面下载
	--skip-ai	bool (true)	跳过 AI 生成字幕下载（默认跳过）
-c	--cookie	string ("")	设置网页端 Cookie（含 SESSDATA 等）
	--access-token	string ("")	设置 TV / APP 端 Access Token
-F	--file-pattern	string ("")	单 P 自定义输出文件名模板
-M	--multi-file-pattern	string ("")	多 P 自定义输出文件名模板
	--work-dir	string ("")	设置下载产物输出的工作目录
	--config-file	string?	指定本地配置文件路径（默认读取 BBDown.config）
	--multi-thread	bool (true)	开启多线程并发分片下载（传 false 可关闭）
	--thread-segment-size	int (20)	多线程分片大小（单位：MB）
	--retry-count	int (3)	网络请求失败最大重试次数
	--retry-delay	int (3000)	重试基础退避间隔（毫秒）
	--delay-per-page	int (0)	多分 P 之间的请求间隔时间（秒）
	--muxer-timeout	int (30)	混流工具最大执行超时时长（分钟）
	--ffmpeg-path	string ("")	手动指定 ffmpeg 可执行文件路径
	--mp4box-path	string ("")	手动指定 mp4box 可执行文件路径
	--use-mp4box	bool (false)	使用 MP4Box 代替 FFmpeg 进行混流
	--use-aria2c	bool (false)	调用外部 aria2c 引擎进行下载
	--aria2c-path	string ("")	手动指定 aria2c 可执行文件路径
	--aria2c-args	string ("")	传给 aria2c 的额外命令行参数
	--force-http	bool (false)	媒体流强制使用 HTTP 协议替代 HTTPS
	--insecure	bool (false)	跳过 SSL/TLS 证书有效性校验（抓包调试用）
	--upos-host	string ("")	手动指定 CDN / UPOS 流媒体主机域名
	--force-replace-host	bool (true)	强制将边缘 PCDN 域名替换为骨干 CDN 域名
	--allow-pcdn	bool (false)	允许使用边缘 PCDN 节点（不自动替换）
	--save-archives-to-file	bool (false)	在工作目录维护 archives.txt 记录已下载 aid
	--notify-webhook	string?	下载完成后发送 HTTP POST 结果通知
	--language	string ("")	设置混流音频流的语言代码（如 chi、jpn、eng）
-u	--user-agent	string ("")	指定自定义 User-Agent 请求头
	--debug	bool (false)	输出详细调试日志（含请求头与异常堆栈）

---

进程退出码 (Exit Codes)

BBDown 在执行完毕后会返回明确的系统退出码，便于在 Shell 脚本、CI/CD 或定时任务中进行自动化分支判断：

退出码	含义	常见原因
0	执行成功	视频成功下载并混流完成；或正常完成信息解析；或用户主动按 Ctrl+C 取消
1	常规错误	视频 URL 无法识别、网络连接超时多次失败、接口返回业务错误（如未登录 404）
2	权限不足 / 充电专属	目标为充电专属视频且未加 --allow-preview；或无购买权限
3	外部工具缺失	未找到可用的 FFmpeg / MP4Box / aria2c 可执行文件