做个人网站这件事，很多人不是没有想法，而是总卡在第一步。
买了域名，想好了名字，也大概知道自己想写什么，可一真要开工，事情立刻就多了起来：首页怎么搭，文章页怎么做，归档页要不要有，评论怎么接，订阅页怎么设计，暗黑模式要不要支持，SEO 怎么处理，后端接口怎么约定。
很多时候，内容还没开始写，精力已经先被基础设施耗光了。
所以最近我把自己一直在打磨的一套 Nuxt 4 博客前端，认真整理后开源了：blog-nuxt。
它不是只有几张截图能看的 Demo，也不是那种“适合学习，但不太适合真改真接”的半成品。它更像一套已经把页面骨架、内容流转、接口边界都铺好的内容站前端，你拉下来就能跑，想继续接后端，也能顺着往下做。
更重要的是，这次我把“前后端对接”这件事提前整理过了。不是前端先写一版，后端再来猜字段、猜分页、猜返回结构，而是服务端直接按文档实现接口，前端就能接上。
项目预览
首页
首页暗黑模式
首页样式 1
首页样式 2
首页样式 3
首页样式 4
首页样式 5
文章归档页
文章归档页暗黑模式
文章详情页
文章详情页暗黑模式
关于页
关于页暗黑模式
下雨天页（白噪音）
订阅页
我想开源的，不只是一个“博客模板”
我一直觉得，很多所谓博客模板的问题，不在于不好看，而在于不够完整。
首页也许有，文章详情也许也有，但一到真实使用场景，问题就开始冒出来了：没有归档页，没有评论流，没有订阅流程，没有站点信息初始化，没有和后端对接时可落地的接口契约，最后你还是得自己把一大堆基础设施重新补一遍。
这次我更在意的是“整站感”。
在 blog-nuxt 里，我把一个内容型网站常见而且真正会用到的页面，基本都铺出来了：
/首页/article文章归档页/[articleId]文章详情页/about关于页/envelope信件页/rain下雨天页面/subscribe订阅页
你拿到的不是一个孤零零的首页，而是一套已经能跑出完整内容站体验的前端。
这个项目让我满意的，不只是页面
先说技术栈，这套项目基于 Nuxt 4 + Vue 3 + Pinia + TypeScript，整体结构是偏现代前端工程化的。
文章详情支持 Markdown 渲染和代码高亮，整站带暗黑模式，首页用了视差效果和本地封面资源，评论、分页、搜索、筛选这些内容站里常见的交互也都补上了。你不是拿到一堆静态页面截图，而是拿到一套已经有内容流和交互节奏的前端站点。
但我更看重的，其实是它在工程层面没有偷懒。
这个仓库默认就支持 Mock 优先 的开发方式。也就是说，你哪怕后端还没开始写，前端照样可以把页面完整跑起来。等后端准备好了，只要把环境变量里的：
NUXT_PUBLIC_USE_MOCK=false
切过去，就能开始走真实接口。
而且这不是一句“支持切换”就算完了。我把这部分真正拆成了几块：
- Mock 层
- HTTP 封装
- API 调用层
- 类型定义
- 后端接口契约文档
这几个东西是对齐的。也就是说，后端不是来“猜前端想要什么”，而是可以直接照着 docs/API_CONTRACT.md 去实现。字段、分页、统一响应结构、路径规则，都已经提前讲清楚了。
换句话说，这个项目不只是“前端已经搭好了”，而是服务端只要按接口文档对接即可。
你不需要再反复和前端确认这些问题：
- 列表字段到底叫什么
- 分页结构怎么返回
- 统一响应外层怎么包
- 详情页正文到底走
mdcontent还是别的字段 - 评论、订阅这些接口路径怎么定
这些在文档里都写清楚了。后端照着实现，前端把 NUXT_PUBLIC_USE_MOCK=false 打开，就能切到真实服务。
对我来说，这一点比“页面漂不漂亮”更重要。
因为很多开源前端项目，看着热闹，真到联调的时候全靠猜：这个字段是不是叫 createTime，分页是 total 还是 count，列表外层包不包 data。这些东西一乱，项目马上就从“模板”变成“返工现场”。
blog-nuxt 这次我尽量避免了这种问题。
我故意保留了它的“内容气质”
我不太喜欢把个人网站做成冷冰冰的信息容器。
所以这套站里除了常规的首页、归档和详情页，我还保留了一些我自己很喜欢的页面，比如信件页、下雨天页面、订阅页。
这些页面从纯“功能性”角度看，不一定都是刚需，但它们会让一个站不只是“能发文章”，而更像一个有人在经营的空间。
README 里我把这个项目叫做“心情小镇”，其实也是这个意思。
我一直觉得，个人网站不只是一个内容输出容器，它也应该承载创作者的情绪、偏好和表达方式。技术是骨架，风格和气质才让它真正像“自己的站”。
它适合什么人
如果你想快速搭一个自己的博客或内容型网站，这个项目可以直接作为起点。
如果你正在学 Nuxt 4，想看一套不是玩具级 Demo 的项目结构，它也值得翻一遍。页面路由、状态管理、SSR 初始化、Mock 优先、接口封装、类型抽离，这些都不是演示性质的拼凑，而是实际项目里会反复遇到的东西。
如果你本来就有后端，这个仓库也很适合当作“前后端契约模板”来用。前端先跑 Mock，把页面和交互定下来；服务端直接按文档实现接口；最后再把环境变量切到真实服务。整个过程会比从零对齐省很多时间。
我比较喜欢的一点：它是可以继续长大的
很多模板起步很快，但长不大。
一开始看着轻巧，后面页面一多、状态一多、接口一多，就开始散。
这次我在 blog-nuxt 里比较在意“后续还能不能继续长”。站点信息有统一初始化，HTTP 层有统一封装，Mock 和真实接口共用一套调用方式，类型定义也提前抽出来了。这意味着它不是“先凑起来能跑就行”，而是从一开始就按可扩展的方式去整理。
你可以先把它当成个人博客来用，后面也完全可以继续往内容社区、作品集站、轻量内容平台去扩。
如果你也想试试
项目地址：
拉下来之后，直接跑下面几步就行：
git clone git@github.com:wangmiaozero/blog-nuxt.git
cd blog-nuxt
npm install
npm run dev
默认先用 Mock 跑前端：
NUXT_PUBLIC_USE_MOCK=true
NUXT_PUBLIC_API_BASE_URL=http://localhost:7001
等服务端按文档实现完接口，再把：
NUXT_PUBLIC_USE_MOCK=false
切到真实接口。
最后
我一直觉得，真正值得开源的，不是“看起来像项目”的东西，而是别人拉下来之后，真的能接着往前做的东西。
blog-nuxt 对我来说，就是这样一个项目。
它有页面，有气质，有工程骨架，也把后端接入这件事提前整理成了文档和契约。
所以它不只是“一个已经能跑起来的 Nuxt 博客前端”，也是一个服务端照文档对接即可落地的内容站模板。
如果你最近正想做一个自己的站，或者想找一套能直接改、直接接、还能继续长的 Nuxt 4 内容站前端，欢迎来看看这个仓库。
如果你觉得它有点用，也欢迎给我点个 Star。
