本站的构建全记录：一个纯静态的 Next.js 个人博客

项目概览

本站是一个纯静态的个人博客与作品集网站，基于 Next.js 16 App Router 构建，使用 MDX 管理文章内容，Tailwind CSS v4 负责样式，HeroUI v3 提供基础组件。全站没有任何后端服务与数据库，所有内容在构建时由本地文件生成静态页面，最终部署在 Vercel 平台上。

选择纯静态架构的原因很简单：内容即文件，版本可控，构建即发布。文章以 Markdown 文件的形式存放在仓库的 content/posts 目录中，每篇文章的元信息（标题、日期、分类、标签等）写在文件顶部的 frontmatter 里，正文部分则是 Markdown 语法。构建时由 src/lib/mdx.ts 统一读取这些文件，解析 frontmatter 并按日期倒序输出文章列表，同时根据正文字数自动估算阅读时长。

文章系统

文章系统是全站的核心模块。文章列表页每篇文章以一张横向卡片呈现，右侧叠加封面图与渐变遮罩，包含日期、描述、阅读时长、分类与标签信息。列表页头部右侧提供「文章归档」入口。

文章详情页由路由 blog/[slug]/page.tsx 动态生成，通过 generateStaticParams 在构建时预渲染所有文章页面。页面包含以下部分：顶部的分类与标签胶囊、大标题、日期与阅读时长信息栏；封面大图；正文内容区；文末的版权声明卡片与分享收藏按钮。

正文渲染采用自定义的按行解析器，支持一级到三级标题、引用块与代码块。二级标题左侧带柠檬绿色竖线装饰，所有标题都设置了 scroll-mt 保证锚点跳转时不被顶部导航遮挡。

详情页右侧配备目录侧边栏，在 xl 及以上屏幕显示。目录自动从正文中提取各级标题生成，采用 sticky 定位吸附在视口上方，滚动页面时始终固定可见，点击目录项可平滑滚动到对应章节。吸附位置精确对齐目录卡片的自然起始位置，滚动时不会产生任何位移。

返回按钮同样经过专门设计：它不是普通的链接跳转，而是通过 router.back() 沿浏览器历史栈返回，这样从文章返回列表时会恢复上次浏览到的滚动位置，而不是回到列表顶部；若用户是直接打开文章链接（无历史记录），则兜底跳转到列表页。

归档时间线

归档页面将全部文章按年份与月份两级分组。年份作为大标题展示并附当年文章总数，每年内按月份分卡片，每张卡片内按日期列出该月的文章。分组逻辑在构建时完成：解析每篇文章的日期字段，先按年聚合、再按月聚合，均从新到旧排序。整个页面是一个纵向时间线的形态，方便按时间脉络回溯内容。

友链与相册

友链页面将数据存储在 friends.json 中，与代码逻辑解耦，维护友链只需修改 JSON 文件而无需触碰代码。每个友链的预览图由 WordPress 的 mShots 服务自动生成首页截图，无需手工上传图片。页面将友链分为正常与「离线链接」两组，无法访问的站点会移入离线分组并附说明，待恢复后自动移回。友链支持搜索过滤，布局采用响应式网格：移动端单列、平板双列、桌面端四列。

相册页面负责展示日常摄影内容，配套的图片优化脚本通过 sharp 处理本地照片，生成多种尺寸的变体以适配不同的布局场景，并借助 next/image 实现懒加载。

首页 Bento 布局

首页采用当下流行的 Bento Grid（便当盒）布局，将多个功能卡片拼合在不规则网格中，包括：个人介绍 Hero 区、最近文章、最新友链、Bangumi 追番卡片、音乐播放器、天气时钟、每日签到与时间线卡片等。每个卡片都是独立的组件，互不干扰，可自由组合与增删。

主题切换与动效

全站支持明暗两套主题，通过 html 根元素上的 dark 类名驱动，Tailwind v4 的自定义变体与 HeroUI 的 data-theme 联动。主题初始化脚本内联在文档头部，在页面渲染前读取本地存储或系统偏好，避免了刷新时的主题闪烁。

主题切换采用 View Transition API 实现圆形扩散动画，从点击位置以圆形揭示的方式过渡到新主题。为保证导航栏与页面内容在同一帧内完成变色，切换期间会给根元素添加禁用过渡的类，临时关闭所有 CSS transition，避免过渡延迟造成的色彩不同步。

设计语言

视觉上全站采用米白底色搭配柠檬绿点缀（主色 #cbf033），圆角卡片、细边框与轻阴影构成主要的设计元素。图标统一使用 lucide-react 图标库。暗黑模式使用深灰绿底色，所有卡片、文字颜色均有对应的覆盖规则，保证两种模式下的对比度与可读性。

工程约定与总结

项目遵循以下约定：文章内容一律以 Markdown 文件存储于 content/posts 目录并包含完整元信息；UI 组件基于 Animate UI 与 HeroUI 实现；页面元素不使用表情符号；文章页配备右侧目录与文末版权声明。

整个项目没有引入任何服务端运行时依赖，构建产物为纯静态页面，托管成本几乎为零。对于个人博客这种以内容为中心的场景，「文件即数据库、构建即发布」的静态架构在简洁性、安全性与可维护性上都有明显的优势，也是本站持续迭代的基石。