如何优雅使用 Hugo 撰写博客

前言

最近经常在挤时间来写博客 :(（因为在忙校招双选会嘛……投了几家中意的而且符合自身实际的岗位。面试前恶补一些以前立下的 Flag……欠下的总是要还的……）

吐槽一下学校的双选会：~~依托答辩~~ 太好了！63 个席位全是名企！感觉我已经手拿 40 个 offer，全球前 500 强任我挑选～！我们普通 本科 软件工程专业的学生真的是：前程似锦，乾坤未定，你我皆是牛黑马！稳了！ 都他妈稳了！ ~~（反串）~~

而且对我来说，写博客时并非一直文思泉涌，而是经常在某个时间点突然有了灵感，然后想赶紧趁思路热乎记录下来。所以我需要一个能够 快速撰写 并 发表 博客的工具。而 Hugo 就是这样一个工具：

它采用 Markdown 写作，轻量化，纯静态，快速部署，主题丰富，社区活跃，甚至可以不需要服务器，直接托管部署在 GitHub Pages 上等等……这也是我为什么选择 Hugo 的原因。

如你所见，这篇文章就是用 Hugo 写的。主题采用的是 hugo-theme-stack。这是一个非常简洁，却又功能强大的主题，正合我意。

至于痛点，列出几个：

现存问题

多平台撰写时同步的问题

目前只列出两个我想到的，后续再补充：

这里特指的是在不同设备上写博客的问题。比如在电脑上写了一半，然后出门在外，在公交车 / 路上突然来灵感，想在手机上继续写。这时候就需要一个同步的工具，来加载之前的进度。
在 Windows 上写和在 Mac 上写受限于系统环境问题，会有一点点不一致。比如 Windows 上的换行符和 Mac 上的换行符不一样，需要一个工具来处理这个问题。这里参考我上一篇博客：点击直达

下面我将带你一步一步解决上述问题，让你从此可以 ~~优雅地使用 Hugo 撰写博客~~。

整体思路很简单：博客源码放在 GitHub 仓库里，所有设备都通过 Git 同步；推送之后由 GitHub Actions 自动构建并发布到 GitHub Pages。

多设备写作与自动发布流程

步骤

由于这篇文章主要介绍双平台，所以我会尽量保持平台无关性。但是在某些步骤上，除非有特别需要时，我会特别指出 Windows 和 macOS 的区别，否则默认为通用步骤。

安装 Hugo

概述：Hugo 是一个用 Go 语言编写的 高性能 ~~我说的~~ 静态网站生成器。它可以将 Markdown 文件转换为 HTML 文件，然后部署到服务器上。

如果你已经阅读了我的上一篇博客为 Windows Terminal 配置 zsh + Oh-My-Zsh！[非 WSL]（强烈建议）的话，那么在 Windows 和 macOS 上安装 Hugo 将会非常简单。直接往下看。

1
2
3
4
5
# macOS（Homebrew 安装的就是 extended 版）
brew install hugo

# Windows（Chocolatey）
choco install hugo-extended -y

Stack 等很多主题需要编译 SCSS，必须用 extended 版。如果主题以 Hugo Module 方式引入，还需要额外安装 Go。

就这么简单，现在不出意外的话，你的电脑就已经有 Hugo 了：

1
hugo version

输出里带 +extended 就对了。

安装 Git

概述：Git 是一个分布式版本控制系统，用于跟踪文件的更改。

e……这个不多说了，如果你还不会（？？？？？？）。没关系，你可以参考我的上一篇博客为 Windows Terminal 配置 zsh + Oh-My-Zsh！[非 WSL]。

安装 Typora 与 VS Code 插件

概述：Typora 是一个轻量级的 Markdown 编辑器，支持实时预览。VS Code 是一个非常强大的编辑器，支持多种语言，插件丰富。二者结合起来，可以让你在写作时更加得心应手。

这个插件是我最近才发现的，非常好用。Typora 的官网在这里。在 VS Code 中安装 Typora 插件后，可以直接在 VS Code 里以所见即所得的方式编辑 Markdown，进一步提升你的写作体验。

把博客源码放进 GitHub 仓库

这一步是解决“多设备同步”的关键：把整个 Hugo 站点目录作为一个 Git 仓库推到 GitHub。

1
2
3
4
5
6
cd my-blog
git init
git add .
git commit -m "init blog"
git remote add origin git@github.com:<你的用户名>/<仓库名>.git
git push -u origin main

public/（构建产物）和 resources/_gen/（缓存）不需要提交，把它们写进 .gitignore。

之后在任何一台电脑上，开写之前 git pull，写完 git push，进度就同步了。

出门在外只有手机的话，可以直接在浏览器里打开 GitHub 仓库，用网页编辑器修改 Markdown 并提交；推送后会自动触发下面配置的发布流程。

处理换行符

Windows 默认使用 CRLF 换行，macOS / Linux 使用 LF。两边混着提交，就会出现“明明没改内容，整个文件都显示被修改”的情况。

最省心的办法是在仓库根目录放一个 .gitattributes，由仓库统一规定换行符，不依赖每台电脑的设置：

1
2
3
4
5
6
7
8
9
* text=auto

*.md text eol=lf
*.yml text eol=lf
*.yaml text eol=lf
*.json text eol=lf

*.png binary
*.jpg binary

另外，也可以按平台设置 Git 的全局选项作为兜底：

1
2
3
4
5
# Windows：检出时转换为 CRLF，提交时转换回 LF
git config --global core.autocrlf true

# macOS / Linux：提交时把 CRLF 转换为 LF，检出时不转换
git config --global core.autocrlf input

新建文章与本地预览

推荐使用 Page Bundle 的方式组织文章：每篇文章一个目录，图片和 Markdown 放在一起，引用时直接写相对路径。

1
2
3
4
5
# 按 archetypes/default.md 模板新建文章
hugo new content post/my-first-post/index.md

# 启动本地预览（-D 表示同时渲染草稿）
hugo server -D

浏览器打开 http://localhost:1313/，保存文件后页面会自动刷新：

新建文章与本地预览

推送后自动发布到 GitHub Pages

最后一步，让 GitHub 在每次推送后帮我们构建、发布。在仓库中新建 .github/workflows/deploy.yml，下面是一个精简后的示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
name: Deploy Hugo site to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: "latest"
          extended: true

      - name: Build
        run: hugo --minify --gc

      - uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  deploy:
    runs-on: ubuntu-latest
    needs: build
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

然后在仓库 Settings → Pages → Build and deployment 中，把 Source 设为 GitHub Actions。

如果主题通过 Hugo Module 引入，需要在构建前加一步 actions/setup-go 安装 Go。各 Action 的版本号请以它们仓库的最新发布为准。

到这里，写作流程就变成了：随便哪台设备写 → git push → 等一两分钟，博客自动更新。

总结

用 Git + GitHub 解决多设备同步；
用 .gitattributes 统一换行符，告别 Windows / macOS 的差异；
用 hugo server 本地预览，用 GitHub Actions 自动发布；
编辑器随意，Typora、VS Code 都很顺手。