从 60 分到 95 分：Hugo Blowfish 博客的极致优化之路

优化前的状态

#

拿到这个博客时，89 篇技术文章已经积累了相当的内容量，但在工程化和视觉呈现上存在不少问题：

优化路线图

#

整个优化分为 5 个阶段，按投入产出比排序执行：

flowchart LR
    A["阶段一
SEO 基础"] --> B["阶段二
视觉体验"]
    B --> C["阶段三
布局重构"]
    C --> D["阶段四
代码框"]
    D --> E["阶段五
CI/CD"]
    style A fill:#10b981,color:#fff
    style B fill:#3b82f6,color:#fff
    style C fill:#8b5cf6,color:#fff
    style D fill:#f59e0b,color:#fff
    style E fill:#ef4444,color:#fff

阶段一：SEO 基础修复

#

H1 标题滥用修复（72 篇，342 处）

#

Blowfish 自动从 title 字段生成 H1，正文中再写 # 标题 就会产生多个 H1，直接导致：

• 搜索引擎降权（一个页面不应有多个 H1）
• 目录（TOC）生成混乱
• 无障碍阅读器导航异常

写了一个 Python 脚本，精确匹配代码块外的 # 并转为 ## ：

# 核心逻辑：追踪代码块围栏，仅修改正文中的 H1
in_code_block = False
for line in lines:
    if line.startswith('```'):
        in_code_block = not in_code_block
    if not in_code_block and line.startswith('# '):
        line = '#' + line  # # -> ##

补充缺失的 description

#

7 篇文章缺少 description 字段，搜索引擎无法生成有意义的摘要。逐篇阅读内容后补充了 50-150 字的中文描述。

启用 robots.txt

#

enableRobotsTXT 从 false 改为 true，让搜索引擎能正确爬取。

阶段二：视觉体验提升

#

Favicon 全尺寸生成

#

从 author.svg 通过 CairoSVG 生成 5 种尺寸的 PNG：

# 生成的文件
static/favicon-16x16.png      # 浏览器标签页
static/favicon-32x32.png      # 浏览器标签页（高分屏）
static/apple-touch-icon.png   # iOS 添加到主屏幕
static/android-chrome-192x192.png  # Android PWA
static/android-chrome-512x512.png  # Android PWA 启动画面

通过自定义 extend-head.html 注入 favicon 链接。

分类名称统一（59 篇）

#

标签和分类的大小写混乱严重影响归档效果：

首页个人信息增强

#

# 修改前
headline = "欢迎来到我的博客"
bio = "一个热爱技术、乐于分享经验和想法的开发者。"

# 修改后
headline = "云原生与 DevOps 实践者"
bio = "专注 Kubernetes、CI/CD、可观测性等云原生技术栈，
       记录生产环境中的实战经验与踩坑复盘。"

阶段三：布局重构

#

配色与布局切换

#

子导航菜单

#

在主导航下方添加热门分类快捷入口：

[[subnavigation]]
  name = "Kubernetes"
  pageRef = "categories/kubernetes"
  weight = 10

[[subnavigation]]
  name = "Docker"
  pageRef = "categories/docker"
  weight = 20

自定义 404 页面

#

替换主题默认的简陋 404，使用 Tailwind 样式实现居中大号数字 + 双按钮导航。

阶段四：苹果窗口风格代码框

#

这是视觉提升最大的一项改动。完全通过 CSS + JS 实现，不修改主题源码。

CSS 实现要点

#

/* macOS 标题栏 */
.highlight::before {
  content: "";
  display: block;
  height: 2.5rem;
  background: rgba(40, 44, 52, 0.95);
}

/* 红绿黄三圆点 */
.highlight::after {
  content: "";
  position: absolute;
  top: 0.85rem;
  left: 1rem;
  width: 12px;
  height: 12px;
  border-radius: 50%;
  background: #ff5f57;
  box-shadow:
    20px 0 0 #febc2e,
    40px 0 0 #28c840;
}

踩坑记录

#

阶段五：封面图与 CI/CD

#

Unsplash 智能封面图

#

从 Picsum 随机风景照进化为 Unsplash 按分类精选的技术主题图片：

flowchart TD
    A["文章 Front Matter"] --> B{"有 featureimage?"}
    B -->|有| C["直接使用"]
    B -->|无| D["CI 构建前运行
assign-featureimage.py"]
    D --> E["读取已使用的图片 ID"]
    E --> F["从 95+ 图片池中
选取未使用的 ID"]
    F --> G["slug MD5 hash
保证稳定分配"]
    G --> H["写入 Front Matter"]
    H --> C

核心设计决策：

• 1920x1080 q=100 — 1080p 满质量，配合 hotlinkFeatureImage = true 直接引用 CDN
• slug hash 分配 — 同一篇文章每次构建获得同一张图
• 已用 ID 跳过 — 保证 89 篇文章零重复
• CI 自动化 — 新文章无需手动配图

SSH 远程部署

#

完整的 CI/CD 流水线：

stages:
  - build          # Hugo 构建（--minify --gc）
  - docker-build   # Docker 镜像构建推送
  - deploy         # GitLab Pages + SSH 远程部署

SSH 密钥通过 GitLab CI/CD Variable（file 类型）注入，OpenSSH 格式转 PEM 避免 libcrypto 兼容性问题。

最终成果

#

数据对比

#

MR 统计

#

16 个 MR，每个都经过 CI 流水线 + pr-agent AI 评审：

pie title MR 分类统计
    "SEO/内容修复" : 5
    "视觉体验" : 4
    "布局重构" : 2
    "代码框" : 3
    "CI/CD" : 2

关键经验

#

1. 不要修改主题源码

#

所有自定义都通过 Blowfish 提供的扩展点实现：

• layouts/partials/extend-head.html — Favicon
• layouts/partials/extend-footer.html — 自定义 JS
• assets/css/custom.css — 苹果代码框样式
• layouts/404.html — 自定义 404 页面

主题升级时零冲突。

2. 批量操作先写脚本

#

72 篇文章的 H1 修复、59 篇的分类统一、89 篇的封面图分配——全部通过 Python 脚本自动化，手动改一天的工作量 10 分钟搞定。

3. 每次改动都要验证

#

CI 流水线 + pr-agent 双重验证，16 个 MR 无一次直接推 main。有一次 author.svg 做头像导致 Hugo 构建失败（SVG 不支持 .Fill 方法），如果直推 main 就会导致线上故障。

4. Unsplash 图片 ID 要逐个验证

#

92 个候选 ID 中有 23 个返回 404。Unsplash 的图片可能被作者删除或设为私有，必须 curl 逐个验证后才能使用。

下一步

#

• 核心文章改用 Page Bundle 结构（posts/xxx/index.md + 本地图片）
• 定制 OG 社交分享图（1200x630，含博客名称和文章标题）
• 接入 Umami 自托管分析