跳到主要内容
Ed. notes

02 架构与选型:一个博客的最小系统

长文 · 2026-11-12 · 合集第 3 / 10 篇

  • 架构
  • 选型
  • Nuxt
  • 构建日志
第 3 / 10 篇 · 查看全部章节 → 当前:02 架构与选型:一个博客的最小系统

结论

先把「博客」拆小。它不需要数据库,也不需要 CMS,只需要四层:

content/ 里的 Markdown
  → server/utils/content.ts       扫描、校验、聚合、渲染
  → server/api/notes/*            输出 JSON
  → app/pages/*                   渲染页面
  → .output/                      构建成可部署产物

这四层分别回答四个问题:内容长什么样、内容是否合法、页面拿到什么数据、产物怎样运行。选型围绕这四层做,而不是先挑框架再想架构。

问题与设计

约束

这个站有几条硬约束:

  • 内容必须留在 Git 里,能 diff、能迁移、能备份;
  • 首屏要能直接看到内容,不能等客户端 JavaScript 跑完;
  • 视觉要克制,颜色、间距、圆角需要统一管理;
  • 部署要简单,一个人维护,不想引入数据库和 CMS;
  • AI 助手以后可以加,但不能让博客依赖它。

选择

约束 选择 没有选 原因
内容所有权 Markdown + frontmatter CMS / 数据库 内容即文件,Git 就是版本和备份
首屏与 SEO Nuxt 4 + SSR 纯 Vue SPA 页面在服务端就有 HTML,useSeoMeta 能直接产出 meta
服务端接口 Nitro 文件路由 独立 Node 服务 API、页面和构建在同一个项目里,少一套部署
样式 SCSS + CSS Modules + design tokens Tailwind 需要主题切换和组件级作用域,不想把样式写成工具类字符串
内容校验 Zod 手写 if / 运行时再说 错误在构建前暴露,字段契约可读
部署 Docker 多阶段 + Caddy 直接在主机跑 Node / Nginx 镜像可复现,Caddy 自动处理 HTTPS
AI 助手 独立 FastAPI 服务 把模型调用塞进 Nuxt Python 生态、RAG 依赖和故障域都和博客分开

Nuxt 在这里的价值不是「流行」,而是三件事恰好合在一起:文件路由、SSR 和 Nitro 服务端路由。页面可以直接 useFetch('/api/notes'),服务端接口又和页面共享 TypeScript 类型;部署时只有一个 .output/ 目录。

目录

edwardwang-blog/
  content/                       唯一写作源,前后端共用
    notes/                       短笔记
    articles/<系列>/             长文
  frontend/
    app/
      pages/                     首页、目录、详情、系列、关于
      components/                卡片、标签、筛选、页头页脚
      composables/               useNotes、useTheme
      layouts/default.vue        全局骨架
    server/
      api/notes/                 列表与详情接口
      routes/                    图片、RSS、sitemap
      utils/content.ts           内容读取与渲染
    scripts/validate-content.mjs 构建前校验
  backend/                       可选:AI 助手,博客不依赖(仅私有仓库)

这套结构里,frontend/ 和 content/ 已经作为开源仓库 nuxt-blog-demo 发布;backend/ 目前只在私有仓库中。下文提到 backend/ 时,指的都是私有仓库里的那一份。

content/ 放在仓库根,而不是 frontend/ 里面,是为了让前端和后端读同一份文件。前端通过 runtimeConfig.contentDir 找到它,部署时可以用 NUXT_CONTENT_DIR 覆盖。

一次请求怎么走

以 /notes 为例:

  1. 浏览器请求 /notes,Nuxt 在服务端渲染页面;
  2. 页面的 useNotes() 调用 /api/notes;
  3. Nitro 路由执行 loadContent(),扫描 content/、校验 frontmatter、过滤草稿;
  4. 路由把结果整理成 notes、tags、series 三段 JSON;
  5. 页面用这些数据渲染卡片网格,客户端 hydration 后接管筛选等交互。

详情页多一步:/api/notes/[slug] 在找到内容后调用 renderMarkdown(),把正文转成 HTML,再返回给页面。图片、RSS 和 sitemap 不经过页面,直接由 Nitro 路由响应。

关键代码

内容目录的配置在 frontend/nuxt.config.ts:

import { fileURLToPath } from 'node:url'

export default defineNuxtConfig({
  ssr: true,
  runtimeConfig: {
    // 默认指向仓库根 content;部署时可用 NUXT_CONTENT_DIR 覆盖。
    contentDir: fileURLToPath(new URL('../content', import.meta.url)),
    public: {
      // 用于 canonical、Open Graph、RSS 和 sitemap。
      siteUrl: 'http://localhost:3000',
    },
  },
})

服务端接口只做「读内容、转 JSON」这一层薄封装:

// frontend/server/api/notes/index.get.ts
export default defineEventHandler(() => {
  const notes = loadContent({ contentDir: String(useRuntimeConfig().contentDir) })
  const summaries = notes.map(toNoteSummary)

  return {
    notes: summaries,
    tags: aggregateTags(summaries),
    series: aggregateSeries(summaries),
  }
})

页面不直接读文件,而是通过一个组合式函数拿数据:

// frontend/app/composables/useNotes.ts
export const useNotes = () => useFetch<NotesResponse>('/api/notes', { key: 'notes' })

这三段代码把边界划清楚了:content.ts 管内容,路由管 HTTP,页面管展示。后面几篇分别进入这三层。

验证

不启动后端也能验证整条链路:

cd frontend
npm run content:validate
npm run dev

另开一个终端看接口:

curl -s http://localhost:3000/api/notes | head -c 400
curl -s http://localhost:3000/api/health

/api/notes 返回 notes、tags、series;/api/health 返回 status: ok 和当前内容数量。如果接口有数据但页面空白,问题通常在页面组件,不在内容层。

边界

  • 没有数据库,也没有增量索引;每次请求都会重新读取并校验文件。当前内容量下够用,内容规模变大后需要缓存或预生成。
  • 长文只扫描 content/articles/<系列>/ 这一层,不支持更深的多级目录。
  • 没有分页、站内搜索和运行时编辑;新增文章后要重新构建或依赖开发服务器重载。
  • AI 助手是独立服务,默认关闭;博客的构建、接口和页面都不依赖它。
  • 设计系统、部署细节和 CI 的深入取舍在 构建实践,本系列只讲到能读懂和运行博客为止。

下一篇从环境开始:把仓库克隆下来,用最短路径跑起首页、目录和详情页。