跳到主要内容
Ed. notes

从零构建个人站 · 一个可运行博客的实现路径

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

  • 构建日志
  • 个人站
第 1 / 10 篇 · 查看全部章节 → 当前:从零构建个人站 · 一个可运行博客的实现路径

这不是一份「建站感想」,而是一条对着源码走的实现路线:博客怎样选型、内容怎样从 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 系列为准。