从零构建个人站 · 一个可运行博客的实现路径
这不是一份「建站感想」,而是一条对着源码走的实现路线:博客怎样选型、内容怎样从 Markdown 变成接口和页面、样式与主题怎样组织、最后怎样构建成一个可以部署的产物。读完可以自己把博客部分跑起来,并在代码里找到每一层的位置。博客部分已经开源,可以一边读这一系列,一边对照 nuxt-blog-demo 里的文件。
对照哪个仓库
博客部分(frontend/ + 内容管线)已经开源,仓库地址:
github.com/edwardwang0302/nuxt-blog-demo
git clone https://github.com/edwardwang0302/nuxt-blog-demo.git
cd nuxt-blog-demo/frontend
npm install
npm run dev
开源仓库和这个站点的关系:
| 部分 | 开源仓库 | 说明 |
|---|---|---|
frontend/ |
有 | Nuxt 4 前端,与本系列讲的实现一致 |
内容管线 server/utils/ |
有 | Markdown 扫描、校验、聚合、渲染 |
docs/ |
部分 | authoring.md、design-system.md、design-tokens.md |
Dockerfile、infra/ |
有 | 多阶段构建与 Caddy 反向代理示例 |
backend/ |
没有 | AI 助手后端(FastAPI + pgvector),只在私有仓库 |
/chat 页面与聊天组件 |
没有 | AI 助手前端,由 搭建AI助手前端 展开 |
| 真实写作内容 | 没有 | 开源仓库自带一套演示内容,与本站内容不是同一份 |
openspec/、scripts/ |
没有 | 变更记录与发布脚本属于私有仓库 |
所以:想跑起来、想读前端代码,对照开源仓库;想读 AI 助手,只看本系列之外的两个 AI 系列。
这个系列写什么
这个系列只讲博客部分:内容、服务端读取、页面渲染、样式主题和构建交付。
不包含 AI 助手的实现。私有仓库里的 backend/、/chat 页面和聊天组件是后来加上的可选能力,会由两个独立系列展开:
博客本身不依赖 backend/,开源仓库也不包含它。只读文章、看目录和详情页时,不需要启动 Python、Postgres 或任何模型服务。
文章
| 编号 | 标题 | 回答什么问题 | 状态 |
|---|---|---|---|
| 01 | 背景:为什么做这个站,以及不做什么 | 个人经历、目标、参考站审计、范围与不做清单 | 可读 |
| 02 | 架构与选型:一个博客的最小系统 | 目录结构、请求链路、Nuxt/SCSS/Markdown 的选择理由 | 初稿 |
| 03 | 从零跑起来:目录、依赖与命令 | 环境要求、安装、校验、启动、构建和常见错误 | 初稿 |
| 04 | 内容管线:Markdown 如何变成结构化内容 | frontmatter 契约、Zod 校验、草稿过滤、标签与系列聚合 | 初稿 |
| 05 | 服务端接口:内容如何离开文件系统 | notes API、详情渲染、图片资源、RSS、sitemap 和健康检查 | 初稿 |
| 06 | 页面与组件:首页、目录、详情与系列 | 布局、数据获取、标签筛选、系列总览、卡片和可访问性 | 初稿 |
| 07 | 样式与主题:tokens 与亮暗切换 | SCSS 变量、CSS 自定义属性、CSS Modules、主题闪烁和响应式 | 初稿 |
| 08 | 构建与交付:从本地到上线 | 内容校验、Nuxt 构建、Docker、Caddy 与 CI 质量门 | 初稿 |
| 09 | 下一步:博客之后的四条路线 | AI 前端、AI 后端、部署工程和性能优化分别怎么读 | 初稿 |
推荐读法
| 目标 | 顺序 | 说明 |
|---|---|---|
| 先跑起来 | 03 | 装依赖、校验内容、打开首页 |
| 读懂整个博客 | 01 → 02 → 03 → 04 → 05 → 06 → 07 → 08 | 从背景到实现,再到构建交付 |
| 只想改内容 | 03 → 04 | frontmatter、slug、草稿和校验规则 |
| 只想改页面 | 03 → 05 → 06 → 07 | 接口形状、页面数据流、组件和样式 |
| 准备上线 | 08 → 构建实践 | 构建链、镜像、反向代理、CI 与发布 |
| 继续做 AI | 09 → 搭建AI助手前端 / AI助手后端实现 | 博客读完后再进入 AI 的两个独立系列 |
最短运行路径
cd frontend
npm install
npm run content:validate
npm run dev
打开 http://localhost:3000。首页、/notes、任意一篇详情页、/rss.xml 和 /sitemap.xml 都属于博客部分,不需要后端。
代码地图
content/ 唯一写作源
notes/ 短笔记
articles/<系列>/ 长文
frontend/
app/pages/ 首页、目录、详情、系列、关于
app/components/ 卡片、标签、筛选、页头页脚
app/layouts/default.vue 跳转链接、主内容区和全局骨架
app/composables/useNotes.ts 页面读取 /api/notes
app/composables/useTheme.ts 主题状态与持久化
server/api/notes/ 笔记列表与详情接口
server/routes/ 图片、RSS、sitemap
server/utils/content.ts 加载、校验、聚合与 Markdown 渲染
scripts/validate-content.mjs 构建前内容校验
上面这份地图里的路径,在开源仓库 nuxt-blog-demo 中都能找到。
后面的文章按这条链路展开,不按「今天做了什么」组织。
状态与维护
- 01 可读;02–09 是初稿,
draft: true,不会出现在生产目录、RSS 和系列总览。 - 系列就是所在文件夹,文件夹名
01-从0建小站就是系列名;00-目录.md是系列第一篇,和其余文章一样有 slug、详情页和正文。 - 系列入口和首页系列卡片都跳到这篇目录文章;正文里的相对
.md链接会自动改写成站内地址。 - 文章 slug 规则是
<英文系列>-<两位序号>-<英文主题词>,本系列以build-log-开头,例如build-log-01-background-scope、build-log-05-server-api。 - 本系列只描述博客部分;AI 相关能力以 09 下一步 和两个 AI 系列为准。