NcatBot 文档

外观

Bilibili 适配器

约 1520 字大约 5 分钟

2026-03-19

Bilibili 平台适配器完整指南 — 扫码登录、凭据持久化、直播/私信/评论/动态多数据源。

Quick Reference

属性值
适配器名称bilibili
平台标识bilibili
协议bilibili-api-python (WebSocket + REST Polling)
类BilibiliAdapter
导入from ncatbot.adapter.bilibili import BilibiliAdapter
额外依赖bilibili-api-python >= 17.0.0（自动安装）
# 最小配置（首次运行会弹出扫码）
adapters:
  - type: bilibili
    platform: bilibili
    enabled: true
    config:
      live_rooms: [12345]

CLI 初始化配置

通过 ncatbot init 或 ncatbot adapter 进入适配器管理并选择 Bilibili 时，CLI 会调用 Bilibili 适配器的交互式配置钩子：

  1. 询问是否扫码登录获取凭据
  2. 若选择扫码：立即弹出二维码，扫码成功后凭据自动写入配置，跳过手动输入 sessdata 等字段
  3. 若选择不扫码：逐项输入 sessdata / bili_jct / buvid3 / dedeuserid / ac_time_value（留空则启动时再扫码）
  4. 无论哪种方式，之后继续配置直播间 ID 和是否监听私信

💡 推荐选择扫码——无需从浏览器复制 Cookie，且凭据会自动持久化到 config.yaml。

扫码登录

Bilibili 适配器使用二维码扫码登录获取凭据。

首次登录流程

  1. 启动 Bot 时，若 config.yaml 中未配置凭据（sessdata 为空），自动触发扫码登录
  2. 终端显示压缩的 ASCII 二维码，同时保存 PNG 图片到临时目录
==================================================
  Bilibili 扫码登录 (第 1/3 次)
==================================================
█▀▀▀▀▀█ ▀▄█▀ █▀▀▀▀▀█
█ ███ █ █▄▀  █ ███ █
...
  二维码图片: C:\Users\...\Temp\ncatbot_bilibili_qr.png
  请使用 Bilibili APP 扫描上方二维码
==================================================
  1. 使用 Bilibili 手机 APP 扫描二维码并确认
  2. 登录成功后，凭据自动写回 config.yaml

凭据持久化

登录成功后，sessdata、bili_jct、dedeuserid、ac_time_value 会自动保存到 config.yaml 的 bilibili 适配器配置中。下次启动时直接使用已保存的凭据，无需重复扫码。

如果凭据过期，适配器会自动检测并重新触发扫码登录。

手动填写凭据

也可以跳过扫码，直接在配置中填入 Cookie 凭据（从浏览器开发者工具获取）：

config:
  sessdata: "your_sessdata_here"
  bili_jct: "your_bili_jct_here"
  dedeuserid: "your_uid_here"
  ac_time_value: "your_ac_time_value_here"

配置项详解

adapters:
  - type: bilibili
    platform: bilibili
    enabled: true
    config:
      # 认证凭据（扫码后自动填入，也可手动配置）
      sessdata: ""
      bili_jct: ""
      buvid3: ""
      dedeuserid: ""
      ac_time_value: ""

      # 数据源 — 直播间
      live_rooms:              # 监听的直播间房间号列表
        - 12345
        - 67890

      # 数据源 — 私信
      enable_session: false    # 是否启用私信监听

      # 数据源 — 视频评论
      comment_watches:         # 监听评论的视频/动态列表
        - id: "BV1xx411c7xx"
          type: video

      # 数据源 — 用户动态
      dynamic_watches:         # 监听动态的用户 UID 列表
        - uid: 12345678

      # 数据源 — 动态主页（多 UP 主合并轮询）
      dynamic_page_watches:    # 通过动态主页一次性监听的用户 UID 列表
        - uid: 87654321
      dynamic_page_poll_interval: 180.0 # 动态页轮询间隔（秒，默认 3 分钟）

      # 轮询间隔
      session_poll_interval: 6.0    # 私信轮询间隔（秒）
      comment_poll_interval: 30.0   # 评论轮询间隔（秒）
      dynamic_poll_interval: 600.0  # 动态轮询间隔（秒）

      # 连接重试
      max_retry: 5             # 最大重连次数
      retry_after: 1.0         # 重连初始延迟（秒）

配置项说明

配置项类型默认值说明
sessdatastring""Bilibili SESSDATA Cookie
bili_jctstring""Bilibili CSRF Token
buvid3string""设备指纹标识
dedeuseridstring""用户 UID
ac_time_valuestring""账号时间戳凭据
live_roomslist[int][]监听的直播间房间号
enable_sessionboolfalse启用私信监听
comment_watcheslist[]监听评论的视频列表（id + type）
dynamic_watcheslist[]监听动态的用户列表（uid）
dynamic_page_watcheslist[]通过动态主页监听的用户列表（uid）
dynamic_page_poll_intervalfloat180.0动态页轮询间隔（秒）
session_poll_intervalfloat6.0私信轮询间隔（秒）
comment_poll_intervalfloat30.0评论轮询间隔（秒）
dynamic_poll_intervalfloat600.0动态轮询间隔（秒）
max_retryint5连接断开后最大重试次数
retry_afterfloat1.0重连初始延迟（秒）

四种数据源

Bilibili 适配器通过 SourceManager 同时管理四种独立的数据源：

1. 直播间弹幕（WebSocket）

通过 WebSocket 实时接收直播间事件：弹幕、SC（SuperChat）、礼物、上舰、点赞等。

live_rooms:
  - 12345    # 房间号
  - 67890

可通过 API 动态添加/移除监听的直播间。

2. 私信（REST Polling）

定时轮询 Bilibili 私信接口，获取新消息。

enable_session: true
session_poll_interval: 6.0   # 每 6 秒轮询一次

3. 视频评论（REST Polling）

定时轮询指定视频的评论区，获取新回复。

comment_watches:
  - id: "BV1xx411c7xx"
    type: video
comment_poll_interval: 30.0  # 每 30 秒轮询一次

4. 用户动态（REST Polling）

定时轮询指定用户的动态列表，基于时间戳增量检测新发布/被删除的动态。支持图文、视频、专栏、音乐、直播推荐、转发等所有动态类型。

dynamic_watches:
  - uid: 12345678       # 用户 UID
dynamic_poll_interval: 600.0  # 每 600 秒（10 分钟）轮询一次

可通过 API 动态添加/移除监听的用户。

5. 动态主页（REST Polling，多 UP 主合并）

通过 Bilibili 动态主页 API 批量轮询多个关注用户的最新动态，一次 API 调用覆盖所有订阅 UP 主，效率优于逐个 dynamic_watches 轮询。不检测动态删除。

dynamic_page_watches:
  - uid: 12345678
  - uid: 87654321
dynamic_page_poll_interval: 180.0  # 每 3 分钟轮询一次

添加前会自动关注目标 UP 主（已关注或关注自己时跳过），确保其动态出现在主页中。 可通过 api.bilibili.add_dynamic_page_watch / remove_dynamic_page_watch 在运行时动态调整。

常见问题

问题原因解决方案
扫码登录超时二维码约 3 分钟过期过期后自动重新生成（最多 3 次）
凭据失效Cookie 过期（通常几天到几周）适配器自动检测并触发重新扫码
直播间无事件房间号错误或主播未开播确认房间号正确；部分事件仅在开播时产生
依赖安装失败bilibili-api-python 安装问题手动 pip install bilibili-api-python>=17.0.0
私信无响应enable_session 未开启设置 enable_session: true

示例

  • examples/bilibili/01_hello_world/ — 最简 Bilibili Bot
  • examples/bilibili/02_live_room/ — 直播间弹幕处理
  • examples/bilibili/03_private_message/ — 私信收发
  • examples/bilibili/04_comment/ — 视频评论处理
  • examples/bilibili/05_live_manager/ — 直播间管理
  • examples/bilibili/06_dynamic/ — 动态页多 UP 主合并监听

延伸阅读

版权归属：MI

许可证：署名 4.0 国际 (CC-BY-4.0)

© 2025-2026 NcatBot