Bilibili Subtitle CLI

全局命令行工具：输入 Bilibili 视频链接、b23.tv 短链、BV 号或 av 号，提取视频已有的字幕轨。

安装

npm install -g @supercakex/bilibili-subtitle-tool

需要 Node.js 20.12 或更高版本。

配置凭证

在 Chrome 登录 Bilibili，打开开发者工具：

Application → Cookies → https://www.bilibili.com → SESSDATA

复制 SESSDATA 的 Value，不要复制 SESSDATA= 或其他 Cookie。

可配置为系统环境变量：

export BILIBILI_SESSION_TOKEN="your_sessdata_value"

也可以使用系统用户配置目录下的 config.yaml。查看当前设备的准确路径：

bili-subtitle config-path

配置内容：

token: "your_sessdata_value"

默认路径：

• macOS：~/Library/Application Support/bilibili-subtitle-tool/config.yaml
• Linux：${XDG_CONFIG_HOME:-~/.config}/bilibili-subtitle-tool/config.yaml
• Windows：%APPDATA%\bilibili-subtitle-tool\config.yaml

建议限制配置文件权限：

chmod 600 "$(bili-subtitle config-path)"

为兼容临时项目环境，也可以在执行命令的当前目录创建 .env：

BILIBILI_SESSION_TOKEN=your_sessdata_value

读取优先级：

1. 系统环境变量 BILIBILI_SESSION_TOKEN
2. 用户配置目录的 config.yaml
3. 当前目录的 .env

不要公开或提交任何包含 SESSDATA 的配置文件。

使用

查看所有命令和参数：

bili-subtitle --help

查看版本：

bili-subtitle --version

直接传入 BV 号：

bili-subtitle BV1hBE96QET1

直接传入视频链接：

bili-subtitle "https://www.bilibili.com/video/BV1hBE96QET1/"

支持自动跟随 b23.tv 重定向并提取目标 BV 号：

bili-subtitle "https://b23.tv/41lQxCo"

显示 HH:MM:SS 时间戳：

bili-subtitle BV1hBE96QET1 --timestamp

多分 P：

bili-subtitle BV1xx411x7xx --page 2

也可以直接使用链接中的 ?p=2。

供程序或 Agent 读取的纯 JSON：

bili-subtitle BV1hBE96QET1 --json --timestamp

安装 Agent Skill

输出一段可直接交给 AI Agent 的 Skill 安装指令：

bili-subtitle skill

输出包含 SKILL.md、安全规则和错误处理规则。该命令只输出安装说明，不请求 Bilibili，也不会输出凭证。

JSON 状态

• ok：成功获取字幕
• no_subtitle：视频存在，但没有可用字幕轨
• credentials_missing：环境变量、config.yaml 和 .env 均未配置凭证
• credentials_invalid：SESSDATA 已过期或无效
• short_link_error：b23.tv 短链无法解析或目标不是 Bilibili 视频
• error：其他错误，查看 error 字段

本工具只提取 Bilibili 已提供的字幕轨，不进行语音识别，也不会为无字幕视频生成字幕。