Skip to content

BiliTube(六):把榜单做成纯静态站,搜索筛选不靠后端 ​

构建日志最后一行是 Generating static pages (1776/1776),产物是一堆 HTML、CSS、JS 和一份 1.7 MB 的 JSON。

没有数据库,没有 API 服务,没有登录。部署到 Cloudflare 之后,用户拿到的就是这些文件。这件事听起来像「省事」,实际是把复杂度从运行时搬到了构建时和浏览器里。

一、先在构建时把页面生成好 ​

详情页的路由是 /v/[bvid]/。Next.js 的静态导出要求显式告诉它有哪些页面:

tsx
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,读一次后缓存在模块级变量里:

ts
let videoCache: Video[] | null = null;

export function loadVideos(): Video[] {
  if (!videoCache) videoCache = readJson<Video[]>("videos.json");
  return videoCache;
}

web/lib/data.ts#L11-L18

1,774 个详情页、首页、隐私页、404,一共 1,776 个页面。每页都有自己的标题、描述、canonical 和分享图:

tsx
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:

ts
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

之后所有筛选都在内存里做:

ts
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 条,页码序列会固定首末页、当前页左右各留一页,中间断档用省略号:

ts
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。首页的「我的收藏」、详情页的收藏按钮、以及另一个标签页里的改动,需要互相同步:

ts
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 后追加尺寸参数:

ts
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`;
}

web/lib/types.ts#L44-L50

@672w_378h_1c.webp 让 CDN 直接返回缩略图,不拉原图。但 B 站封面有防盗链:带非 B 站 Referer 会 403,不带 Referer 反而 200。所以 <img> 必须显式设置:

tsx
<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 要过两道闸门。

本文阅读--次|全站访问--次|访客--人