跳到主要内容
Ed. notes

nuxt-blog-demo:把这个博客的前端开源出来

仓库 · 2026-11-12

  • 个人站
  • Nuxt
  • 开源
  • 内容管线

结论

这个博客的前端已经开源成独立仓库:nuxt-blog-demo。克隆之后三条命令就能跑起来,看到和本站一样的首页、笔记目录、详情页、RSS 和 sitemap。

它解决什么问题

写博客的过程中最难复用的不是某段代码,而是整套约束:内容放在哪、frontmatter 有哪些字段、草稿怎么过滤、slug 冲突怎么拦、构建前为什么必须先校验。这些约束散在几份文档里,别人读到也只能猜。

开源一个能跑的仓库,等于把这些约束变成可执行的东西:读者克隆下来跑一遍,就知道哪条规则是真的在生效。

我的实验

git clone https://github.com/edwardwang0302/nuxt-blog-demo.git
cd nuxt-blog-demo/frontend
npm install
npm run content:validate
npm run dev

校验通过后输出内容总数和草稿数,开发服务器在 http://localhost:3000。仓库自带一套演示内容:4 篇已发布笔记、1 篇草稿、1 篇带本地图片的笔记,以及 demo-log 系列的 3 篇长文;草稿可以用来验证「草稿不出现在目录、RSS 和 sitemap」,本地图片可以用来验证资源路由。

再往下一层是构建链路:

npm run build
npm run preview

生产构建和 npm run dev 不是一回事:开发服务器会热更新、按需编译,生产产物才会暴露 CSS Modules 类名、资源路由和 404 行为的问题。这也是仓库里把端到端测试指向 .output/server/index.mjs 而不是开发服务器的原因。

限制

  • 只包含博客前端。 AI 助手后端(FastAPI + pgvector)、聊天页面和同源代理不在这个仓库里,它们需要 Python、Postgres 和模型配置,是另一条链路。
  • 演示内容不是真实内容。 仓库里的 content/ 是一套最小示例,方便验证管线的每一条规则;本站正在写的真实内容不公开,避免半成品被当成结论读。
  • 文档是子集。 公开仓库保留了 docs/authoring.md、docs/design-system.md 和 docs/design-tokens.md;PRD、ADR、runbook 和变更记录留在私有仓库。
  • 没有 AI 相关的前端。 聊天浮窗、/chat 页面和 SSE 解析都不在这个仓库里,不要在这里找 /api/assistant/chat。

适合谁

想用 Nuxt 4 + Markdown 做内容站、但不想从零设计内容契约的人。这个仓库的 server/utils/content.ts 和 scripts/validate-content.mjs 可以直接借鉴;如果只要页面层和主题体系,仓库里的 frontend/app/assets/styles/ 也是完整的。

不适合当作生产模板直接上线:演示内容需要整体替换,部署配置里的域名和镜像地址都是占位符。

继续探索