BiliTube(六):把榜单做成纯静态站,搜索筛选不靠后端
构建日志最后一行是 Generating static pages (1776/1776),产物是一堆 HTML、CSS、JS 和一份 1.7 MB 的 JSON。
没有数据库,没有 API 服务,没有登录。部署到 Cloudflare 之后,用户拿到的就是这些文件。这件事听起来像「省事」,实际是把复杂度从运行时搬到了构建时和浏览器里。
一、先在构建时把页面生成好
详情页的路由是 /v/[bvid]/。Next.js 的静态导出要求显式告诉它有哪些页面:
export const dynamicParams = false;
export function generateStaticParams() {
return loadVideos().map((video) => ({ bvid: video.bvid }));
}web/app/v/[bvid]/page.tsx#L14-L18
loadVideos() 在构建进程里用 fs.readFileSync 读 public/data/videos.json,读一次后缓存在模块级变量里:
let videoCache: Video[] | null = null;
export function loadVideos(): Video[] {
if (!videoCache) videoCache = readJson<Video[]>("videos.json");
return videoCache;
}1,774 个详情页、首页、隐私页、404,一共 1,776 个页面。每页都有自己的标题、描述、canonical 和分享图:
return {
title: `${video.title} · BiliTube`,
description: video.card?.why || video.card?.summary || "...",
alternates: { canonical: `/v/${bvid}/` },
openGraph: { type: "article", title: video.title, images },
};web/app/v/[bvid]/page.tsx#L42-L59
这一步在纯客户端 SPA 里很难做好。搜索引擎拿到的是一个空壳,分享卡片也统一是首页信息。静态生成让 1,774 条视频各自可被索引、可被分享。
二、首页:一次加载,浏览器内筛选
首页是另一种形态。首屏的标题、四项硬指标来自 meta.json,在构建时渲染进 HTML;下面的精选列表交给客户端组件 VideoExplorer,挂载后一次性拉两份 JSON:
Promise.all([
fetch("/data/videos.json").then((response) => response.json()),
fetch("/data/topics.json").then((response) => response.json()),
]).then(([videoList, topicList]) => {
setVideos(videoList as Video[]);
setTopics(topicList as Topic[]);
});web/components/VideoExplorer.tsx#L72-L89
之后所有筛选都在内存里做:
const matched = videos.filter((video) => {
if (onlySaved && !saved.includes(video.bvid)) return false;
if (topic) {
const list = video.card?.topics ?? [];
if (!list.includes(topic)) return false;
}
if (!keyword) return true;
const haystack = [
video.title, video.up ?? "", video.tname,
video.card?.summary ?? "", video.card?.why ?? "",
(video.card?.topics ?? []).join(" "),
].join(" ").toLowerCase();
return haystack.includes(keyword);
});web/components/VideoExplorer.tsx#L132-L165
搜索范围包括标题、UP 主、分区、摘要、推荐理由和主题词。分页是每页 25 条,页码序列会固定首末页、当前页左右各留一页,中间断档用省略号:
function buildPages(current: number, total: number): (number | "gap")[] {
if (total <= 7) return Array.from({ length: total }, (_, i) => i + 1);
const pages = new Set([1, total, current - 1, current, current + 1]);
if (current <= 4) [2, 3, 4, 5].forEach((item) => pages.add(item));
if (current >= total - 3) {
[total - 1, total - 2, total - 3, total - 4].forEach((item) => pages.add(item));
}
...
}web/components/VideoExplorer.tsx#L23-L41
架构文档记录的实测是 1,360 条全量过滤小于 100ms。现在多了 400 条,量级没变——1.7 MB 的数据换来了一个不需要后端的搜索框。这是整站最核心的一笔交易。
三、收藏只存在浏览器里
站点没有账号,收藏按钮点下去,写的是 localStorage。首页的「我的收藏」、详情页的收藏按钮、以及另一个标签页里的改动,需要互相同步:
const sync = () => setSaved(readFavorites());
sync();
window.addEventListener(FAVORITES_EVENT, sync);
window.addEventListener("storage", sync);web/components/VideoExplorer.tsx#L104-L114
storage 事件负责跨标签页,FAVORITES_EVENT 负责同一页面内的组件通信。没有这两个监听,你在详情页收藏完返回首页,列表还是旧的——这是纯静态站最容易漏掉的一处状态同步。
代价也很明确:换设备、清缓存、换浏览器,收藏就没了。产品的定位本来就不需要账号,所以这不是缺陷,是边界。隐私页把这一点写清楚了。
四、封面为什么不下载
1,774 张封面如果下载到仓库,体积会从几 MB 涨到约 300 MB,静态托管的轻量优势就没了(ADR-015)。
现在的做法是直连 B 站 CDN,在 URL 后追加尺寸参数:
export function coverUrl(cover: string | null | undefined, width = 672): string | null {
if (!cover) return null;
const height = Math.round((width * 9) / 16);
const base = cover.split("@")[0];
return `${base}@${width}w_${height}h_1c.webp`;
}@672w_378h_1c.webp 让 CDN 直接返回缩略图,不拉原图。但 B 站封面有防盗链:带非 B 站 Referer 会 403,不带 Referer 反而 200。所以 <img> 必须显式设置:
<img
src={coverUrl(video.cover) ?? ""}
referrerPolicy="no-referrer"
loading="lazy"
alt=""
/>这一条是实测出来的,不是猜的。图片加载失败时还有占位底色和骨架屏兜底,不会把卡片撑破。
五、为什么不做 SSR
| 方案 | 好处 | 代价 |
|---|---|---|
| SSR / 服务端渲染 | 可以做个性化、实时数据 | 需要部署服务与数据库,有运维和故障 |
| SPA 直读 JSON | 最轻,构建快 | 首屏空、SEO 差、分享卡片差 |
| 静态导出 | 零运维、每页可索引、可托管任意静态平台 | 数据更新要重新构建,个性化只能在浏览器里做 |
这个产品是「所有人看同一份每周榜单」,没有登录、没有实时数据、没有个性化推荐。SSR 的能力一样用不上,却要背一套服务端运维。ADR-004 选了静态导出。
选型之后还有一次视觉重做。首版是深色面板 + 圆角卡片 + 蓝色强调色,信息正确,但看起来像内部工具。第二版改成编辑型策展版面:浅青白底、墨色正文、单一翠绿强调色、衬线标题、发丝线分隔,封面成为视觉主角(ADR-016 / ADR-017)。

选型时也比过托管平台。Vercel Hobby 的带宽和商用限制不合适,*.vercel.app 在国内被污染;Cloudflare Workers 静态资源带宽不限、自带无 cookie 统计,配自有域名后可用(ADR-020)。
六、实测数据
| 指标 | 数值 |
|---|---|
| 构建页面 | 1,776 页 |
| 导出 JSON | 约 1.7 MB |
| 精选视频 | 1,774 条 |
| 主题数 | 80 个 |
| 全量筛选耗时 | 1,360 条时实测 <100ms |
| 封面存储 | 0 张,全部直连 CDN |
1.7 MB 不是一个小数字。首屏的列表要等它下载完才能渲染,所以页面先显示骨架屏,数据到了再替换。在网络慢的设备上,这个等待是真实存在的。
踩坑:封面 403 不是图片挂了,是 Referer
最开始直接在 <img> 里用 B 站封面地址,一半图片裂开。排查发现:带本站 Referer 请求封面返回 403,不带 Referer 返回 200。
修复不是换图床,而是给每张图加 referrerPolicy="no-referrer"。这件事没法在服务端统一处理,因为请求是浏览器发的。
ADR-015 还留了后手:如果 B 站以后改防盗链策略,卡片会集体变成占位底色,但有降级样式,不会破版。
为什么不按主题分片
1,774 条、1.7 MB 还能一次加载,按主题拆成 80 个文件反而要处理「切主题时再请求」的加载态和缓存。ADR-004 把分片列为「数据涨到数万条时」的遗留风险,现在没到那个点。
真到那天,第一步不是上搜索服务,而是把 videos.json 按首字母或主题拆成几个分片,首页只加载索引。纯静态站的可扩展性比想象中好,前提是别提前优化。
七、小结
这个站点的设计可以概括成三句话:
- 能在构建时做的,不放到运行时:1,774 个详情页、每页元信息、sitemap;
- 必须在浏览器里做的,接受它的代价:搜索、筛选、收藏存 localStorage;
- 能从外部引用的,不复制进仓库:封面直连 CDN,视频播放回 B 站。
站点不是这条流水线的附属品,它是整条链路的验收标准:数据对不对、卡片写得好不好、分数有没有意义,最终都要在页面上被人看见。
下一篇讲怎么把这一整套东西每周安全地推上线:为什么 push main 不部署,为什么打 tag 要过两道闸门。