bili-down-cli

v1.0.0

Published

a month ago

B站视频下载 CLI 工具 — 支持各种 URL 类型的视频/音频/弹幕/字幕下载

0High
0Medium
0Low

iblq

bilibili download video cli b站下载

bilibili-download-cli

一个面向 AI Agent 的 Bilibili 内容下载 CLI。它提供稳定、可组合的命令行接口，支持视频、番剧、收藏夹、UP 主空间、合集、课程、音频、弹幕、字幕和封面等内容。

npm 包名是 bili-down-cli，安装后的短命令为 bili-down。

为什么适合 AI Agent

命令和参数适合被 Agent 生成、组合和自动化执行。
支持单个资源、列表资源和 YAML 批量任务。
支持登录、清晰度、分页、排序、数量限制、音频、弹幕、字幕和封面等显式参数。
通过下载记录和 sync 避免重复下载，适合增量任务。
项目内置可直接复用的 skill：skills/bili-down/SKILL.md。

给 AI Agent 的快速接入

将项目中的 skill 复制到 Agent 的 skills 目录：

cp -R skills/bili-down ~/.claude/skills/bili-down

然后在项目根目录安装并构建：

npm install
npm run build
npm link

Agent 可直接调用：

bili-down down BV1Ra4y177SE
bili-down down 35579222 --order stow --limit 50
bili-down batch ./templates/batch-example.yml
bili-down login --qr

使用高画质内容通常需要先登录；音视频合并需要安装 FFmpeg。

安装

从 npm 安装

npm install -g bili-down-cli
bili-down --help

从源码安装

git clone <your-repository-url>
cd bilibili-download-cli
npm install
npm run build
npm link

要求：Node.js >= 18。FFmpeg 为可选依赖，可用于音视频合并：

brew install ffmpeg

命令速查

# 下载视频、番剧、收藏夹、UP 主空间等
bili-down down <BV号或URL>

# 搜索 UP 主并下载
bili-down search <关键词>

# 批量下载
bili-down batch ./tasks.yml

# 登录管理
bili-down login --qr
bili-down login --status

# 配置和下载记录
bili-down config list
bili-down repo list
bili-down sync

下载选项

bili-down down [input] [options]

-q, --quality <qn>   清晰度：8K/HDR/4K/1080P60/1080P+/1080P/720P60/720P/480P/320P
-p, --page <pages>   分P，例如 1,3,5 或 all
    --order <order>  列表排序：pubdate/click/stow
    --limit <n>      限制下载数量
    --no-merge       仅下载，不合并音视频
    --audio-only     仅下载音频
    --danmu          下载弹幕
    --subtitle       下载字幕
    --cover          下载封面
    --format <type>  格式：m4s/flv/mp4

支持的输入

| 类型 | 示例 | | --- | --- | | BV / AV | BV1Ra4y177SE / av123456 | | b23 短链 | https://b23.tv/xxx | | 番剧 | ss12345 / ep12345 | | UP 主空间 | https://space.bilibili.com/xxx/video | | 收藏夹 | https://space.bilibili.com/xxx/favlist?fid=xxx | | 合集 | https://space.bilibili.com/xxx/channel/collectiondetail?sid=xxx | | 课程 | https://www.bilibili.com/cheese/play/ssxxx | | 音频 | au12345 / am12345 | | 图文专栏 | https://www.bilibili.com/read/cv12345 |

纯数字输入会按 UID 处理，例如：

bili-down down 35579222 --order stow --limit 50

批量任务

tasks:
  - url: https://space.bilibili.com/8741628/favlist?fid=70263328
    stop:
      - [{ left: "page", operator: ">", right: "10" }]
    download:
      - [{ left: "_", operator: "!", right: "downloaded" }]
      - [{ left: "cTime", operator: ">", right: "2024-01-01" }]
    settings:
      startPage: 1

条件支持已下载状态、页码、BV 号、发布时间、收藏时间、标题正则、时长、播放量、收藏量和弹幕数等。完整示例见 templates/batch-example.yml，完整 Agent 操作说明见 skills/bili-down/SKILL.md。

数据目录与个人配置

默认配置随项目和 npm 包提供，位于 config/defaults.yml（包括默认 4K、并发数、命名格式等）。运行时会先加载该文件，再读取用户目录 ~/.bilibili-download/config.yml 覆盖其中的同名项；仓库和 npm 包不读取或保存项目目录内的个人配置：

配置、Cookie 与指纹：~/.bilibili-download/config.yml、cookies.json、fingerprint.json
默认下载目录：~/.bilibili-download/downloads/（可用 download.savePath 修改）
下载记录：~/.bilibili-download/cache/record.json（可用 cache.recordPath 修改）

使用 bili-down config set <配置项> <值> 会自动创建并更新 ~/.bilibili-download/config.yml。例如，将外部 .lfile-video-mix-cache.json 设为同步源：

bili-down config set cache.syncSourcePath /path/to/.lfile-video-mix-cache.json
bili-down sync

也可直接在 ~/.bilibili-download/config.yml 写入：

cache:
  syncSourcePath: /path/to/.lfile-video-mix-cache.json

环境变量 BILI_DOWNLOAD_SAVE_PATH、BILI_DOWNLOAD_RECORD_PATH 和 BILI_DOWNLOAD_SYNC_SOURCE_PATH 可覆盖对应配置。请勿将 Cookie、下载内容或个人配置提交到公开仓库。

开发

npm run dev       # 本地运行
npm run build     # 构建
npm test          # 测试
npm run typecheck # 类型检查

发布 npm 包

推送与 package.json 版本一致的标签（例如 v1.0.0）会触发 GitHub Actions 发布。工作流使用 npm Trusted Publishing（OIDC），不需要在 GitHub 保存 npm 发布 token。

首次启用时，需在 npmjs.com 的包设置中添加 Trusted Publisher：GitHub 用户 iblq、仓库 bilibili-download-cli、工作流文件名 publish.yml，并授权 npm publish。随后创建并推送标签：

git tag v1.0.0
git push origin v1.0.0

许可证

Apache-2.0