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 为例:
- 浏览器请求
/notes,Nuxt 在服务端渲染页面; - 页面的
useNotes()调用/api/notes; - Nitro 路由执行
loadContent(),扫描content/、校验 frontmatter、过滤草稿; - 路由把结果整理成
notes、tags、series三段 JSON; - 页面用这些数据渲染卡片网格,客户端 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 的深入取舍在 构建实践,本系列只讲到能读懂和运行博客为止。
下一篇从环境开始:把仓库克隆下来,用最短路径跑起首页、目录和详情页。