用 Next.js 和 MDX 搭建个人技术博客

个人技术博客最重要的不是功能堆叠，而是让写作、预览、发布形成稳定循环。Next.js 负责页面和构建，MDX 负责文章表达，两者组合起来足够轻，也足够长久。

先把内容路径跑通，再逐步补搜索、分类、目录和视觉细节。博客系统的第一性原理是持续写作。

内容结构

HUAN Lab 把文章放在 content/posts 目录，每篇文章都是一个独立的 .mdx 文件。文件名同时承担 URL slug 的职责，因此建议使用英文短横线命名。

推荐的最小结构如下：

• content/posts/*.mdx 存放文章正文
• public/images/posts 存放文章封面和配图
• lib/posts.ts 负责读取 frontmatter 和正文
• docs/writing-guide.md 记录团队写作约定

const postPath = path.join(process.cwd(), "content", "posts", `${slug}.mdx`);
const source = fs.readFileSync(postPath, "utf8");
const { data, content } = matter(source);

这段读取逻辑不复杂，但它建立了一个清晰边界：内容作者只关心 MDX，页面组件只关心解析后的结构化数据。

Frontmatter 约定

每篇文章开头都需要完整 frontmatter。标题、日期、分类、标签、摘要、精选状态和封面路径都应该显式写出，避免页面层猜测默认值。

一个稳定的 frontmatter 可以带来几个好处：

• 列表页可以按日期排序
• 分类页可以直接过滤
• 搜索索引可以读取标题和摘要
• 社交分享可以使用统一封面

title: "用 Next.js 和 MDX 搭建个人技术博客"
date: "2026-07-12"
category: "技术教程"
tags:
  - Next.js
  - MDX
description: "记录博客搭建思路。"
featured: true
cover: "/images/posts/default-cover.svg"

构建与发布

本地开发时运行 npm run dev，确认文章列表、详情页和代码高亮都能正常显示。发布前至少执行一次构建：

npm run build

如果构建通过，就可以提交到 GitHub。Vercel 连接仓库后会监听主分支更新，自动拉取代码、安装依赖并运行构建命令。

小结

这个方案的重点是保持内容和程序之间的契约简单清楚。只要 frontmatter 可靠、文件路径稳定、构建命令可重复，个人博客就不会变成一个需要经常维护的负担。