快速开始#

1. 在 src/config/animeConfig.ts 里填好你的 B 站数字 UID：

   1
   providers: {
   2
     bilibili: {
   3
       enable: true,
   4
       vmid: "3546912602982411",   // 就是 space.bilibili.com/<这一串>
   5
       ...
   6
     },
   7
   }
   

2. 执行同步，生成快照：

   1
   pnpm anime:sync --provider bilibili
   

3. 正常 pnpm build。页面会读那份快照。

配置#

src/config/animeConfig.ts：

接口#

1
GET https://api.bilibili.com/x/space/bangumi/follow/list
2
    ?type=1                固定 1（追番；2 是追剧）
3
    &follow_status=<1|2|3> 1 想看 / 2 在看 / 3 看过
4
    &vmid=<UID>
5
    &ps=<10..50>           单页大小
6
    &pn=<1..>              页码

请求头：

1
User-Agent: 合规桌面浏览器 UA
2
Referer:    https://space.bilibili.com/
3
Cookie:     SESSDATA=<...>;    ← 仅当追番列表设为私密时才需要

响应形如：

1
{
2
  "code": 0,
3
  "message": "0",
4
  "data": {
5
    "list": [
6
      {
7
        "media_id": 28228367,
8
        "season_id": 34209,
9
        "title": "间谍过家家",
10
        "cover": "http://i0.hdslb.com/bfs/bangumi/image/....jpg",
11
        "total_count": 25,
12
        "progress": "看到第12话",
13
        "rating": { "score": 9.7 },
14
        "evaluate": "为了潜入名校……",
15
        "publish": { "pub_time": "2022-04-09 23:00:00" },
16
        "styles": ["搞笑", "日常", "漫画改"]
17
      }
18
    ],
19
    "total": 45
20
  }
21
}

1
BILI_SESSDATA="你的 SESSDATA"

封面防盗链#

B 站图床（hdslb.com）对外站有严格的 Referer 校验，直接把 URL 贴到页面里 大概率是破图。cover.mode: "local" 时同步脚本会把封面下载到：

1
public/assets/anime/covers/bili_<season_id或media_id>.<ext>

下载时会给 URL 追加 B 站 CDN 自己的处理参数 @220w_280h.webp： 真正干活的是 B 站的图片服务，本地不跑任何图片转码（不依赖 sharp）， 拿到的就是裁好尺寸的 WebP，通常只有十几 KB。

文件扩展名从文件头魔数判断（其次是 content-type，最后兜底 webp）： B 站 CDN 加了 @...webp 之后返回的仍可能是 JPEG，光看后缀会写错扩展名。

下载失败会退回远程 URL，不会让整次同步失败。

remote 模式则只追加 CDN 参数、保留远程地址； none 模式不使用封面，卡片显示渐变占位。

安全#

落盘前会扫描快照内容，命中 SESSDATA / cookie: / authorization: / access_token / refresh_token / csrf 任一模式就中止写入。 凭据只该存在于 process.env，绝不该出现在要提交进 Git 的快照里。

写入是原子的：先写临时文件再 rename。同步中途被打断时， 线上那份快照仍然是完整的。

为什么不在构建期抓取#

astro build 全程不碰网络，这是刻意的：

• 构建环境常常没有外网，把网络请求放进构建会变得很脆；
• B 站挂了不应该导致博客发布失败；
• 「今天部署的产物」和「昨天部署的产物」应当可复现。

代价是数据会停留在最后一次同步的时刻，所以 snapshot.staleAfterDays 到期后会在构建日志里提醒你。

快照格式#

src/data/anime-snapshots/bilibili.json：

1
{
2
  "schemaVersion": 1,
3
  "provider": "bilibili",
4
  "fetchedAt": "2026-10-06T08:35:03.419Z",
5
  "accountRef": "3546912602982411",
6
  "items": [
7
    {
8
      "title": "Lycoris Recoil",
9
      "status": "completed",
10
      "rating": 9.8,
11
      "year": "2022",
12
      "genres": ["Action", "Slice of Life"],
13
      "progress": { "watched": 12, "total": 12 },
14
      "cover": "/assets/anime/covers/bili_12345.webp",
15
      "link": "https://www.bilibili.com/bangumi/media/md28338623",
16
      "description": "…",
17
      "studio": "Aniplex",
18
      "identity": { "provider": "bilibili", "seasonId": "12345", "sourceId": "28338623" }
19
    }
20
  ]
21
}

解析时也兼容裸数组格式（早期格式 / 手工拷贝），见 parseAnimeSnapshot()。

数据校验#

外部接口返回的内容一律视为不可信输入，src/utils/anime/normalize.ts 会洗一遍：

• 状态做白名单（并容忍 onhold / ON_HOLD 这类写法）；
• 评分夹到 0 ~ 10，保留一位小数；
• 图片只放行 https:// 与站内 / 开头的路径 —— 这条是安全边界而不是格式偏好， javascript: / data: 一旦进了 <img src> 就是可执行的注入点；
• 简介去掉 HTML 标签与实体，压缩空白，截断到 500 字；
• 题材去重、去 #、单个限长 30 字、最多 6 个。

CLI#

1
pnpm anime:sync                     # 按配置里的 source.provider 决定同步谁
2
pnpm anime:sync --provider bilibili # 指定 provider
3
pnpm anime:sync --if-stale          # 只在快照过期时才同步（适合放进 CI 定时任务）

退出码：provider 失败 → 1；「没配置」「保留了旧快照」→ 0 （不让「有意保留旧档」这种事中断部署流水线）。

关联文件#

配置#

src/config/animeConfig.ts 的 providers.bilibili.coins：

maxItems 在读取侧才截断，快照里始终留全量数据。 所以想多显示几条，改配置重新构建即可，不用重新同步。

接口#

1
GET https://api.bilibili.com/x/space/coin/video?vmid=<UID>&pn=<页>&ps=<每页>
2

3
→ { "code": 0, "data": [ ...视频对象 ] }

三个和追番接口不一样的地方，都踩过：

1. data 是裸数组，不是 { list, total }。没有 total 可比对， 只能靠「这一页返回的条数够不够」判断有没有下一页。
2. 不需要登录，返回的是用户公开的投币记录。 前提是在 B 站「隐私设置 → 投币视频」里设为公开， 否则返回 code 53013（和追番列表私密时是同一个码）。
3. pn 参数实际上被忽略 —— 实测两个账号，pn=1 与 pn=2 返回完全相同的列表。

第 3 条会直接坑到分页逻辑：如果照常 pn++ 循环，就会无限翻同一页。 所以同步脚本用「本页有没有新 bvid」来兜底：

1
const fresh = list.filter((item) => item?.bvid && !seen.has(item.bvid));
2
if (fresh.length === 0) break;   // 分页没生效，或者已经到底了

配合「返回条数不足一页就停」，两种行为（分页生效 / 不生效）都能正确收敛。

排序依据#

按 time（我投币的时间） 倒序，而不是视频的 pubdate。

这两个字段差得很远：完全可能今天给一个五年前的老视频投币。 按发布时间排的话它会沉到列表底部，而「最近投币」看的就是我什么时候投的。

接口里的对应关系：

页面上这两个币数都会显示：封面左上角的 ×2 是我投的， 卡片底部计数行里的「投币」是整个视频的总数。

封面#

和追番封面同一套机制（同一个图床、同一个 Referer 校验、同一个魔数嗅探）， 只有目标目录和尺寸不同：

1
public/assets/bilibili/covers/coin_<bvid>.<ext>

尺寸参数用 @480w_270h.webp（16:9），因为视频封面是横版； 追番封面是竖版海报，用的是 @220w_280h.webp。

快照格式#

src/data/anime-snapshots/bilibili-coins.json：

1
{
2
  "schemaVersion": 1,
3
  "provider": "bilibili",
4
  "kind": "coins",
5
  "fetchedAt": "2026-10-06T09:01:10.796Z",
6
  "accountRef": "3546912602982411",
7
  "items": [
8
    {
9
      "bvid": "BV1CRahzZEmy",
10
      "title": "……",
11
      "cover": "/assets/bilibili/covers/coin_BV1CRahzZEmy.webp",
12
      "author": { "mid": "18026414", "name": "……" },
13
      "duration": 245,
14
      "publishedAt": "2025-09-05T10:57:37.000Z",
15
      "coinedAt": "2026-09-30T16:35:33.000Z",
16
      "coins": 2,
17
      "stats": { "view": 5269096, "danmaku": 33145, "like": 248137, "coin": 239450, "favorite": 55642 },
18
      "category": "翻唱",
19
      "link": "https://www.bilibili.com/video/BV1CRahzZEmy/"
20
    }
21
  ]
22
}

同样兼容裸数组格式，见 parseCoinSnapshot()。

数据校验#

src/utils/bilibili/normalize.ts 做的事和追番那份类似，另外多两条：

• BV 号必须匹配 ^BV[1-9A-HJ-NP-Za-km-z]{10}$ —— 它既是去重主键， 也是拼链接的唯一依据，不合法就丢掉整条。
• 外链限定 B 站域名。link 走白名单校验， 只放行 bilibili.com 与 b23.tv，免得接口被篡改时把访客引到站外。

关联文件#

⚠️ 这一块必须配 SESSDATA#

勋章墙接口在 live 域下，不在 api.bilibili.com：

1
GET https://api.live.bilibili.com/xlive/web-ucenter/user/MedalWall?target_id=<你的mid>
2
Cookie: SESSDATA=<...>;

匿名请求一律返回：

1
{ "code": -101, "message": "账号未登录", "ttl": 1 }

这个和收藏夹那边完全不同 —— 收藏夹是「列目录要登录、读内容不用」， 而勋章墙是整个接口都校验登录态。换域名、补参数、加 buvid3 Cookie、 加 WBI 签名，都绕不过去（都实测过）。所以这块没有免凭据的用法。

配置方式：在项目根目录建 .env（已在 .gitignore 里）：

1
BILI_SESSDATA="你的 SESSDATA"

怎么取：浏览器登录 B 站 → F12 → Application → Cookies → https://www.bilibili.com → 找到 SESSDATA，复制它的值。

没配凭据时同步脚本会跳过并且不发任何请求，页面上显示的是 「怎么配」的提示而不是一片空白。

⚠️ SESSDATA 等同于你的登录态，泄漏了别人就能以你的身份操作。 它只应该待在 .env 里，绝不要提交进 Git —— 同步脚本落盘前会扫描 SESSDATA / cookie: / access_token 之类的敏感串，命中就中止写入。

配置#

src/config/animeConfig.ts 的 providers.bilibili.medals：

排序#

佩戴中 → 等级从高到低 → 亲密度从高到低。

佩戴中的排最前是因为那是用户当前的选择，B 站自己的勋章墙也是这么排的。

配色#

接口给了两套颜色字段，取的时候新的优先：

新版才是 B 站当前界面真正在用的配色（含透明度），所以优先用； 老版按 #RRGGBB 转出来兜底。两套都没有时退回主题色， 保证任何情况下都不会渲染出一枚看不见的勋章。

字段最终落到 colorStart / colorEnd / colorBorder / colorText， 页面直接塞进 CSS 变量（--medal-start 等）—— 每枚勋章颜色都不同， 用 Tailwind 类名表达不了。

关联文件#

最麻烦的一点：没有「我拥有哪些收藏集」的接口#

B 站的收藏集接口全是按 act_id（单个收藏集）设计的：

asset_bag 返回的 owned_item_cnt / total_item_cnt 就是「我拥有几张 / 一共几张」， 但它必须指定 act_id。App 里那个「背包」页面也是先选收藏集再展示的。

也就是说，「找出我拥有哪些收藏集」只能把整个目录逐个查一遍。 实测目录有 1500+ 个收藏集 —— 一千多次请求。

⚠️ 实测这么做会触发 B 站风控：扫描完约 1561 个之后， 该系列接口开始返回 412 Precondition Failed，且几分钟内不会恢复。 这不是理论风险，是实际发生过的。

所以设计成两条路#

首次必须跑一次全量扫描；之后日常同步走刷新就够了，又快又不会触发风控。

1
# 第一次：把所有收藏集找出来（慢，且可能被风控，偶尔跑一次即可）
2
pnpm anime:sync --provider bilibili --scan-collections
3

4
# 之后：只刷新已知的那些
5
pnpm anime:sync --provider bilibili

配置#

src/config/animeConfig.ts 的 providers.bilibili.collections：

数据流#

1
1. 目录      GET x/vas/dlc_act/act/list?scene=1&site=<偏移>       （全量扫描才走）
2
                → { data: { list: [{ act_id, act_name, act_pic, lottery_id, ... }], is_more, site } }
3

4
2. 持有情况  GET x/vas/dlc_act/asset_bag?act_id=&lottery_id=&ruid=
5
                → { data: { owned_item_cnt, total_item_cnt, item_list, act_y_img, ... } }
6

7
3. 两边合成一条扁平记录 → normalizeCollection() 清洗 → 快照

几个实现细节：

• 并发压到 3、每条之间留 120ms：这一块本来就请求多，再猛冲只会更快触发风控。
• lottery_id 可以传 0，实测不影响返回。
• 卡面图不做本地化：一个收藏集动辄十几张卡，全下载收益很低， 而这些图是公开可直连的。

页面怎么展示#

• 收藏集按「我拥有的卡牌数」从多到少排。
• 每张卡下面的 card_scarcity 用来标稀有度：>= 80 标「大隐藏」、 >= 60 标「小隐藏」。阈值随活动变化，所以只用来打标记和配色，不做硬性判断 —— 认不出来就当普通卡。

关联文件#

语法#

1
::bilibili{bvid="BV1GJ411x7h7" part=1 title="视频标题"}

不支持 av 号。把 av 转 BV 需要额外的算法，而真正需要兼容的场景极少， 写错了会被明确地降级成纯文本（见下）。

为什么叫「门面」（facade）#

生成的 HTML 里只有：

1
<figure class="bili-facade" data-bilibili data-bilibili-bvid="BV1GJ411x7h7" …>
2
  <div class="bili-facade__stage">
3
    <button data-bilibili-activate aria-label="视频标题"> ▶ </button>
4
  </div>
5
  <figcaption>…</figcaption>
6
</figure>

没有 iframe、没有 player.bilibili.com、没有第三方脚本。 所以在读者点击播放之前，这个页面和 B 站之间没有任何数据往来 —— 没有 Cookie、没有 IP 泄漏、没有第三方 JS。

点击后才由 src/utils/bilibili.ts 创建 iframe。那次创建是唯一的第三方请求， 而且是读者自己主动触发的。

参数写错会怎样#

::bilibili{} 的参数不合法（BV 号位数不对、p 不是正整数……）时， src/plugins/markdown/remark-bilibili.mjs 会把它还原成普通文本。

不这么做的话，组件会返回 null 让这一块直接消失 —— 作者看不到任何提示， 只会发现「我明明写了视频，页面上却什么都没有」。

安全#

播放器 URL 用 URLSearchParams 构造（不用字符串拼接）， 并且在激活时会重新校验 data-* 属性。原因是 DOM 是可篡改的 （浏览器插件、XSS 注入、控制台手改），而 iframe 的 src 一旦被改成 任意地址就成了开放重定向 / 钓鱼的跳板。

iframe 还带上了 referrerpolicy="strict-origin-when-cross-origin"， 只向 B 站暴露来源域名，不带完整路径。

与直接写 <iframe> 的对比#

关联文件#

两条更普适的教训#

一、「匿名能读到什么」和「文档写了什么」完全是两回事。 投币列表匿名可读、收藏夹内容匿名可读但目录不可读、勋章墙整个必须登录 —— 这三种情况文档里都是同一句「认证方式：Cookie(SESSDATA) 或 APP」。 只能一个个实测，文档只配用来查字段含义。

二、这个项目里出现了三次「不报错、数据静静消失」。 投币时间戳被二次归一化吃掉、$变量 写在普通字符串里、刷新收藏集时用部分结果覆盖全量。 共同点是：操作看起来都成功了，只有对比前后数据才发现不对。 所以每次改完同步逻辑，我都会把快照前后 diff 一遍，而不是看一眼退出码。