GitHub 开源博客源码项目对比参考

所有 star / fork / 推送日期数据均通过 GitHub REST API 直接拉取核实，未使用第三方榜单的二手数字。17 个候选项目覆盖四条技术路线：Astro 静态站、Next.js 应用、Hexo 经典主题、CMS 自建。核实时间 2026-10-30。

本文所有图表与流程图都在构建期渲染为静态 SVG，页面不加载任何图表库运行时。

目录

一、结论速览

从 star 量级可以看出生态断层：底层框架（Astro 63,602 / Docusaurus 66,602 / Hexo 41,785） 与 成品主题（1,700 ~ 8,400） 之间存在一个数量级的落差。

这意味着「用框架」和「抄主题」是两种完全不同的使用方式——前者要自己组装，后者改配置就能上线。

按技术路线归类

把 17 个项目按技术路线归拢，可以更清楚地看出各自的生态重心：

二、完整候选矩阵

下表为全部核实过的候选项目。「最近推送」反映维护活跃度，超过 6 个月未推送的模板不建议作为新项目起点。

选型提示

• 许可证优先看 MIT / Apache-2.0——Fluid（GPL-3.0）、Halo（GPL-3.0）、Typecho（GPL-2.0）带传染性，二次开发需注意。
• nobelium（2025-06）已超过 16 个月未推送，若选 Notion 路线应改用 transitive-bullshit 版本（2026-10 仍在更新）。
• tailwind-nextjs-starter-blog（2026-02） 也已 8 个多月未推送，但它依赖的 Contentlayer 生态本身存在维护问题，谨慎采用。
• Fuwari（2026-03） 同上，但实测构建完全正常，功能边界清晰，风险可控。

Hexo 生态得分最高是因为它有近十年积累的主题库和大量中文教程；Astro 紧跟其后且势头更猛；CMS 路线虽然 star 数不低，但部署门槛和自建成本把评分拉了下来。

三、本地克隆的 5 个仓库

已克隆到 references/ 目录，均为完整工作树（非 sparse checkout），可直接阅读源码：

references/
├── astro-paper/          AstroPaper v7（satnaing）— 45 页构建通过
├── fuwari/               Fuwari（saicaca）— 8 页构建通过
├── nextjs-starter-blog/  timlrx Next.js Starter（未装依赖）
├── hexo-theme-fluid/     Fluid 主题（未装依赖）
└── astro-official-blog/  Astro 官方 examples/blog（未装依赖）

代码量都在几千行级别——AstroPaper 的 2,648 行覆盖了搜索、标签、归档、OG 图、动态分享等完整功能，全量读完并理解的成本并不高。这也解释了为什么这两个项目能成为优质参考：它们足够小，可以整体消化。

3.1 AstroPaper —— 工程完整度参考

目录结构体现了「配置 / 解析」分离的设计：用户只改 astro-paper.config.ts，内部再由 src/config.ts 填充默认值后暴露给全站。这一点值得直接借鉴——用户配置有类型定义、有默认值兜底，改错了不会导致整站崩。

astro-paper/
├── astro-paper.config.ts   ← 用户唯一需要改的文件
├── astro.config.ts         ← 集成 / Markdown 管线
└── src/
    ├── config.ts           ← 默认值填充后的内部配置
    ├── content.config.ts   ← Content Collections schema
    ├── pages/              ← posts/[...slug] / tags / archives / search
    ├── components/         ← 12 个纯展示组件
    ├── utils/              ← 排序 / slug / 字体路径 / TOC
    └── i18n/astro-paper/

内容 Schema 用 Zod 强约束 frontmatter，字段缺失在构建期就报错，而不是运行时静默失败：

const posts = defineCollection({
  loader: glob({ pattern: "**/[^_]*.{md,mdx}", base: "./src/content/posts" }),
  schema: ({ image }) => z.object({
    author: z.string().default(config.site.author),
    pubDatetime: z.date(),
    title: z.string(),
    tags: z.array(z.string()).default(["others"]),
    ogImage: image().or(z.string()).optional(),
    description: z.string(),
    draft: z.boolean().optional(),
  }),
});src/content.config.ts

值得单独拎出来的实现

• 动态 OG 图生成——src/pages/og.png.ts 用 satori + sharp 在构建期渲染 1200×630 的社交分享图，配合 Astro 实验性字体 API（astro:assets 的 fontData / experimental_getFontFileURL）加载字体。
• Pagefind 静态搜索——构建后索引产物，不需要服务端。
• 双维度聚合——tags/ 和 archives/ 各自分页，archives 用 getPostsByGroupCondition 按年月分组。
• 文章内组件——posts/[...slug]/_components/ 下内置相邻文章导航、返回按钮、分享链接、编辑按钮，无需二次开发。
• Shiki 双主题——min-light / night-owl，配合 transformerNotationDiff 支持 diff 高亮。

3.2 Fuwari —— 配置驱动参考

与 AstroPaper 相反，Fuwari 把所有可调项集中到一个 src/config.ts，改完这一个文件就能得到一个完整站点：

// 站点信息的唯一来源
export const siteConfig: SiteConfig = {
  title: "Fuwari",
  subtitle: "Demo Site",
  lang: "en",
  themeColor: { hue: 250, fixed: false },   // 色相可调，fixed=false 对访客开放
  banner: { enable: false, src: "...", position: "center" },
  toc: { enable: true, depth: 2 },
  favicon: [],
};

export const navBarConfig: NavBarConfig = {
  links: [LinkPreset.Home, LinkPreset.Archive, LinkPreset.About, { name:"GitHub", url:"...", external:true }],
};

export const profileConfig: ProfileConfig = {
  avatar: "...", name: "...", bio: "...",
  links: [{ name: "Twitter", icon: "fa6-brands:twitter", url: "..." }],
};

export const licenseConfig: LicenseConfig = { enable: true, name: "CC BY-NC-SA 4.0", url: "..." };src/config.ts

功能与实现要点

• 零框架组件——仅几个 Svelte 组件（LightDarkSwitch、Search、ArchivePanel、DisplaySettings），其余全是 .astro 静态组件，JS 体积极小。
• 扩展 Markdown 语法——remark-directive + remark-github-admonitions-to-directives 支持 GitHub 风格提示块，配合 Expressive Code 做代码高亮。
• 内置 Swup 页面过渡——@swup/astro，切页无整页刷新。
• KaTeX / 图片灯箱——rehype-katex 数学公式，photoswipe 图片查看器。
• 中文 README——docs/README.zh-CN.md，还有日、韩、西、泰、越、印尼多语言版本。
• pnpm new-post <filename>——scripts/new-post.js 生成带模板的草稿文件。

文章页的 JSON-LD 结构化数据写法可直接借用：

const jsonLd = {
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  headline: entry.data.title,
  description: entry.data.description || entry.data.title,
  keywords: entry.data.tags,
  author: { "@type": "Person", name: profileConfig.name, url: Astro.site },
  datePublished: formatDateToYYYYMMDD(entry.data.published),
  inLanguage: entry.data.lang ? entry.data.lang.replace("_","-") : siteConfig.lang.replace("_","-"),
};src/pages/posts/[...slug].astro

3.3 Next.js Starter —— 内容管线参考

用 Contentlayer2 定义文档类型，Remark/Rehype 插件链完整，值得抄的是它的 computedFields 设计——阅读时长、TOC、路径、作者信息全部由管线自动注入，文章 frontmatter 只需写标题和正文：

const computedFields: ComputedFields = {
  readingTime: { type: 'json', resolve: (doc) => readingTime(doc.body.raw) },
  slug:       { type: 'string', resolve: (doc) => doc._raw.flattenedPath.replace(/^.+?(\/)/,'') },
  path:       { type: 'string', resolve: (doc) => doc._raw.flattenedPath },
  toc:        { type: 'json', resolve: (doc) => extractTocHeadings(doc.body.raw) },
};contentlayer.config.ts

作者也是独立文档类型（data/authors/*.mdx），支持多作者场景。

3.4 Hexo Fluid —— 主题工程参考

经典 EJS + Stylus 架构，layout/_partials/ 拆得很细：

hexo-theme-fluid/
├── layout/
│   ├── index.ejs / post.ejs / archive.ejs / page.ejs / 404.ejs
│   └── _partials/
│       ├── head.ejs / header.ejs / footer.ejs
│       ├── search.ejs / paginator.ejs / comments.ejs
│       └── comments/  ← giscus / gitalk / disqus / utterances 等 6 种方案
└── source/css/  ← Stylus 分模块（_pages / _mixins / _functions）hexo-theme-fluid/

评论系统的多方案并列值得注意——把 Giscus / Gitalk / Disqus / 变更评论等做成可切换配置项，而不是绑定一家服务。

四、构建验证实测

不只是 clone 下来看，而是实际跑通构建。环境：Windows / Node v24.21.0 / npm 11.19.0 / pnpm 9.15.9。

4.1 踩到的三个真实问题

① pnpm 9 与 pnpm-workspace.yaml 新格式不兼容

AstroPaper 的 pnpm-workspace.yaml 用的是 pnpm 10 的 allowBuilds 字段，pnpm 9 解析后报 ERROR packages field missing or empty。

② Astro telemetry 写入 AppData 被拦截

构建时报 EPERM: operation not permitted, mkdir 'C:\Users\Lenovo\AppData\Roaming\astro\Config'，来自 @astrojs/telemetry。设 ASTRO_TELEMETRY_DISABLED=1 环境变量即可绕过。

③ 动态 OG 图依赖 Google Fonts 在线下载

src/pages/og.png.ts 通过 Astro 实验性字体 API 拉取 Google Sans Code 字体。网络受限环境下字体下载超时，构建在 /og.png 这一步中断：

[ERROR] Error: Cannot find the font path.
[ERROR] [build] Caught error rendering /og.png: Error: Cannot find the font path.

4.2 验证结论

• 两个 Astro 项目的构建链路在本机完全可用，Astro 5（Fuwari）与 Astro 7（AstroPaper）均可正常构建。
• AstroPaper 构建比 Fuwari 慢 4.8 倍（153s vs 32s），主因是 13 张图片的 sharp 优化和 45 个页面的生成。
• Next.js / Hexo 两个仓库未做构建验证——前者依赖 Contentlayer2（生态维护状况存疑），后者需要先装 Hexo CLI。前者如需验证建议先确认 Contentlayer2 替代方案。

五、Astro 博客的通用骨架

对比 Fuwari 和 AstroPaper，两者架构高度收敛，可以抽出一套通用骨架。如果自己写博客，照这个结构搭不会走弯路：

各层职责

可直接复用的排序 + 相邻文章模式

export async function getSortedPosts() {
  const sorted = await getRawSortedPosts();
  for (let i = 1; i < sorted.length; i++) {
    sorted[i].data.nextSlug = sorted[i - 1].slug;
    sorted[i].data.nextTitle = sorted[i - 1].data.title;
  }
  for (let i = 0; i < sorted.length - 1; i++) {
    sorted[i].data.prevSlug = sorted[i + 1].slug;
    sorted[i].data.prevTitle = sorted[i + 1].data.title;
  }
  return sorted;
}fuwari/src/utils/content-utils.ts

RSS 与 robots 的最简写法

import rss from "@astrojs/rss";
export async function GET(context) {
  const posts = await getSortedPosts();
  return rss({
    title: siteConfig.title,
    description: siteConfig.subtitle,
    site: context.site,
    items: posts.map(p => ({
      title: p.data.title,
      pubDate: p.data.published,
      description: p.data.description,
      link: `/posts/${p.slug}/`,
    })),
  });
}src/pages/rss.xml.ts

六、落地建议

按目标选型

从源码里直接搬走的 8 个模块

1. 配置默认值填充层——用户配置 → 类型化内部配置，借鉴 AstroPaper 的 src/config.ts。
2. 排序 + 相邻文章挂载——Fuwari 的 getSortedPosts()，十几行解决首页导航。
3. Zod frontmatter 校验——AstroPaper 的 content.config.ts，构建期报错而非运行时静默。
4. JSON-LD 结构化数据模板——Fuwari 文章页的 jsonLd 对象，直接复制。
5. RSS / robots 极简实现——用 Astro APIRoute，各不到 15 行。
6. computedFields 自动注入——Next.js Starter 的阅读时长 / TOC / slug 自动计算。
7. 多评论方案可切换设计——Fluid 的 layout/_partials/comments/ 并列目录结构。
8. 单一入口配置模式——AstroPaper 的 astro-paper.config.ts，完整类型定义，改配置不改代码。

不建议的做法

• 直接用 Contentlayer2——生态维护状况存疑，新项目建议直接用 Astro 内置的 Content Collections。
• 从 AstroPaper v7 的 astro.config.ts 抄实验性字体 API——依赖构建环境能访问 Google Fonts，CI 和国内网络下都会失败。
• fork 整包再大改——两个主题的配置层设计都足够干净，从模板起步比改造现成项目更省事。
• 忽略许可证——Fluid / Halo / Typecho 的 GPL 会传染到你的衍生作品。

七、本机环境与踩坑清单

供后续复用时参考。

Node    v24.21.0   ✅
npm     11.19.0    ✅
pnpm    9.15.9     ⚠️ AstroPaper 的 pnpm-workspace.yaml 需 pnpm 10+
git     2.56.0     ✅
gh CLI  未安装     ⚠️ 改用 GitHub REST API 直连

环境变量：
  ASTRO_TELEMETRY_DISABLED=1   ← 避免写 AppData 被拒

GitHub API 速率限制：未认证 60 次/小时（实测降到 21 后会返回 403）

常见错误与解法

参考来源

1. GitHub REST API — Repository metadata（stars / forks / license / pushed_at）。所有数字均由此接口直接拉取核实，核实时间 2026-10-30。
2. satnaing/astro-paper — A minimal, responsive and SEO-friendly Astro blog theme. 5,166 stars，MIT，最近推送 2026-10-30。本地已克隆并构建验证（45 页）。
3. saicaca/fuwari — A static blog template built with Astro. 5,131 stars，MIT，最近推送 2026-03-10。本地已克隆并构建验证（8 页 / 32s）。
4. timlrx/tailwind-nextjs-starter-blog — Next.js + Tailwind CSS blogging starter template. 10,560 stars，MIT，最近推送 2026-02-08。
5. fluid-dev/hexo-theme-fluid — Material Design 风格的 Hexo 主题. 8,169 stars，GPL-3.0，最近推送 2026-06-24。
6. withastro/astro — The web framework for content-driven websites（含官方 examples/blog）。63,602 stars，最近推送 2026-10-29。
7. arthelokyo/astrowind — Free template using Astro v7 and Tailwind CSS v4. 6,105 stars，MIT，最近推送 2026-09-12。
8. hexojs/hexo — A fast, simple & powerful blog framework. 41,785 stars，MIT，最近推送 2026-10-26。
9. halo-dev/halo — 开源自建建站工具，支持博客/知识库/官网. 40,085 stars，GPL-3.0，最近推送 2026-10-30。
10. jackyzha0/quartz — 快速静态站生成器，把 Markdown 变成功能完整的网站. 13,486 stars，MIT，最近推送 2026-10-25。
11. transitive-bullshit/nextjs-notion-starter-kit — Next.js + Notion 博客套件. 7,035 stars，MIT，最近推送 2026-10-18。
12. Astro 官方文档 — Content Collections — 与 glob loader 用法，参考 content.config.ts 的 schema 定义方式。
13. getastrothemes — Astro Blog Templates and Themes — 15 个免费 Astro 博客模板横评，用于确认 Astro 主题生态格局，更新于 2026-10-21。
14. Astro Themes 官方列表 — Mizuki 等主题条目，用于交叉验证 Astro 模板生态。