Astro 静态博客文章推荐功能的实现思路

1. 标签匹配分（0-100）#

使用 Jaccard 相似度衡量两篇文章标签的重叠程度：

1
Jaccard(A, B) = |A ∩ B| / |A ∪ B|
2
tagMatchScore = Jaccard(当前文章标签, 候选文章标签) × 100

标签完全相同得 100 分，完全不同得 0 分。这是最直观的相关性信号。

2. 标题相似度分（0-100）#

标签可能为空或过于宽泛，标题往往能更精确地反映文章主题。同样使用 Jaccard 相似度，但需要先对标题分词。

关键问题是中英文混合标题的分词。方案对比：

最终选择 Intl.Segmenter，零依赖且天然支持中英混合：

1
function tokenizeTitle(title: string): Set<string> {
2
  const tokens = new Set<string>();
3
  const segmenter = new Intl.Segmenter("zh", { granularity: "word" });
4
  for (const { segment, isWordLike } of segmenter.segment(title)) {
5
    if (!isWordLike) continue; // 过滤标点和空白
6
    tokens.add(segment.toLowerCase()); // 英文统一小写
7
  }
8
  return tokens;
9
}

例如标题 "Astro 博客主题开发指南" 会被分为 {"astro", "博客", "主题", "开发", "指南"}。

3. 时间新鲜度分（0-30）#

采用 6 个月半衰期的指数衰减：

1
timeFreshnessScore = 30 × e^(-ln2 × daysSincePublished / 180)

刚发布的文章得 30 分，6 个月前的约 15 分，一年前约 7.5 分。这样在其他维度得分接近时，新文章会排在前面。

4. 分类加成（0 或 10）#

同分类的文章额外加 10 分，作为锦上添花的信号。

5. 选取策略#

不是简单地取 Top N，而是分两轮：

1. 优先取有标签匹配的（tagMatchScore > 0），按总分排序
2. 不足 5 篇时，从无标签匹配的候选中按 timeFreshnessScore + categoryBonus 降序补充
3. 跳过加密文章，加密文章不会出现在推荐列表

这样保证了：有相关标签的文章一定优先，没有标签匹配时也不会显示空列表。

问题：静态站无法实现服务端随机#

Astro 构建后输出纯 HTML，构建时的 Math.random() 只执行一次，结果被固化到 HTML 中。每次刷新看到的都是同样的”随机”结果。

方案：复用已有 API + 客户端渲染#

项目中已有一个 /api/allPostMeta.json 端点（日历组件在用），返回所有文章的元信息。直接复用它：

1. 给 API 补充 category 和 password 字段
2. 客户端 fetch 这个 JSON，过滤掉当前文章、相关文章和加密文章
3. Fisher-Yates 洗牌后取前 5 篇
4. 用 DOM API 渲染列表

1
// 使用缓存避免重复请求
2
if (window.__allPostMetaCache) {
3
  render(window.__allPostMetaCache);
4
} else {
5
  fetch(apiUrl)
6
    .then(r => r.json())
7
    .then(data => {
8
      window.__allPostMetaCache = data;
9
      render(data);
10
    });
11
}

缓存共享#

日历组件和随机文章组件共享同一个 window.__allPostMetaCache，无论哪个先加载，API 只请求一次。swup 页面切换时也不会重复请求，只是重新随机选取并渲染。