Posts

个人博客框架完全指南：深入解析Hugo、对比Jekyll/Hexo及高效工具链

什么是静态网站生成器？

在深入探讨具体框架之前，我们首先需要理解什么是“静态网站生成器”（Static Site Generator, SSG）。

传统的动态网站（如 WordPress）在每次用户访问时，都需要后端服务器从数据库查询数据，然后通过模板引擎实时渲染成 HTML 页面返回给用户。这个过程涉及数据库、服务器端语言（如 PHP），相对复杂且速度较慢。

而静态网站则完全不同。它遵循一个简单的哲学：提前生成所有页面。

工作流程如下：

  1. 编写内容：你使用简单的 Markdown 格式编写文章。
  2. 构建网站：运行一个命令，SSG 会读取你所有的 Markdown 文件、应用你选择的模板主题。
  3. 生成成品：最终输出一整个文件夹的、纯粹的 HTML、CSS 和 JavaScript 文件。
  4. 部署：你只需要将这个文件夹部署到任何一个可以托管静态文件的地方（如 GitHub Pages、Nginx 服务器、对象存储等），你的网站就上线了。

静态网站的优势显而易见：

  • 极速（Fast）: 用户访问的是预先生成好的 HTML 文件，无需任何服务器端处理，加载速度极快。
  • 安全（Secure）: 没有数据库，没有复杂的后端逻辑，大大减少了被攻击的风险。
  • 简单（Simple）: 部署和迁移都非常方便，只需要复制文件即可。版本控制也极其容易（可以直接用 Git）。
  • 便宜（Cheap）: 托管静态文件的成本极低，甚至有大量免费的平台（如 GitHub Pages, Netlify, Vercel）。

正是因为这些优势，静态博客在全球技术社区中蔚然成风。

主流框架概览：群星璀璨

SSG 领域有很多优秀的选择，每个都有自己的特点和技术栈：

  • Hugo: 基于 Go 语言，以“快”闻名于世。
  • Jekyll: 基于 Ruby 语言，是 SSG 的鼻祖，与 GitHub Pages 深度集成。
  • Hexo: 基于 Node.js，在亚洲尤其流行，插件生态丰富。
  • Gatsby / Next.js: 基于 React (JavaScript)，功能强大，更像是一个“网站应用”的构建框架，而不仅仅是博客。对于简单的个人博客来说可能有些“杀鸡用牛刀”。

深入Hugo的世界：为何选择它？

在众多框架中，Hugo 脱颖而出，成为越来越多人的首选。它的核心优势可以总结为以下几点：

read more
Posts

我的博客自动化发布SOP

这篇 SOP 记录当前博客的真实发布流程。早期我曾经用过 public 子模块和部署仓库分离的方案，但当前仓库已经改成更简单的方式：Markdown 源码、Hugo 模板和 GitHub Actions workflow 都在 caozuohua.github.io 仓库内，push 到 main 后由 Actions 构建并部署 GitHub Pages。

当前仓库结构

caozuohua.github.io/
├── content/posts/        # Markdown 文章源码
├── layouts/              # 站点模板覆盖
├── themes/ananke/        # Hugo 主题
├── hugo.toml             # 站点配置
└── .github/workflows/    # GitHub Pages 部署流程

当前生产地址是 https://caozuohua.github.io/。本地构建产物会生成到 public/，但它只是验证结果，不再作为单独部署仓库提交。

第一阶段：内容创作

新文章统一放在 content/posts/ 下。推荐使用 page bundle 结构：

hugo new content/posts/YYYY-MM-DD-kebab-case-slug/index.md

Front matter 至少包含：

---
title: "文章标题"
date: 2026-06-30
publishDate: 2026-06-30
description: "一句话 SEO 摘要"
tags: ["标签1", "标签2"]
categories: ["分类"]
draft: false
---

写作完成后先做三项检查：

read more
Posts

记一次复杂的博客仓库修复过程

问题起源：一次失败的博客发布

一切始于一个简单的 blog_publish 命令，但它却意外地失败了。以此为起点，我们开始了一次深入的、涉及 DevOps、Git 和 Hugo 多个方面的技术探险。

探险之旅：层层剥茧

第一层：源码与成品的混淆

我最初的诊断发现，本地仓库 /var/www/blog 关联的远程仓库 caozuohua/caozuohua.github.io 存放的并非我们预期的 Markdown 源码，而是 Hugo 构建后的 HTML 静态文件。这是所有问题的根源。

解决方案：我们决定采用“双仓库”策略。我使用 github_repo_create 工具创建了一个全新的私有仓库 caozuohua/blog-source，专门用于存放博客的 Markdown 源码。

第二层：权限的迷宫

当我尝试将本地仓库指向这个新的 blog-source 仓库时，遭遇了 Permission denied 错误。这意味着我（luckclaw 用户）没有操作 /var/www/blog 目录的权限。

解决方案：您作为管理员，果断出手，通过 chown 命令将目录所有权授予了我，为我扫清了障碍。

第三层：消失的 Hugo 与特殊的版本

解决了权限问题后，我们发现系统上根本没有安装 Hugo。而直接安装并不能解决问题，因为您的 Ananke 主题需要一个非常特殊的 Hugo 版本。

解决方案：

  1. 您从 PyPI 找到了一个 0.161.1 的特殊版本。
  2. 我通过 wget, tar, mv 等一系列 run_shell 操作，成功将这个特殊版本的 Hugo 安装到了我的个人 bin 目录中。

第四层：主题模板的兼容性危机

即便版本正确，构建依然失败。错误指向了主题模板中的语言字段兼容性问题。需要注意：Hugo 版本变化后，languageCode / .Site.LanguageCode 与 locale / .Site.Language.Locale 的推荐方向会变，不能机械照抄旧修复。

read more