为什么要做这个项目

我想搭一个真正能长期使用的个人博客，而不是只在本地打开一次主题示例页面。

对我来说，一个博客站至少要满足几件事：

  • 能稳定写文章
  • 能把已有项目经历整理上线
  • 后续还能继续改样式、改结构、改部署，而不是每次重头来一遍

所以这次项目真正做的，其实不是“套一个主题”，而是把博客从本地示例一步步整理成一个能持续维护的站点。

站点是怎么搭起来的

我选的是 Hugo + PaperMod 这套组合。

原因比较直接：

  • Hugo 适合写静态博客
  • Markdown 写文章效率高
  • 部署简单
  • 和 GitHub、Cloudflare 这类工具链很容易接起来

PaperMod 则帮我先解决了：

  • 首页模式
  • 文章页结构
  • 目录（TOC）
  • 标签页
  • 一些基础 SEO 元信息

这样我一开始就不用从零写模板，而是先把内容结构和部署链路跑通。

我做了哪些关键整理

1. 清掉官方示例内容

主题自带的示例页更适合演示功能，不适合直接变成自己的博客。

所以我先做的不是“加功能”，而是：

  • 清理默认示例内容
  • 只保留自己的 posts 结构
  • 创建文章 archetype
  • 把站点导航收成更适合个人博客的样子

这一步很重要，因为它决定了这个站到底是“演示模板”还是“个人项目”。

2. 把已有项目经历转成文章

博客不能只有壳子，没有内容。

所以后面我把自己已有的项目经历逐步整理成文章，例如：

  • dotfiles 仓库整理与同步
  • Kubernetes 静态网页部署实践

在这个过程中，我也发现一件事：

项目笔记和博客文章其实不是同一种写法。

  • 笔记更偏内部记录
  • 博客更偏对外表达

所以后来我会先把项目整理成笔记，再把它改写成更适合公开阅读的博客版本。

后面我又做了一件和普通文章不太一样的事：给站点加了一个独立的 Gallery 页面。

我不想把照片简单塞进博客文章里，因为两者的阅读方式完全不同：

  • 文章适合连续阅读
  • 照片更适合按组浏览，再点进去细看

所以这次照片模块采用的是另一套结构：

  • 右上角导航新增 Gallery
  • 页面按日期分组
  • 每个日期组是一张独立卡片
  • 卡片顶部显示日期、出处、作者
  • 组内照片直接用缩略图网格展示
  • 点击单张照片进入独立详情页

单图详情页也不是普通博客正文结构，而是：

  • 上面一张大图
  • 图下方是日期、出处、作者
  • 再下面是一排标签

这样一来，照片页的阅读体验就和文章页自然分开了。

我还把照片内容并进了站点现有的 tags 体系：

  • 每张图片都作为独立内容项
  • 每张图片都有自己的 tags
  • 这些标签会和文章标签一起出现在 /tags/ 页面里

这样标签页不只是文章索引，也能反过来帮照片做分类。

部署时真正踩过的坑

1. baseURL 没改，文章点击直接 404

刚开始最典型的问题就是：页面本地能看，但线上一点击文章就跳错地方。

根因其实很简单：

  • Hugo 生成很多绝对链接时会依赖 baseURL
  • 如果这里还是占位域名，文章页、图片、canonical、RSS 都会一起错

也就是说，这不是“某个链接写错了”，而是站点的基准域名没配置对。

2. Cloudflare 构建失败，不是 Hugo 问题，而是主题目录状态有问题

后面我把项目接到 Cloudflare 时，第一次并不是 Hugo 构建失败，而是仓库在拉取时就出问题了。

原因是：

  • themes/PaperMod 仍然是 submodule 指针
  • 但仓库里并没有把子模块映射处理干净

最后的解决方式，是把主题直接纳入仓库，改成普通目录。
这一步修完之后，Cloudflare 才能真正开始构建站点。

3. Cloudflare 新流程和很多旧教程不一样

这次部署时，我用到的已经不是很多旧教程里的老版 Pages 界面了，而是更接近 Workers Builds 的新流程。

整个链路变成了：

  • GitHub 仓库触发构建
  • Cloudflare 安装 Hugo
  • 执行 hugo --gc --minify
  • 再用 Wrangler 把 public/ 部署出去

这一步还额外要求补上：

  • wrangler.jsonc
  • compatibility_date

否则部署命令会直接失败。

4. 域名没真正接上时，头像会丢

后来页面里还出现过“头像不显示”的问题。

本质上不是图片文件没了，而是：

  • 页面里图片地址已经按正式 baseURL 生成
  • 但正式域名并没有真正绑定到当前部署

所以网页是在一个地址打开，图片却去另一个域名请求，最后自然失败。

为了先保证站点可用，我最后把 baseURL 暂时切到了当前已经成功上线的 workers.dev 地址。

样式这部分我后面又做了什么

把站点跑起来之后，我没有停在默认主题样式，而是继续调整了阅读体验。

主要做了两类改动：

首页

  • 保留 profile 模式
  • 调整背景颜色和卡片质感
  • 换掉演示素材

目标是让首页更像“个人站入口”，而不是主题默认演示页。

文章页

  • 把外层文章卡片做宽
  • 控制正文阅读列不要太长
  • 再把正文列整体往右挪一点

这样页面读起来会更自然：

  • 外层宽度不会太局促
  • 正文又不会一行太长
  • 留白也比默认布局更舒服

这部分其实已经不只是换色，而是在调阅读布局。

这个项目最后真正给了我什么

从结果看，这次我得到的不只是一个博客页面，而是一整套可继续维护的基础设施：

  • 一个能访问的个人博客
  • 一套 Hugo + PaperMod 的站点结构
  • 一条 GitHub 到 Cloudflare 的自动部署链路
  • 一种“项目笔记 -> 博客文章”的内容整理流程
  • 一版已经开始有自己风格的页面样式

对我来说，这种价值比“单次把页面做出来”更重要。

后面还想继续做什么

如果继续完善，我最想补的是：

  • 接入真正属于自己的自定义域名
  • 把站点标题、按钮文案、编辑链接这些细节收干净
  • 继续整理更多项目经历上线
  • 再慢慢把中文阅读排版打磨得更顺手
  • 继续扩展 Gallery，把更多真实照片整理进来

这类工作都不是推翻重来，而是在现有基础上的持续迭代。