Next.js 内容站技术选型与实践

做一个技术博客站，框架选型是第一道坎。2026 年的今天，选择多得让人眼花：Next.js、Astro、Hugo、Eleventy、VitePress……每个都有自己的拥趸。这篇不拉踩，只讲我选了 Next.js 全家桶之后的真实理由，以及几个关键取舍。

一、为什么是 Next.js 而不是别的

我列了一个自己真正在意的检查表，不是 KPI 式的"社区活跃度"：

核心判断：内容站不等于"只会渲染 Markdown 的站"。我的站除了静态文章，还需要评论系统（写文件）、阅读数（API）、搜索、懒加载图片……这些的复杂度远超"渲染 Markdown"。Next.js 把"静态内容 + 动态交互 + 服务端逻辑"统一在一个 React 技术栈里，是我最终选择它的根本原因。

Astro 的 islands 很优雅，但当我发现自己要为评论/搜索写一堆客户端组件时，Next 的"整页 React"模式反而更顺。Hugo 快，但中文内容站的"公式、图表、自定义页面逻辑"在模板语言里会非常痛苦。

二、为什么不用 @next/mdx

这是最常被问的一个问题。Next.js 官方就支持 MDX（@next/mdx），为什么不用？

MDX 的本质是"Markdown + JSX"——文章里可以嵌组件。这听起来强大，但对一个纯内容型技术博客是过度设计，而且带来三个实际问题：

1. 渲染管线不可控。MDX 的渲染交给 MDX 运行时，我要的 KaTeX 公式、Mermaid 图、自定义引用块、代码高亮，每样都得往 MDX 插件里塞，出了问题很难调。
2. XSS 面大。MDX 允许任意 JSX，等于让 Markdown 拥有执行代码的能力，对"允许第三方投稿/内容多来源"的场景是隐患。
3. 正文和站点渲染层耦合。我希望能全站统一一个渲染函数（文章、教程、静态页共用一套样式），MDX 让每篇文章变成一个"组件"，样式收敛困难。

所以最终：文章就是纯 Markdown，自己写一个渲染器（src/lib/markdown.ts），把 KaTeX、Mermaid、引用块、代码高亮有控制地接进来。这条路后面有专门一篇讲。

三、静态 vs 动态：混合渲染的分区策略

内容站的月经问题是"哪些页面静态、哪些动态"。我的结论不是一刀切，而是按数据生命周期分区：

这个分区的关键洞察：

内容站点里"新增一篇文章"和"新增一篇教程"的用户期望不同。 文章是正式发布的，接受"要 build 才生效"；教程是常改的工作文档，最好丢个 md 文件刷新就能看到。所以教程路由做成请求时 readdirSync 扫描磁盘，文章详情走 SSG。

代价是：教程页是动态渲染，每次请求扫磁盘（有签名缓存优化，见第 2 篇）；文章新增要跑 build。这个权衡是值得的——把"等待构建"从高频操作里拿走。

四、自动构建：auto_rebuild.py

既然内容驱动，"新增文章后要 build"就是高频操作，不能靠手动。写了一个 auto_rebuild.py：轮询 src 目录的 mtime/size 快照，监测到变化自动 rm -rf .next && npx next build 并重启服务。

# scripts/auto_rebuild.py（核心逻辑）
# 每 3 秒对比 snapshot；变化 → 清理 .next → build → restart
watch 目录: src/ + public/ + next.config.ts + package.json + tsconfig.json
排除: src/data/comments（运行时数据，写入不触发重建）

这样整个编辑体验变成：写个 md 文件 → 保存 → 自动 build → 刷新页面看到更新。"要不要 build"完全不是用户心智负担。

五、版本与维护纪律

选完型，接下来是长期维护。这个系列每篇都会遵守几个铁的纪律，这里先立下来：

• 三线验证：每次改动 npx tsc --noEmit → npx eslint src → npx next build，全绿才算完。
• 版本号三处同步：package.json version、README 版本历史、git commit message，改一处必三处同步。
• 每轮交付附修改文件清单：谁改了哪些文件、是新增还是修改、要不要重新 build，列清楚便于手动同步生产。

给普通人的一句话：技术选型不是选"最好"的框架，而是选"你的需求里那些不常见但关键的部分"能被满足的框架。

参考

• Next.js 文档：https://nextjs.org/docs
• Astro：https://astro.build