120 lines
4.7 KiB
Plaintext
120 lines
4.7 KiB
Plaintext
---
|
||
title: "用 Next.js App Router 搭建个人博客"
|
||
date: "2025-03-08"
|
||
summary: "从零搭一个可写、可读、可部署的博客：内容层怎么设计、Server Component 怎么分工、MDX 与代码高亮怎么接。"
|
||
tags: ["Next.js", "MDX", "架构"]
|
||
draft: false
|
||
---
|
||
|
||
这个博客的第一版目标很克制：**能写、能读、能部署**。没有后台、没有数据库、没有登录。所有的复杂度都收敛到一件事上——把 Markdown 文件变成页面。
|
||
|
||
## 为什么不用 CMS
|
||
|
||
第一版最容易犯的错误，是一上来就选一个「以后肯定用得上」的方案。数据库 + 后台管理听起来很美，但它会带来一整套额外的负担：
|
||
|
||
- 需要维护 schema 与迁移
|
||
- 需要处理鉴权、草稿权限、并发编辑
|
||
- 需要为内容管理单独做一套 UI
|
||
- 本地开发必须先起一个数据库
|
||
|
||
而写作本身的需求其实非常朴素：打开编辑器，写 Markdown，提交。Git 已经是一个成熟的内容版本管理系统了——它自带历史记录、分支、协作和回滚。
|
||
|
||
> 用文件系统当数据库，用 Git 当版本管理。第一版不需要更多东西。
|
||
|
||
## 内容层设计
|
||
|
||
文章放在 `content/posts/` 目录，文件名即 slug：
|
||
|
||
```text
|
||
content/posts/
|
||
├── building-a-blog-with-nextjs.mdx
|
||
├── react-server-components.mdx
|
||
└── tailwind-v4-design-tokens.mdx
|
||
```
|
||
|
||
每篇文章顶部是一段 YAML frontmatter，声明标题、日期、摘要、标签和草稿状态：
|
||
|
||
```yaml
|
||
---
|
||
title: "用 Next.js App Router 搭建个人博客"
|
||
date: "2025-03-08"
|
||
summary: "从零搭一个可写、可读、可部署的博客。"
|
||
tags: ["Next.js", "MDX"]
|
||
draft: false
|
||
---
|
||
```
|
||
|
||
读取层只有一个职责：**扫描目录 → 解析 frontmatter → 校验 → 排序**。草稿在读取时就被过滤掉，因此它既不会出现在列表里，也无法通过直接访问 URL 被读到。
|
||
|
||
### 校验放在读取层
|
||
|
||
内容错误最容易的暴露时机是构建阶段，而不是线上。所以 frontmatter 的校验写在读取函数里：缺少 `title`、`date` 格式不对、`tags` 不是数组，都会直接抛出错误并终止构建。
|
||
|
||
```ts
|
||
const problems: string[] = [];
|
||
|
||
if (!title) {
|
||
problems.push("缺少必填字段 `title`（标题）");
|
||
}
|
||
|
||
if (problems.length > 0) {
|
||
throw new PostValidationError(slug, problems);
|
||
}
|
||
```
|
||
|
||
这样一来，错误信息会明确指向**哪个文件**、**哪个字段**，而不是在页面上渲染出一个空白标题。
|
||
|
||
## Server Component 的分工
|
||
|
||
App Router 的默认是 Server Component。博客恰好是它的理想场景：内容在构建时就已经确定，没有任何需要客户端状态的东西。
|
||
|
||
分工原则很简单：
|
||
|
||
1. **数据获取全部在服务端** —— 用 `server-only` 标记读取层，物理上防止它被打进客户端 bundle
|
||
2. **交互才下沉到客户端** —— 滚动进度、目录高亮、移动端菜单这类需要 `useState` 的部分单独拆成客户端组件
|
||
3. **列表页不传递正文** —— 列表只需要元信息，正文留在详情页按需读取
|
||
|
||
`server-only` 这个包很小，但价值很大：
|
||
|
||
```ts
|
||
import "server-only";
|
||
```
|
||
|
||
如果哪次重构不小心把内容读取层 `import` 进了客户端组件，构建会立刻失败，而不是把整个 `content/` 目录打进浏览器产物。
|
||
|
||
## 排序要稳定
|
||
|
||
按日期倒序是最直观的排序方式，但只按日期排序会有一个隐患：**同一天发布的两篇文章，顺序可能在不同机器上不一致**。
|
||
|
||
```ts
|
||
function byDateDescending(a: PostMeta, b: PostMeta): number {
|
||
const diff = new Date(b.date).getTime() - new Date(a.date).getTime();
|
||
return diff !== 0 ? diff : a.slug.localeCompare(b.slug);
|
||
}
|
||
```
|
||
|
||
用 slug 兜底之后，排序结果就是确定性的，构建产物也不会因为环境不同而漂移。
|
||
|
||
## 日期时区陷阱
|
||
|
||
YAML 里的 `2025-03-08` 会被解析成 Date 对象，而这个 Date 默认是本机时区的午夜。如果服务器在 UTC+8 而构建机在 UTC，同一篇文章可能显示成 3 月 7 日。
|
||
|
||
解决办法是**始终把日期当作 UTC 处理**：
|
||
|
||
```ts
|
||
new Intl.DateTimeFormat("zh-CN", {
|
||
year: "numeric",
|
||
month: "long",
|
||
day: "numeric",
|
||
timeZone: "UTC",
|
||
}).format(new Date(`${date}T00:00:00Z`));
|
||
```
|
||
|
||
读取时统一转成 `YYYY-MM-DD` 字符串，格式化时显式指定 `timeZone: "UTC"`。日期在整条链路上就不再漂移了。
|
||
|
||
## 下一步
|
||
|
||
第一版到这里就足够了。接下来真正值得做的事，是**先写几篇文章**，让真实的使用暴露出真实的需求——那时候再决定要不要加标签页、搜索或者 RSS，会比现在拍脑袋靠谱得多。
|
||
|
||
内容层已经预留了扩展点：标签聚合、相邻文章导航都基于同一份元信息，加功能不需要改动存储格式。
|