如何搭建个人博客：Hugo + GitHub Pages 实战 2026

前置：git、GitHub 账号、Node.js 24+、Hugo 0.162+ extended、Dart Sass 1.97+、Go 1.26+。本机开发用 VSCode。
Why 2026 还在用 Hugo：静态站点 + Markdown + Git 版本控制是程序员写博客的"最低摩擦路径"——不需要 WordPress 的数据库、不需要备案（境外 Pages）、不需要关心安全补丁。本文 2026 年最新版本 + 踩坑总结。

为什么选 Hugo（2026 视角）

我从 2014 年开始用 WordPress、2017 年迁 Hexo、2019 年转 Hugo、2024 年到现在稳定在 Hugo + hugo-theme-stack。4 套工具都用过超过 1 年，Hugo 的优势在 2026 年依然没被替代：

维度	Hugo	Hexo	WordPress	Notion
构建速度	290 篇文章 8 秒	290 篇文章 60 秒	不适用（动态）	不适用
依赖	单个 Go 二进制	Node + npm	PHP + MySQL	联网
写作体验	Markdown + 实时预览	Markdown	富文本	块编辑
可移植性	纯文本 + 静态文件	纯文本 + 静态文件	数据库导出	平台锁定
成本	0（Pages 免费）	0（Pages 免费）	服务器费用	订阅费

程序员写博客的"理想型"：本地 Markdown → Git 版本控制 → 推 GitHub → 自动构建部署到 Pages。整个链路纯文本、无数据库、跨平台、抗丢失。Hugo + GitHub Pages 是这条链路的最短实现。

一、本地环境搭建（Windows + macOS + Linux 三平台）

1.1 Windows（用 Scoop 包管理器）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# 安装 Scoop（一次性，PowerShell 管理员）
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex

# 装 Hugo extended + Git + Node
scoop install hugo-extended git nodejs-lts

# 验证
hugo version
# Hugo Static Site Generator v0.162.1-...
git --version
node --version

1.2 macOS（用 Homebrew）

1
2
3
4
brew install hugo git node

# 验证
hugo version

1.3 Linux（Debian/Ubuntu）

1
2
3
4
5
6
7
8
9
sudo apt update
sudo apt install -y hugo git nodejs npm

# 注意：Debian 仓库的 hugo 可能不是 extended 版
# 推荐从 GitHub Release 下载最新版
wget https://github.com/gohugoio/hugo/releases/download/v0.162.1/hugo_extended_0.162.1_linux-amd64.tar.gz
tar -xzf hugo_extended_0.162.1_linux-amd64.tar.gz
sudo mv hugo /usr/local/bin/
hugo version

关键提醒：必须用 hugo extended 版（带 Sass 编译），主题 hugo-theme-stack v4+ 依赖 Sass。

二、创建双仓库（源码私有 + 部署公开）

为什么双仓库：

源码仓库（私有）：你的 Markdown 草稿、源数据、未发布的文章——放私有防止泄露
部署仓库（公开）：Hugo 构建产物（HTML/CSS/JS），GitHub Pages 服务的对象——必须公开

两个仓库的命名约定（GitHub Pages 要求 <用户名>.github.io 形式）：

仓库	可见性	用途	命名示例
源码	Private	Hugo 源文件 + content	`my-blog`
部署	Public	静态构建产物	`<username>.github.io`

2.1 创建源码仓库

1
2
3
4
5
6
7
8
# 1. 在 GitHub 网页端：New repository
#    命名：my-blog
#    可见性：Private
#    不要勾选 "Add a README"

# 2. 克隆到本地
git clone git@github.com:<your-username>/my-blog.git
cd my-blog

2.2 初始化 Hugo 站点

1
2
3
4
5
6
7
# 初始化 Hugo（创建 hugo.toml、archetypes 等基础文件）
hugo new site . --force

# 拉取主题（hugo-theme-stack v4 通过 Hugo Module 引入）
hugo mod init github.com/<your-username>/my-blog

# 编辑 config/_default/module.toml

config/_default/module.toml 配置：

1
2
[[imports]]
path = "github.com/CaiJimmy/hugo-theme-stack/v4"

首次拉取主题依赖：

1
2
hugo mod get -u
hugo mod tidy

2.3 创建部署仓库

1
2
3
4
5
# 1. 在 GitHub 网页端：New repository
#    命名：<username>.github.io
#    可见性：Public
#    不要勾选 "Add a README"
#    （README 会在首次部署时自动生成）

三、GitHub Actions 自动部署

核心思路：源码仓库 push → Action 触发 → Hugo 构建 → 推到部署仓库 → Pages 自动发布。

3.1 申请 Personal Access Token

打开 https://github.com/settings/tokens
Generate new token → Generate new token (classic)
权限勾选：repo（完整仓库权限）、workflow
重要：复制 token 字符串（页面关闭后再也看不到）

3.2 配置源码仓库 Secrets

在源码仓库（my-blog）：

Settings → Secrets and variables → Actions → New repository secret
Name: PERSONAL_ACCESS_TOKEN
Value: 粘贴刚才的 token

3.3 创建工作流文件

源码仓库根目录创建 .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
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
name: Build and deploy
on:
  push:
    branches:
      - main
      - master
  workflow_dispatch:

permissions:
  contents: write

concurrency:
  group: pages
  cancel-in-progress: false

defaults:
  run:
    shell: bash

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      DART_SASS_VERSION: 1.97.1
      GO_VERSION: 1.26.4
      HUGO_VERSION: 0.162.1
      NODE_VERSION: 24.12.0
      TZ: Asia/Shanghai
    steps:
      - name: Checkout
        uses: actions/checkout@v6
        with:
          submodules: recursive
          fetch-depth: 0

      - name: Setup Go
        uses: actions/setup-go@v6
        with:
          go-version: ${{ env.GO_VERSION }}
          cache: false

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: ${{ env.NODE_VERSION }}

      - name: Install Dart Sass
        run: |
          mkdir -p "${HOME}/.local"
          curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
          tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
          rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
          echo "${HOME}/.local/dart-sass" >> "${GITHUB_PATH}"

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: ${{ env.HUGO_VERSION }}
          extended: true

      - name: Build the site
        run: |
          hugo \
            --gc \
            --minify \
            --baseURL "https://<your-username>.github.io/" \
            --cacheDir "${{ runner.temp }}/hugo_cache"

      - name: Deploy to Public Pages Repo
        uses: peaceiris/actions-gh-pages@v4
        with:
          external_repository: <your-username>/<your-username>.github.io
          personal_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
          publish_dir: ./public
          publish_branch: master
          commit_message: ${{ github.event.head_commit.message }}

关键点：

--baseURL 必须设为你 Pages 仓库的 URL，否则所有 CSS/JS 路径错位
personal_token 用 ${{ secrets.PERSONAL_ACCESS_TOKEN }} 引用 secret，永远不要把 token 写死在 yml 里
publish_dir: ./public 推送 Hugo 构建产物（290 篇文章对应几千个 HTML 文件）
publish_branch: master 是 GitHub Pages 默认分支（虽然现在 GitHub 推荐 main，但 Pages 仓库默认还是 master）

3.4 启用 GitHub Pages

在部署仓库（<username>.github.io）：

Settings → Pages
Source: Deploy from a branch
Branch: master / / (root)
保存

3.5 触发部署

1
2
3
git add .
git commit -m "feat: 初始化博客 + Actions 自动部署"
git push origin main

5-10 分钟后打开 https://<your-username>.github.io/ 就能看到博客。

四、添加评论系统（giscus）

为什么用 giscus：

基于 GitHub Discussions——评论数据在你自己的 GitHub 仓库里，永不丢失、可导出
零服务器——不需要数据库、不需要后端
隐私友好——不引入第三方追踪
支持 Markdown——程序员友好

4.1 在部署仓库开启 Discussions

部署仓库（<username>.github.io，注意是部署仓库）：

Settings → General → Features
勾选 Discussions

4.2 在 giscus.app 配置

打开 https://giscus.app/zh-CN：

Repository：填入你的部署仓库（<username>/<username>.github.io）
Discussion Category：选 Announcements（giscus 推荐）
Page ↔ Discussions Mapping：选 pathname
复制生成的配置（repo-id、category-id）

4.3 配置 Hugo 主题

config/_default/params.toml 中配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
[comments]
    enabled = true
    provider = "giscus"

    [comments.giscus]
        # 必填项 - 从 https://giscus.app/zh-CN 生成
        repo       = "<your-username>/<your-username>.github.io"
        repoID     = "R_你的ID"
        category   = "Announcements"
        categoryID = "DIC_你的ID"

        # 可选项
        mapping            = "pathname"
        strict             = "0"
        reactionsEnabled   = "1"
        emitMetadata       = "0"
        inputPosition      = "bottom"
        theme              = "preferred_color_scheme"
        lang               = "zh-CN"
        lazyLoadingEnabled = "1"

坑点：repo 字段必须填部署仓库（公开），giscus 需要从公开仓库读取 Discussion 数据。如果填源码仓库（私有），评论会失败。

五、SEO 与常见踩坑

5.1 必做的 SEO 配置

config/_default/params.toml：

1
2
3
[seo]
    image = image/cover.jpg
    thumbnail = image/cover.jpg

config/_default/hugo.toml 关键字段：

1
2
3
4
baseURL = "https://<your-username>.github.io/"
languageCode = "zh-CN"
title = "你的博客名"
googleAnalytics = "G-你的ID"  # 可选

5.2 5 个常见踩坑

CSS 加载失败：忘了 --baseURL 或 baseURL 错位 → 全部 CSS 404
Sass 编译失败：用的是 hugo 非 extended 版 → 升级到 extended
PAT 权限不足：token 只勾了 public_repo 没有 repo → 推送到私有部署仓库失败
giscus 评论不显示：repo 字段填了私有仓库（源码）→ 改填公开仓库（部署）
图片 404：文章用 page bundle 但图片放在别处 → Hugo 默认把 image/cover.jpg 解析为 bundle resource，路径必须对

5.3 进阶：自定义域名 + HTTPS

如果你有自己的域名（如 liangweidong.com）：

部署仓库 Settings → Pages → Custom domain：填 liangweidong.com
域名 DNS 添加 CNAME 记录指向 <username>.github.io.
勾选 Enforce HTTPS（GitHub 自动签 Let’s Encrypt 证书）

六、写给 2026 年的程序员

博客不是"展示技术"——博客是**“对外的备用大脑”**。我用 Hugo 写了 7 年：

2019 年写的 K8s 笔记到 2024 年帮新同事 1 天上手，省了 2 周培训
2020 年写的"数据量认知"到 2026 年自己回看，发现"亿级"那套方法论仍然适用
2022 年写的英语学习路径到 2026 年帮 3 个朋友少走 2 年弯路

写博客最大的收益不是"让别人看到"——是让自己 3 年后回看时能 5 分钟找回当时的状态。

工具会变（Hugo → Astro？→ 其他？），但纯文本 + Git 版本控制 + 公开 Pages这条链路不会变。从今天开始写，一年后的你会感谢现在的自己。

参考资料

Hugo 官方文档：https://gohugo.io/documentation/
hugo-theme-stack v4：https://github.com/CaiJimmy/hugo-theme-stack
GitHub Pages 文档：https://docs.github.com/en/pages
giscus 配置：https://giscus.app/zh-CN
peaceiris/actions-hugo：https://github.com/peaceiris/actions-hugo
peaceiris/actions-gh-pages：https://github.com/peaceiris/actions-gh-pages