博客 on Liangweidong's blog

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

WordPress 博客快速部署：官方镜像 + 数据持久化 + 反向代理

Fri, 15 Mar 2019 00:00:00 +0800

WordPress 是全球最流行的内容管理系统，官方市场份额常年第一（全球网站 40%+ 跑 WordPress）。虽然静态博客（Hugo/Jekyll）现在很火，但 WordPress 的"开箱即用 + 插件生态 + 后台可视化编辑"对新人和企业站仍是首选。这篇文章讲清楚 WordPress 官方镜像容器化部署、数据持久化、Nginx 反代、备份策略。

阅读对象：想用 WordPress 快速搭博客/企业站、又不想 LAMP 手工搭环境的同学
覆盖范围：WordPress 容器化部署、数据卷持久化、Nginx 反代、HTTPS、备份

一、为什么是 WordPress（容器化）

传统 LAMP 部署 WordPress：

装 Apache/Nginx + PHP + MySQL
配置 PHP-FPM / 虚拟主机
改 wp-config.php 数据库连接
装主题、插件、调权限

每台新机器都要重新走一遍。容器化的好处：

一致性：开发、测试、生产用同一镜像
可移植：服务器迁移只需打包数据卷
升级简单：docker pull wordpress:latest 一行就升级
隔离：和宿主机其他服务不冲突

When to use：需要"内容运营"团队（不熟技术）自己发文章、装插件，WordPress 是首选。如果只是写技术博客，Hugo / Jekyll 等静态博客更省心。

二、容器化部署

2.1 最简启动（SQLite 数据）

1
2
3


docker run -d --restart=always --name wordpress -p 8864:80 \
 -v /home/project/wordpress/data:/var/www/html \
 wordpress

数据卷 /var/www/html：WordPress 全部文件（核心代码 + 上传的媒体 + 主题插件）。挂出来才能持久化。

访问 http://{{HOST}}:8864 进入 WordPress 安装向导。

2.2 配合 MySQL 部署（推荐生产）

 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


version: "3"
services:
 mysql:
 image: mysql:8.0
 restart: always
 environment:
 MYSQL_ROOT_PASSWORD: {{REDACTED}}
 MYSQL_DATABASE: wordpress
 MYSQL_USER: wordpress
 MYSQL_PASSWORD: {{REDACTED}}
 volumes:
 - mysql_data:/var/lib/mysql
 command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci

 wordpress:
 image: wordpress:latest
 restart: always
 depends_on:
 - mysql
 ports:
 - 8864:80
 environment:
 WORDPRESS_DB_HOST: mysql:3306
 WORDPRESS_DB_USER: wordpress
 WORDPRESS_DB_PASSWORD: {{REDACTED}}
 WORDPRESS_DB_NAME: wordpress
 volumes:
 - wp_data:/var/www/html

volumes:
 mysql_data:
 wp_data:

utf8mb4：MySQL 5.7+ / 8.0 必须用 utf8mb4 字符集，emoji 和中文才不乱码。 depends_on：等 MySQL 起来再启 WordPress（但只保证容器启动顺序，不等 MySQL 完全就绪——WordPress 启动时会重试连接）。

2.3 初始账号

WordPress 安装向导里设置：

站点标题
管理员用户名 / 密码（不要用 admin）
管理员邮箱

生产环境必改：

用户名不要用 admin（机器人会暴力破解）

密码 16+ 位，大小写+数字+符号

邮箱用企业域名（找回密码用）

三、Nginx 反代 + HTTPS

 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


server {
 listen 80;
 server_name blog.example.com;

 # HTTP 跳 HTTPS
 return 301 https://$host$request_uri;
}

server {
 listen 443 ssl;
 server_name blog.example.com;

 ssl_certificate /www/cert/blog.example.com/fullchain.pem;
 ssl_certificate_key /www/cert/blog.example.com/privkey.pem;
 ssl_protocols TLSv1.2 TLSv1.3;

 # WordPress 上传文件可能很大
 client_max_body_size 100m;

 location / {
 proxy_pass http://127.0.0.1:8864;
 proxy_set_header Host $http_host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;

 # WordPress 永久链接（pretty permalinks）需要
 try_files $uri $uri/ /index.php?$args;
 }

 # 静态资源直接走 Nginx（性能优化）
 location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
 proxy_pass http://127.0.0.1:8864;
 proxy_cache_valid 200 30d;
 expires 30d;
 }
}

try_files 关键：WordPress 用"文章名"做 URL（如 /2019/03/hello-world/），Nginx 必须 fallback 到 index.php，否则 404。 client_max_body_size：WordPress 上传主题/插件可能 50MB+，默认 1M 会 413。

四、WordPress 后台必备设置

4.1 永久链接

Settings → Permalinks → Post name（/%postname%/）。别用默认的 ?p=123，SEO 友好需要路径式 URL。

4.2 媒体上传大小

Nginx：client_max_body_size 100m（如上）

PHP：容器内 php.ini 或 wp-config.php 加：

1
2


@ini_set('upload_max_size', '100M');
@ini_set('post_max_size', '100M');

4.3 安全加固

改默认管理员用户名（不要 admin）
强密码 + 二次验证（Google Authenticator 插件）
限制登录失败次数（Limit Login Attempts Reloaded 插件）
关闭文件编辑（wp-config.php 加 define('DISALLOW_FILE_EDIT', true);）
隐藏 WordPress 版本号（很多 security 插件有这个功能）

4.4 推荐插件

类别	插件	用途
SEO	Yoast SEO / Rank Math	元信息、sitemap、社交分享
缓存	WP Super Cache / W3 Total Cache	静态化提速
安全	Wordfence / Sucuri	WAF、登录保护、扫描
备份	UpdraftPlus / BackWPup	自动备份到 OSS/S3
主题	Astra / GeneratePress	轻量、快、自定义强
编辑器	Classic Editor / Gutenberg	编辑器选择

五、备份策略

5.1 备份什么

数据库（mysqldump）：所有文章、用户、配置
数据卷（wp_data）：主题、插件、上传的媒体
wp-config.php：数据库连接等关键配置

5.2 备份脚本

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


#!/bin/bash
# backup-wordpress.sh
BACKUP_DIR=/backup/wordpress/$(date +%Y%m%d)
mkdir -p $BACKUP_DIR

# 数据库
docker exec mysql_container mysqldump -u wordpress -p{{REDACTED}} wordpress \
 | gzip > $BACKUP_DIR/db.sql.gz

# 数据卷
docker run --rm \
 -v wp_data:/data:ro \
 -v $BACKUP_DIR:/backup \
 alpine tar czf /backup/wp_data.tar.gz /data

echo "Backup done: $BACKUP_DIR"

生产环境：备份同步到 OSS / S3 / 异地机房，本地磁盘挂了不能恢复等于没备份。

六、踩坑清单

上传 413——client_max_body_size 没调，或 PHP upload_max_filesize 太小
固定链接 404——Nginx try_files 没配，或者 .htaccess 没生效
中文乱码——MySQL 没用 utf8mb4 字符集，老库是 latin1
主题/插件升级失败——wp_data 没挂出来，容器升级后回到默认状态
wp-admin 卡顿——没接 CDN/缓存，每次请求都打 WordPress
被刷登录——没装限流插件，admin 用户名太简单被暴力破解

七、2024+ 视角补充

本文写于 2019-03，2024-2026 这几年 WordPress 生态有显著变化：

WordPress 6.x 核心更新：

6.0-6.6（2022-2024）逐步把经典编辑器过渡到全站编辑（Full Site Editing, FSE）+ 块主题（Block Theme），传统 PHP 主题（如 Twenty 系列）模式正在被"块"取代
6.5+ 引入站点字体加载 API（Site Fonts API），前端字体管理不再靠主题 hack
6.6（2024-07）性能大幅提升：首屏 LCP 优化、字体切换不闪屏、插件加载顺序调优

PHP 版本要求：WordPress 6.5+ 最低要求 PHP 7.4，强烈推荐 8.2+（性能提升 30%+）。wordpress:6-php8.3-apache 是 2024+ 生产推荐 tag。

容器化最佳实践更新：

官方镜像 wordpress 2024 年起改用 PHP 8.x + Apache 默认 tag，wordpress:latest 实际跑的是 6.6.x + PHP 8.3。旧的 wordpress:5-apache 还可拉但不收安全补丁
多阶段构建：2024 年生产推荐用 FROM wordpress:6-php8.3-apache + 自定义 wp-content 主题/插件做多阶段，把不可变基础设施原则贯彻
持久化命名约定：从 2019 年的 wp_data 卷，到 2024 年推荐 wp-content、wp-uploads 拆成独立卷——主题/插件更新不影响上传文件

Headless WordPress / WPGraphQL： 2023+ 越来越多团队把 WordPress 当 CMS-only 用（只走 WPGraphQL / REST API 输出 JSON），前端用 Next.js / Nuxt 渲染。好处：复用 WordPress 的后台编辑体验，前端享受现代 SPA/SSG 性能。WPGraphQL 插件 1.16+ 稳定。

反代 / HTTPS 实践变化：

2023 年起 certbot 推荐用 snap 或 docker 化部署（不再 apt install）
Caddy 替代 Nginx 越来越流行：自动 HTTPS（Let’s Encrypt 自动续期）、Caddyfile 配置比 nginx.conf 简洁 50%
WordPress 6.5+ 自带 application passwords 替代传统 API token，更安全

现代化插件栈（2024 推荐）：

类别	旧推荐	2024+ 推荐
缓存	WP Super Cache	WP Rocket（付费）或 LiteSpeed Cache（免费且强）
安全	Wordfence	Solid Security（原 iThemes）
SEO	Yoast SEO	Rank Math（免费 + 高级功能）
静态化	W3 Total Cache	Simply Static（生成纯静态站点）
表单	Contact Form 7	WPForms / Fluent Forms

经验法则更新：内容运营团队 + 简单站点 → WordPress 6.6 + PHP 8.3 + MariaDB 11 + LiteSpeed Cache；纯写技术博客 → Hugo / Astro 仍是更省心选择；API 化集成业务 → Headless WordPress + Next.js。

八、参考资料

WordPress 官方文档：https://wordpress.org/support/
WordPress 6.6 发布说明：https://wordpress.org/news/2024/07/
Docker Hub WordPress：https://hub.docker.com/_/wordpress
WordPress 永久链接：https://wordpress.org/support/article/using-permalinks/
WPGraphQL：https://www.wpgraphql.com/
安全白皮书：https://wordpress.org/about/security/

下一步

想做静态博客？→ 看 Hugo / Hexo 等（本站用的就是 Hugo）
想做密码管理？→ Vaultwarden 自托管密码一文
想做反代网关？→ Nginx 反向代理实战一文