一、工具安装

1. Go

这里安装的 Go 版本为 1.25.3，官网地址：Go。

安装过程：略。

安装完成后，查看 Go 版本：

1
2

$ go version
go version go1.25.3 windows/amd64

2. Hugo

Hugo 是一个用 Go 写的静态网站生成器。

这里安装的是标准版的 Hugo。

1
2
3
4
5
6

$ go install github.com/gohugoio/hugo@latest
go: downloading github.com/gohugoio/hugo v0.152.1
...

$ hugo version
hugo v0.152.1 windows/amd64 BuildDate=unknown

3. Hugo 的常用命令

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

# 创建网站
$ hugo new site <网站名>

# 启动本地服务器
$ hugo server

# 启动本地服务器 (包含草稿文章)
$ hugo server -D

# 创建文章
$ hugo new <文章名称>

# 生成静态网站
$ hugo

二、创建网站

1. 创建流程

基本创建流程如下：

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

$ hugo new site hugo_blog
$ cd hugo_blog

# 创建 git 仓库
$ git init

# 下载主题, 这里选择的是 PaperMod
$ git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

# 配置主题为 PaperMod
$ echo "theme = 'PaperMod'" >> hugo.toml

# 测试
$ hugo server

PaperMod 主题的示例网址

可选

为了方便管理，建议将 Hugo 创建的网站保存到 Github 的私有仓库或其他私人 Git 服务器，当然也可以保留到本地。\

Hugo 是用来生成静态网站的，我们发布的只是 Hugo 生成的静态网站，而不是 Hugo 创建的网站。

1
2
3
4
5
6
7

# 本地提交代码
$ git add .
$ git commit -m "init: Hugo 网站初始化"

# 添加 Github 仓库地址并提交
$ git remote add origin <仓库地址>
$ git push -u origin master

2. 目录架构

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

hugo_blog
├── archetypes
├── assets
├── content        # 存放博客文章
├── data
├── hugo.toml      # Hugo 配置文件
├── i18n
├── layouts
├── public         # Hugo 生成的静态网站
├── static
└── themes         # 主题插件
    └── PaperMod

3. 修改配置文件

配置文件是 hugo_blog/hugo.toml。

示例如下：

 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

baseURL = "https://zeepunt.github.io"
languageCode = "zh-cn"
defaultContentLanguage = "zh-cn"
theme = "PaperMod"

[languages]
  [languages.zh-cn]
    title = "Zeepunt 日常随笔"
    weight = 1
    
  [languages.en]
    title = "Zeepunt Daily Scribbles"
    weight = 2

[params]
  defaultTheme = "auto"

[[languages.zh-cn.menu.main]]
  identifier = "article"
  name = "文章"
  url = "/article/"

[[languages.en.menu.main]]
  identifier = "article"
  name = "Articles"
  url = "/article/"

创建完成后的效果如下所示：

• 中文

  

• 英文

  

4. 创建第一篇文章

1. 这里我计划是创建一个 article 目录来存放文章（上述配置文件里面 url 也是 /article/ ）。
2. 由于是使用 Markdown 格式，为了方便资源（比如图片）的引用和管理，文章需要和资源放到同一个目录。

1
2
3
4
5
6
7
8

# 创建文章
$ hugo new article/使用Hugo和Github搭建个人博客搭建/使用Hugo和Github搭建个人博客搭建.md

# 创建完成后的目录结构如下
content/
└── article
    └── 使用Hugo和Github搭建个人博客搭建
        └── 使用Hugo和Github搭建个人博客搭建.md

如果打开这个 .md 文件，可以发现 Hugo 会在这个 .md 文件的顶部添加了一些头部信息，如下所示：

这些头部信息称为 Front Matter。

1
2
3
4
5

+++
date = '2025-10-25T13:49:02+08:00'
draft = true
title = '使用Hugo和Github搭建个人博客搭建'
+++

我们将其修改下，添加一些信息：

1
2
3
4
5
6

+++
date = '2025-10-25T13:49:02+08:00'
draft = false
title = '使用Hugo和Github搭建个人博客搭建'
tags = ["Blog"]
+++

• title：文章的标题

• date：文章的创建或发布时间

• draft：是否为草稿。设为 true 时 hugo 默认不构建。

• tags：文章标签。可以设置多个标签。

其效果如下：

三、生成静态网站

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

$ hugo
Start building sites …
hugo v0.152.1 windows/amd64 BuildDate=unknown


                  │ ZH - CN │ EN
──────────────────┼─────────┼────
 Pages            │      14 │  8
 Paginator pages  │       0 │  0
 Non-page files   │       3 │  0
 Static files     │       0 │  0
 Processed images │       0 │  0
 Aliases          │       4 │  1
 Cleaned          │       0 │  0

Total in 74 ms

执行完成后，静态网站的内容位于 hugo_blog/public 目录下。

四、发布到 Github

Github 上创建一个名为 <用户名>.github.io 的仓库，而且这个仓库必须是公开的。

1
2
3
4
5
6
7

# 当前路径是 hugo_blog 目录
$ cd public
$ git init
$ git remote add origin <仓库地址>
$ git add .
$ git commit -m "blog: $(date +"%Y-%m-%d %H:%M:%S")"
$ git push -u origin master

提交完成后确认仓库的配置。

1. 自动发布

我们可以使用 Github Action 来实现自动发布：当更新 hugo_blog 仓库后，自动生成静态网站文件，并更新到 <用户名>.github.io 仓库。

可以参考：hugo-setup

1. 在 hugo_blog 目录下创建工作流目录

   1	$ mkdir -p .github/workflows

2. 在 workflow 目录中创建 YAML 文件 hugo_update.yaml：

   1 2	$ cd .github/workflows $ touch hugo_update.yaml

   文件内容如下：

   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

   name: Deploy Hugo Site to GitHub Pages on: push: branches: [ master ] jobs: deploy: runs-on: ubuntu-22.04 concurrency: group: ${{ github.workflow }}-${{ github.ref }} steps: # 检出代码 - name: Checkout repository uses: actions/checkout@v4 with: submodules: recursive fetch-depth: 0 # 安装 Hugo - name: Setup Hugo uses: peaceiris/actions-hugo@v3 with: hugo-version: '0.152.1' extended: false # 静态构建 - name: Build with Hugo run: hugo --minify --gc # 部署到 GitHub Pages - name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pages@v3 with: personal_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }} external_repository: <指定仓库> # 这里一般是 <用户名>/<用户名>.github.io publish_dir: ./public publish_branch: master force_orphan: true user_name: 'Zeepunt' user_email: <个人邮箱> # 个人邮箱 commit_message: 'blog: ${{ github.event.head_commit.timestamp }}'

2. 创建 PAT 令牌

点击 GitHub 页面右上角的头像，进入 Settings：

• 在左侧边栏找到 Developer settings，然后选择 Personal access tokens 下的 Tokens (classic)。

• 点击 Generate new token (classic)。

• 为令牌起一个易于识别的名称，例如 Hugo Blog Deploy。

• 过期时间：为了长期使用的便利性，建议选择 No expiration。如果出于安全考虑选择有效期，请记住到期前需要更新。

• 权限范围：务必勾选 repo 权限，这能赋予它对所有仓库的完全访问权限。

• 点击 Generate token，并立即复制生成的令牌字符串。

在仓库中添加令牌

• 进入存放 Hugo 源代码的仓库（例如 <用户名>/hugo_blog）。

• 点击 Settings 选项卡，然后选择 Secrets and variables 下的 Actions。

• 点击 New repository secret。

• Name 处输入 PERSONAL_ACCESS_TOKEN（此名称需与工作流文件中的引用保持一致）。

• Value 处粘贴您刚才复制的令牌。

• 点击 Add secret 保存。