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

Thu, 04 Jun 2026 00:00:00 +0800

如何搭建个人博客：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

GitHub Actions on Liangweidong's blog

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

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

为什么选 Hugo（2026 视角）

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

1.1 Windows（用 Scoop 包管理器）

1.2 macOS（用 Homebrew）

1.3 Linux（Debian/Ubuntu）

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

2.1 创建源码仓库

2.2 初始化 Hugo 站点

2.3 创建部署仓库

三、GitHub Actions 自动部署

3.1 申请 Personal Access Token

3.2 配置源码仓库 Secrets

3.3 创建工作流文件

3.4 启用 GitHub Pages

3.5 触发部署

四、添加评论系统（giscus）

4.1 在部署仓库开启 Discussions

4.2 在 giscus.app 配置

4.3 配置 Hugo 主题

五、SEO 与常见踩坑

5.1 必做的 SEO 配置

5.2 5 个常见踩坑

5.3 进阶：自定义域名 + HTTPS

六、写给 2026 年的程序员

参考资料