为什么改#

文章多起来之后标签会涨到十几个甚至几十个。全部铺在左侧栏那张小卡片里有两个后果：

• 左栏被撑得比正文还长，首页首屏几乎全被标签占满；
• 想找某个标签时，在一堆按钮里翻反而更难找。

现在怎么分#

/tags/ 页面是纯静态直出，没有任何客户端脚本：构建时把标签排好、 渲染成一组链接就完事。想按首字母分组也可以，改一个布尔值就行 （中文标签会全落到「其它」一组，所以默认关着）。

标签链接落在哪#

这里做了一个刻意的选择：不为每个标签生成独立路由。 getTagUrl() 统一返回归档页的筛选参数：

1
export function getTagUrl(tag: string): string {
2
  if (!tag) return url("/archive/");
3
  return url(`/archive/?tag=${encodeURIComponent(tag.trim())}`);
4
}

好处是「标签」只有一种落地方式 —— 不用为几十个标签各生成一个页面， 也不会出现「标签页和归档页筛选结果不一致」的问题。 这个函数是标签系统与路由之间唯一的接缝，哪天想改成 /tags/<标签>/， 只需要替换它一个。

配置#

1
export const tagsConfig: TagsConfig = {
2
  sidebarLimit: 12,         // 左栏显示上限；0 = 不限制（退回旧行为）
3
  sidebarSort: "count",     // 左栏排序：count 按文章数 / name 按字母
4
  pageSort: "count",        // /tags/ 页面排序
5
  pageGroupByLetter: false, // 是否按首字母分组
6
  showCount: true,          // 标签后面显示文章数
7
  cloudSizing: true,        // /tags/ 页面字号是否随热度缩放
8
  description: "",
9
};

排序在文章数相同时都会退化成字母序，保证每次构建结果一致 —— 否则同样的内容可能生成顺序不同的 HTML，git diff 里全是噪声。

两个能力层，别混在一起#

这是接入时最容易搞混的地方，两者的数据流向完全相反：

解析规则集中在 resolveUmamiOptions() 一个函数里，所有消费方共用同一个结论 —— 不会出现「脚本加载了但卡片没渲染」这种半开状态。

1
enable: true,
2
shareUrl: "https://cloud.umami.is/share/<id>",
3
websiteId: "<website-id>",
4
scriptUrl: "https://cloud.umami.is/script.js",

只填一个 websiteId 或只填 scriptUrl 不会加载采集脚本： 与其加载一个注定上报失败的脚本，不如干脆不加载。 只要公开分享统计的话，把后两行清空即可，页面上不会出现任何第三方脚本。

踩到的坑：cloud.umami.is 的区域路径#

这个坑值得单独记一笔。

Umami 的分享链接是一套只读的公开接口，读数据分两步：

1
GET {apiBase}/share/{shareId}                  → { websiteId, token }
2
GET {apiBase}/websites/{websiteId}/stats?...   → { pageviews, visitors, visits }

问题出在 apiBase 怎么算。官方文档里的链接长这样：

1
https://cloud.umami.is/analytics/us/share/<id>
2
                      ^^^^^^^^^^^^^ 区域段

但从控制台复制出来的实际是短链：

1
https://cloud.umami.is/share/<id>

短链里没有区域段。按「把 /share/ 之前的路径保留、后面接 /api」这条规则推导， 会算出 https://cloud.umami.is/api —— 而这个地址返回 404：

1
GET https://cloud.umami.is/api/share/<id>               → 404
2
GET https://cloud.umami.is/analytics/us/api/share/<id>  → 200 ✓

症状极具迷惑性：分享链接在浏览器里能正常打开、能看到图表，站内卡片却永远是 --， 控制台也不报错（请求失败被静默收敛成 null 了）。

修法是不猜，把几种可能都列出来按顺序探测：

1
const candidates = [`${origin}${prefix}/api`];
2

3
// 短链没有区域段时，真正的接口在 /analytics/<region>/api
4
if (!prefix.includes("/analytics/")) {
5
  candidates.push(
6
    `${origin}${prefix}/analytics/us/api`,
7
    `${origin}${prefix}/analytics/eu/api`,
8
  );
9
}

第一个 404 就试下一个，命中即停。这样自部署、带区域段、短链四种形态都能用。

数字是怎么到页面上的#

纯静态站点读第三方接口有个天然的矛盾：构建期抓的数据会过期，运行时抓的数据可能被挡住。

所以两条路都走，先到先得、后到的覆盖：

1. 构建期 —— 在 Node 里抓一次，把数字直接写进 HTML。首屏就有真实数值， 访客端即使被 CORS 或网络问题挡住也不会是一片 --。请求 5 秒超时， 失败不影响构建；同一次构建里只真正请求一次（Promise 缓存）， 不会每个页面都打一遍 Umami。
2. 运行时 —— 浏览器里再拉一次覆盖，成功就换成带千分位的实时值， 失败就保留构建期那份。

两端共用同一份接口代码。这不是为了少写几行，而是因为「接口地址怎么推导、 返回的 JSON 怎么解析」如果各写一份，迟早会漂移成「构建期能出数、运行时出不来」 这种极难排查的状态。

还有一个坑：域名绑定#

Umami 后台为该网站配置的 Website Domain，必须与站点实际域名一致。

不一致时采集脚本会被 Umami 实例的策略静默拦截：脚本能加载、控制台不报错、 后台就是一条数据都没有。排查方法是打开开发者工具的 Network 面板， 看 /api/send 请求的响应状态 —— 被拦截时它不会返回 2xx。

3.1 追番同步：构建期不联网#

页面数据来自一份本地 JSON 快照，由 pnpm anime:sync 在构建前显式抓取生成：

1
pnpm anime:sync --provider bilibili

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

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

代价是数据会停留在最后一次同步的时刻，所以快照过期后会在构建日志里提醒。

同步脚本里有几处是吃过亏才加的：

• 封面本地化。 B 站图床对外站有严格的 Referer 校验，直接把 URL 贴到页面里 大概率是破图。所以同步阶段把封面下载到 public/assets/anime/covers/， 页面只引用站内路径，访客端零第三方请求。
• 不跑本地图片转码。 给 URL 追加 B 站 CDN 自己的处理参数 @220w_280h.webp， 真正干活的是他们的图片服务，本地不依赖 sharp，拿到的就是裁好尺寸的 WebP。
• 扩展名按文件头魔数判断。 加了 @...webp 之后返回的仍可能是 JPEG， 光看后缀会写错扩展名。
• 敏感串扫描。 落盘前扫 SESSDATA / cookie: / access_token 之类的模式， 命中就中止写入。凭据只该存在于环境变量里，绝不该出现在要提交进 Git 的快照里。
• 原子写入 + 空结果保护。 先写临时文件再 rename；抓到空列表时不覆盖 已有的有效快照 —— B 站偶尔会限流，一次抖动不至于把线上番剧页清空。

接口本身是三天状态遍历（在看 / 看过 / 想看），翻页带间隔防限流：

1
GET https://api.bilibili.com/x/space/bangumi/follow/list
2
    ?type=1&follow_status=<1|2|3>&vmid=<UID>&ps=<10..50>&pn=<页码>
3
Referer: https://space.bilibili.com/
4
Cookie:  SESSDATA=<...>;      ← 仅当追番列表设为私密时才需要

追番列表如果是私密的，接口会返回 code 53013，此时需要在项目根目录的 .env 里填上 BILI_SESSDATA 再同步一次 —— .env 已在 .gitignore 里， 且脚本会扫描确认凭据没有混进快照。

3.2 最近投币的视频#

/anime/ 页面下半部分是「最近投币」，数据来自另一个接口：

1
GET https://api.bilibili.com/x/space/coin/video?vmid=<UID>&pn=<页>&ps=<每页>
2
→ { "code": 0, "data": [ ...视频对象 ] }

这个接口有三处和追番不一样，其中第三处直接把分页逻辑写崩过一次：

第 3 条如果照常写 pn++ 循环，就会无限翻同一页。所以用「本页有没有新 BV 号」兜底：

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

再配合「返回条数不足一页就停」，两种行为都能正确收敛 —— 不用去猜服务端到底认不认这个参数。

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

卡片上还会同时出现两个币数，别搞混：

• 封面左上角的 ×2 —— 我投了几个币（接口的 coins）
• 底部计数行的「投币」 —— 这个视频收到的总投币数（接口的 stat.coin）

3.3 粉丝勋章#

独立的 /medals/ 页面。这块把前面几个坑的教训一次性用上了 —— 先探接口再动手， 一探就发现它是唯一一个彻底没法匿名访问的：

1
GET https://api.live.bilibili.com/xlive/web-ucenter/user/MedalWall?target_id=<mid>
2
Cookie: SESSDATA=<...>;
3
→ { "code": -101, "message": "账号未登录" }

注意域名是 api.live.bilibili.com —— 勋章是直播体系的东西，不在 api.bilibili.com 上。 我照例试了换域名、补参数、加 buvid3 Cookie、加 WBI 签名，全部 -101。 所以这块没有「免凭据的用法」可以设计，只能老实配 SESSDATA。

代码上的处理是：没有凭据就不发请求，直接返回空并打印怎么配， 页面显示对应的提示 —— 而不是发一个注定 401 的请求再报个看不懂的错。

勋章的颜色字段有个值得记的细节：接口同时给了两套。

新版才是 B 站当前界面真正在用的配色（带透明度），所以优先用它，老版转成 #RRGGBB 兜底。页面直接把这些色值塞进 CSS 变量渲染成勋章 pill —— 每枚颜色都不一样，Tailwind 类名表达不了这个。

3.4 数字收藏集#

独立的 /collections/ 页面。这块一开始我理解错了 —— 用户说的「收藏集」 我当成了「收藏夹」，做出了一个以文件夹分组的页面才发现是两回事：

中文名长得像，实际毫无关系。

那个做错的收藏夹页面已经删掉了 —— 它本质就是一个视频列表， 和站点已有的归档页定位重复，没必要单独开一个页面。

1
GET x/vas/dlc_act/act/list?scene=1&site=<偏移>          列出全部收藏集（目录，约 20/页）
2
GET x/vas/dlc_act/asset_bag?act_id=&ruid=               我在某一个收藏集里的持有情况

3.5 视频门面：点击之前不连 B 站#

以前在文章里嵌视频是直接手写 <iframe>。那样有个问题： 只要页面被打开，浏览器就会连上 player.bilibili.com，即使访客根本没打算看。

• 每个访客的 IP 都被 B 站记录一次，还会带上 Cookie；
• 白占首屏带宽，拖慢真正想看的内容；
• 在你不知情的情况下，把「谁看过这篇文章」交给了第三方。

所以做了一个「门面」（facade）：构建期只输出一张静态卡片 —— 16:9 的占位区 + 播放按钮 + 一行标题，HTML 里没有 iframe、没有第三方脚本。 只有访客真的点了播放，才由浏览器现场创建播放器。

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

实际效果（点播放按钮之前，这个页面和 B 站之间没有任何连接）：

参数写错时（比如 BV 号少一位），这行语法会原样显示成文本而不是静默消失 —— 这样能立刻看出是哪里写错了，而不是对着一片空白猜。

安全性上，播放器 URL 用 URLSearchParams 构造，并且在激活时会重新校验 data-* 属性：DOM 是可控篡改的（浏览器插件、XSS、控制台手改）， 而 iframe 的 src 一旦被改成任意地址，就成了开放重定向的跳板。

改了什么#

1
改之前                          改之后
2
src/content/posts/              src/content/posts/
3
├── hello-world.md              ├── hello-world/
4
├── mizuki-relayout.md          │   ├── index.md
5
├── ...                         │   └── cover.jpg
6
└── img/                        ├── mizuki-relayout/
7
    ├── cover-1.jpg             │   ├── index.md
8
    └── photo-2.png             │   └── cover.jpg
9
                                └── ...

一篇文章一个文件夹，正文入口是 index.md，配图就近放在同一层， 用 ./cover.jpg、./photo-1.png 这样的相对路径引用。

为什么值得改#

迁移时守的两条规矩#

1. 文件夹名沿用原来的文件名，所以 15 篇文章的 URL 一字未变 —— 已有的链接和 giscus 评论全部继续有效。
2. 迁移脚本必须跳过围栏代码块与行内代码。 站内有两篇文章正是在用代码块 演示「图片该怎么写」，那些示例路径不能被改写 —— 否则示例就变成了错的。

顺带把文档里所有 ./img/xxx 的示例也改成了新写法， 新建文章的脚手架（pnpm new-post <名字>）现在直接生成文件夹结构。

配置覆盖层#

新增 src/user/user-config.ts。不想动主题自带的默认值时，把要改的字段写在这里：

1
export const userConfigOverrides: Readonly<Record<string, unknown>> = {
2
  umami: { enable: true, shareUrl: "https://…" },
3
};

合并规则是对象递归合并、数组整体替换。数组不做逐项合并， 因为 sidebarConfig.widgets 这类清单的语义是「这就是我要的全部条目」—— 逐项合并会让「删掉一项」变得没法表达。

这样升级主题时，src/config/*Config.ts 可以整份替换而不会覆盖你的配置。

文档#

四个功能各配了一篇说明，记的都是配置项、实现原理和坑：

• docs/tags.md
• docs/umami.md
• docs/bilibili.md
• docs/post-folders.md