静态站点 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

Nginx 反向代理实战：WebSocket、HTTPS、静态站点与 MinIO 网关

Fri, 15 Apr 2022 00:00:00 +0800

Nginx 几乎是后端服务的标配——静态站点、反向代理、负载均衡、WebSocket 网关、HTTPS 终结，每个开发者都用过。但真正"线上跑得稳"需要把几个坑都踩过：WebSocket 反代不写 Upgrade 头、gzip 配错类型反向变慢、HTTPS 证书路径不对、buffer 不够大上传大文件 502。这篇文章把零散在多个笔记里的 Nginx 实战经验整理成一篇。

阅读对象：需要在容器化环境部署 Nginx 做反向代理/静态服务/WebSocket 网关的同学
覆盖范围：Nginx 容器化部署、反向代理基础、HTTPS 终结、WebSocket 反代、gzip/buffer 优化、MinIO 反代示例

一、容器化部署

1.1 最简启动

1

docker run -d --restart=always --name nginx -p 80:80 nginx:stable

推荐用 nginx:stable 而不是 nginx:latest：stable 标签跟小版本号（1.22、1.24 等），latest 偶尔会跳大版本。

1.2 配置持久化

生产环境必须挂载配置和静态文件：

1
2
3
4
5
6
7


docker run -d --name nginx --restart=always -p 80:80 \
 -v /home/nginx/logs:/var/log/nginx \
 -v /home/nginx/conf/conf.d:/etc/nginx/conf.d \
 -v /home/nginx/conf/nginx.conf:/etc/nginx/nginx.conf:ro \
 -v /home/nginx/dist:/usr/share/nginx/html \
 -v /etc/localtime:/etc/localtime:ro \
 nginx:stable

或者 host 网络模式（适合内网用 80 端口）：

1
2
3
4
5
6


docker run -d --name nginx --restart=always --net=host \
 -v /home/docker/nginx/log:/var/log/nginx \
 -v /home/docker/nginx/conf/conf.d:/etc/nginx/conf.d \
 -v /home/docker/nginx/conf/stream:/etc/nginx/stream \
 -v /home/docker/nginx/conf/nginx.conf:/etc/nginx/nginx.conf:ro \
 nginx:stable

1.3 Alpine 版（更小）

1
2
3
4
5
6
7


docker run -d --name nginx --restart=always -p 80:80 \
 -v /home/nginx/logs:/var/log/nginx \
 -v /home/nginx/conf/conf.d:/etc/nginx/conf.d \
 -v /home/nginx/conf/nginx.conf:/etc/nginx/nginx.conf:ro \
 -v /home/nginx/dist:/usr/share/nginx/html \
 -v /etc/localtime:/etc/localtime:ro \
 nginx:1.25-alpine

Alpine 版镜像只有 40MB 左右，但没有预装 shell 和常用工具（wget/curl/vi），排查问题时进容器会比较痛苦。

二、生产级 nginx.conf

 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


user root;
worker_processes 1; # 推荐设为 CPU 核心数

error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;

events {
 worker_connections 1024;
}

http {
 include /etc/nginx/mime.types;
 default_type application/octet-stream;

 log_format main '$remote_addr - $remote_user [$time_local] "$request" '
 '$status $body_bytes_sent "$http_referer" '
 '"$http_user_agent" "$http_x_forwarded_for"';

 access_log /var/log/nginx/access.log main;

 sendfile on;
 keepalive_timeout 65;

 autoindex on;

 # ===== gzip 优化 =====
 gzip on;
 gzip_buffers 32 4K;
 gzip_comp_level 6;
 gzip_min_length 1k;
 gzip_types application/javascript text/css text/xml;
 gzip_disable "MSIE [1-6]\.";
 gzip_http_version 1.1;
 gzip_vary on;

 # ===== 客户端 body/header buffer（上传大文件必须调）=====
 client_body_buffer_size 1024k;
 client_max_body_size 2048m;

 client_header_buffer_size 128k;
 large_client_header_buffers 4 128k;

 # ===== 代理 buffer =====
 proxy_buffer_size 256k;
 proxy_buffering on;
 proxy_buffers 64 128k;
 proxy_busy_buffers_size 512k;

 # ===== FastCGI buffer =====
 fastcgi_buffers 6 512k;
 fastcgi_buffer_size 512k;
 fastcgi_busy_buffers_size 512k;
 fastcgi_temp_file_write_size 512k;
 fastcgi_intercept_errors on;

 # ===== WebSocket 关键配置（http 段顶层）=====
 map $http_upgrade $connection_upgrade {
 default upgrade;
 '' close;
 }

 include /etc/nginx/conf.d/*.conf;
}

# ===== TCP/UDP 4 层转发（可选）=====
stream {
 log_format proxy '[$time_local] $protocol status:$status, bytes client:$bytes_sent/$bytes_received $session_time, '
 'client: $remote_addr, upstream:"$upstream_addr", '
 'bytes upstream:$upstream_bytes_sent $upstream_bytes_received $upstream_connect_time';
 include /etc/nginx/stream/*.conf;
}

关键参数解读：

client_max_body_size 2048m：上传文件超过默认 1M 会 413，调大

client_header_buffer_size 128k：HTTP header 单行超过 1k 会 400，调大

proxy_buffer_size / proxy_buffers：调大避免后端响应一次性写入临时文件

map $http_upgrade $connection_upgrade：WebSocket 反代必须，否则 426 错误

三、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


server {
 listen 443 ssl;
 server_name example.com;

 ssl_certificate /www/server/panel/vhost/cert/example.com/fullchain.pem;
 ssl_certificate_key /www/server/panel/vhost/cert/example.com/privkey.pem;
 ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;

 charset utf-8;

 location / {
 proxy_pass http://localhost:9000;
 proxy_redirect http:// https://;
 proxy_set_header Host $http_host;
 }
}

server {
 listen 80;
 server_name example.com;

 # HTTP 自动跳 HTTPS
 if ($scheme = http) {
 return 301 https://$host:443$request_uri;
 }
}

证书路径：生产环境用 certbot / acme.sh 自动签发 Let’s Encrypt 证书，定时续期。

四、反向代理 + WebSocket

WebSocket 反代必须带 Upgrade 和 Connection: upgrade 头：

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


location ^~ /ws/ {
 proxy_pass http://{{BACKEND_HOST}}/ws/;
 proxy_http_version 1.1;
 proxy_read_timeout 300s;
 proxy_send_timeout 300s;

 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;

 # WebSocket 关键
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection $connection_upgrade;
}

$connection_upgrade 由前面 map 指令定义，根据客户端 Upgrade 头动态返回 upgrade 或 close。如果忘了配 map，WebSocket 连接会被 nginx 关闭。

五、MinIO 网关示例

MinIO 经常用 Nginx 做反代，重点是 WebSocket（控制台实时通知）+ 大文件上传：

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


location ^~ /minio/ {
 proxy_pass http://localhost:9090/;
 proxy_read_timeout 300s;
 proxy_send_timeout 300s;

 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;
 proxy_http_version 1.1;

 # WebSocket
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection $connection_upgrade;
}

MINIO_BROWSER_REDIRECT_URL 必须配成 Nginx 转发后的地址，否则 MinIO 控制台会 404：

1
2


environment:
 - MINIO_BROWSER_REDIRECT_URL=http://{{NGINX_HOST}}/minio

六、踩坑清单

WebSocket 426/断开——忘了 map $connection_upgrade，或者 location 段漏 Upgrade 头
上传 413——client_max_body_size 默认 1M，调成业务需要的最大值
Header 400——client_header_buffer_size 默认 1k，Cookie 巨长的请求会超
代理慢/卡顿——proxy_buffer_size 太小，后端响应被频繁写入临时文件
gzip 没生效——gzip_types 漏了类型，或者 gzip_min_length 设太大（小文件不压缩）
配置改完没生效——nginx -s reload 失败（语法错），需要 docker logs nginx 查原因
HTTPS 跳不过来——return 301 写在 location / 里而不是 server 顶层
跨域 CORS——后端没设 CORS 头，Nginx 要么 add_header 加，要么在 if 段处理 OPTIONS 预检

七、2024+ 视角补充

本文写于 2022-04，2024-2026 期间 Nginx 关键演进：

Nginx 1.25+（2023-06 起）：HTTP/3 (QUIC) 实验性支持；gRPC 代理原生；动态 SSL 证书加载（不用 reload）
Nginx 1.27 LTS（2024-11）：HTTP/3 默认开；OpenSSL 3.x 兼容；更精细的限流（limit_req_dry_run 等）
Nginx Ingress 1.10+（K8s）：Gateway API 全面支持（vs 老 Ingress API）；IPV6 双栈
Nginx Unit 1.32+：应用服务器模式（跑 Go / Node / Python / Java / PHP / Perl）——Web 服务器 + 应用服务器一体
OpenResty 1.25+：Lua 生态成熟，WAF / API Gateway 场景仍是首选
替代品（2024+ 视角）：
- Caddy 2.x：自动 HTTPS / Caddyfile 简洁 / Go 跨平台——新项目首选
- Traefik 3.x：K8s 原生 / 自动服务发现 / Let’s Encrypt 自动化
- HAProxy 3.0+：四层代理性能优于 Nginx，数据库 / TCP 代理首选
- Envoy 1.32+：Service Mesh 标配（Istio / Consul / Linkerd）

实战建议（2025-2026 视角）：

传统 Web 反代 / 静态站 → Nginx 1.27 LTS 仍是生产首选
K8s 入口 → Nginx Ingress 1.10+ / Traefik 3.x / Gateway API
数据库 / TCP 代理 → HAProxy 3.0+（性能与功能强于 Nginx stream）
新项目想要最少配置 → Caddy 2.x（HTTPS 配置从 30 行降到 3 行）

八、参考资料

Nginx 官方文档：http://nginx.org/en/docs/
Nginx 反向代理 WebSocket：https://nginx.org/en/docs/http/websocket.html
Mozilla SSL 配置生成器：https://ssl-config.mozilla.org/

下一步

想做安全网关？→ Vaultwarden 自托管密码一文（也用 Nginx 反代）
想做企业 VPN？→ OpenVPN 自建 VPN 服务一文
想用 K8s Ingress？→ 看 K8s 集群流量入口 Ingress-nginx 一文