NcatBot 文档

外观

Bilibili 适配器

约 968 字大约 3 分钟

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]

扫码登录

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

      # 轮询间隔
      session_poll_interval: 6.0    # 私信轮询间隔（秒）
      comment_poll_interval: 30.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）
session_poll_intervalfloat6.0私信轮询间隔（秒）
comment_poll_intervalfloat30.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 秒轮询一次

常见问题

问题原因解决方案
扫码登录超时二维码约 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/ — 直播间管理

延伸阅读

版权归属：huan-yp

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

© 2025 NcatBot