记录这个博客的搭建过程，使用 Hugo + GitHub Pages搭建，本文使用AI协助创作。

一、安装 Hugo

1. 安装 Scoop 包管理器

1.1 打开 PowerShell

按下 Win + R，输入 powershell，按回车打开 PowerShell 终端。

1.2 允许执行脚本

运行以下命令以设置执行策略，允许执行远程签名的脚本。

1
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

如果提示是否更改执行策略，输入 Y 或 A 确认。

1.3 下载并安装 Scoop

运行以下命令安装 Scoop。

1
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression

安装完成后，可通过以下命令验证 Scoop 是否安装成功。

1
scoop --version

2. 安装 Hugo

2.1 安装 Hugo 扩展版本

运行以下命令安装 hugo-extended 版本。

1
scoop install hugo-extended

安装完成后，验证 Hugo 是否安装成功。

1
hugo version

2.2 更新 Scoop 与 Hugo

更新 Scoop。
1
scoop update
更新 Hugo。
1
scoop update hugo-extended

二、创建与配置站点

1. 创建 Hugo 网站

安装 Hugo 后，可使用 hugo new site 命令快速创建新站点。

1
hugo new site Blog

该命令会在当前目录下生成名为 Blog 的站点文件夹，其中包含基础的站点结构和必要的配置文件。

2. 配置主题

创建站点后，需配置主题以定义网站的外观与功能。Hugo 社区提供了丰富的主题，可通过官网 Themes 浏览并选择适合的风格。选定主题后，进入其项目仓库，通常会有详细的安装与配置说明。以下以 PaperMod 主题为例。

步骤1：进入站点目录 在 PowerShell 中执行以下命令，切换至刚创建的 Blog 目录。

1
cd D:\Blog

步骤2：初始化 Git 仓库

1
git init

步骤3：添加 PaperMod 为子模块 执行以下命令，将主题克隆至 themes/PaperMod 目录。

1
git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

成功后，D:\Blog\themes 目录下会出现 PaperMod 文件夹，内含主题全部文件。

更新主题。

1
git submodule update --remote themes/PaperMod

2.1 配置 Hugo 使用主题

修改站点配置文件以启用主题。

打开 D:\Blog 目录下的 hugo.toml 文件；
在文件末尾添加以下配置，指定使用 PaperMod 主题。
1
theme = "PaperMod"
保存并关闭文件。

2.2 测试主题是否生效

创建一篇测试文章。
1
hugo new content posts/first-post.md
启动 Hugo 本地服务器进行预览。
1
hugo server --buildDrafts
在浏览器中访问 http://localhost:1313，即可看到应用了 PaperMod 主题的站点样式。

2.3 修改主题配置

参考

教程.https://github.com/adityatelange/hugo-PaperMod/wiki/Installation

样例.https://github.com/adityatelange/hugo-PaperMod/blob/exampleSite

我的配置：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
 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
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
baseURL = "https://flash122u.github.io/"
title = "flash122u's blog"
theme = "PaperMod"

enableRobotsTXT = true  # 启用 robots.txt 文件生成
buildDrafts = false     # 不构建草稿文章
buildFuture = false     # 不构建未来日期的文章
buildExpired = false    # 不构建过期文章

[pagination]
  pagerSize = 5  # 每页显示5篇文章

[minify]
  disableXML = true    # 禁用 XML 压缩
  minifyOutput = true  # 启用 HTML/CSS/JS 压缩

[params]
  env = "production" # 启用谷歌分析、开放图谱、Twitter卡片和结构化数据
  title = "flash122u's blog"  # 站点标题，建议改为你自己的
  description = "这是我的个人博客，分享技术学习和生活感悟"  # 站点描述
  keywords = ["Blog", "Technology", "Learning"]  # 站点关键词
  author = "flash122u"  # 作者名称
  # author = ["Me", "You"] # 多个作者
  images = ["/images/avatar.png"]  # 开放图谱图片，替换为你的图片路径
  DateFormat = "January 2, 2006"  # 日期格式
  defaultTheme = "dark" # 默认主题：auto, dark, light
  disableThemeToggle = false  # 允许用户切换主题
  ShowReadingTime = true  # 显示阅读时间
  ShowShareButtons = false  # 显示分享按钮
  ShowPostNavLinks = true  # 显示上一篇/下一篇导航
  ShowBreadCrumbs = true  # 显示面包屑导航
  ShowCodeCopyButtons = true  # 显示代码复制按钮（设为true如果常贴代码）
  ShowWordCount = true  # 显示字数统计
  ShowRssButtonInSectionTermList = true  # 在分类/标签页显示RSS按钮
  UseHugoToc = true  # 使用Hugo的目录生成
  disableSpecial1stPost = false  # 不禁用第一篇特殊文章
  disableScrollToTop = false  # 不禁用滚动到顶部按钮
  comments = false  # 禁用评论（设为true并配置评论系统如Disqus）
  hidemeta = false  # 不隐藏元数据
  hideSummary = false  # 不隐藏摘要
  showtoc = false  # 不显示目录（设为true如果文章较长）
  tocopen = false  # 目录默认不展开
  
  [params.assets]
    # disableHLJS = true # 禁用highlight.js高亮
    # disableFingerprinting = true # 禁用资源文件指纹
    favicon = "/favicon.ico"  # 网站图标路径
    favicon16x16 = "/favicon-16x16.png"  # 16x16图标
    favicon32x32 = "/favicon-32x32.png"  # 32x32图标
    apple_touch_icon = "/apple-touch-icon.png"  # iOS主屏幕图标
    safari_pinned_tab = "/safari-pinned-tab.svg"  # Safari固定标签页图标
  
  [params.label]
    text = "Home"  # 首页链接显示文本
    icon = "/apple-touch-icon.png"  # 首页图标
    iconHeight = 35  # 图标高度
  
  # 个人资料模式（个人主页样式）
  [params.profileMode]
    enabled = true # 需要显式设置为true才能启用
    title = "flash122u's blog"  # 资料模式标题
  subtitle = "If people do not believe that mathematics is simple,\n\nit is only because they do not realize how complicated life is.\n\n  -- *John von Neumann*"
  imageUrl = "/images/avatar.png"  # 头像图片路径
    imageWidth = 150  # 头像宽度
    imageHeight = 150  # 头像高度
    imageTitle = "my avatar"  # 头像标题
    
    [[params.profileMode.buttons]]
      name = "Posts"  # 按钮1：文章列表
      url = "posts"
    
    [[params.profileMode.buttons]]
      name = "Tags"  # 按钮2：标签页
      url = "tags"

    [[params.profileMode.buttons]]
      name = "About"  # 按钮3：about页
      url = "about"
  
  # 首页信息模式
  [params.homeInfoParams]
    Title = "Hi there \U0001F44B"  # 首页标题
    Content = "欢迎来到我的博客，这里分享技术学习和生活感悟"  # 首页内容
  
  # 社交媒体图标
  [[params.socialIcons]]
    name = "x"  # X（原Twitter）
    url = "https://x.com/"
  
  [[params.socialIcons]]
    name = "github"  # GitHub
    url = "https://github.com/flash122u"  # 改为你的GitHub地址
  
  [params.analytics]
    # 谷歌分析验证标签（需要时添加）
    [params.analytics.google]
      SiteVerificationTag = "XYZabc"
    [params.analytics.bing]
      SiteVerificationTag = "XYZabc"
    [params.analytics.yandex]
      SiteVerificationTag = "XYZabc"
  
  [params.cover]
    hidden = true # 封面图片：在所有地方隐藏但不影响结构化数据
    hiddenInList = true # 在列表页隐藏
    hiddenInSingle = true # 在单篇文章页隐藏
  
  [params.editPost]
    URL = "https://github.com/flash122u/hugo-blog-source"  # 编辑文章链接，改为你的仓库
    Text = "edit" # 编辑文本
    appendFilePath = false # 在编辑链接后追加文件路径
  
  # 搜索功能配置（Fuse.js）
  [params.fuseOpts]
    isCaseSensitive = false  # 不区分大小写
    shouldSort = true  # 排序结果
    location = 0  # 匹配位置
    distance = 1000  # 匹配距离
    threshold = 0.4  # 匹配阈值
    minMatchCharLength = 0  # 最小匹配字符长度
    limit = 10 # 搜索结果限制数量
    keys = ["title", "permalink", "summary", "content"]  # 搜索的字段

# 启用分类和标签系统（重要！）
[taxonomies]
  category = "categories"  # 分类
  tag = "tags"  # 标签

# 导航菜单配置
[[menu.main]]
  identifier = "categories"
  name = "Categories"
  url = "/categories/"  # 分类页面
  weight = 10  # 权重（排序用，数值越小越靠前）
  
[[menu.main]]
  identifier = "tags"
  name = "Tags"
  url = "/tags/"  # 标签页面
  weight = 20

[[menu.main]]
  identifier = "rss"
  name = "RSS"
  url = "/index.xml"  # RSS订阅地址
  weight = 30

[[menu.main]]
  identifier = "archive"
  name = "Archive"
  url = "/archives/"  # 文章归档页面
  weight = 30

[[menu.main]]
  identifier = "search"
  name = "Search"
  url = "/search/"  # 搜索页面
  weight = 30

[[menu.main]]
  identifier = "about"
  name = "About"
  url = "/about/"  # 关于页面
  weight = 40

# 语法高亮设置
# 参考：https://github.com/adityatelange/hugo-PaperMod/wiki/FAQs#using-hugos-syntax-highlighter-chroma
pygmentsUseClasses = true

[markup]
  [markup.highlight]
    noClasses = false
    # anchorLineNos = true  # 为行号添加锚点
    # codeFences = true     # 启用代码围栏
    guessSyntax = true    # 猜测语法
    lineNos = true        # 显示行号
    style = "monokai"     # 代码高亮样式

三、部署到 GitHub Pages

这个博客采用双仓库方案。

源码仓库：命名为 hugo-blog-source，用于存放 Hugo 配置、主题、文章等所有源码；
Pages 仓库：命名为 flash122u.github.io（必须为「用户名.github.io」格式），仅存放 Hugo 生成的静态网页文件，供 GitHub Pages 展示。

整体流程：在本地修改源码 → 推送至源码仓库 → GitHub Actions 自动构建静态文件 → 将静态文件推送至 Pages 仓库 → GitHub Pages 自动更新生效。

1. 创建两个 GitHub 仓库

仓库 1：Pages 仓库

登录 GitHub → 点击右上角「+」→「New repository」；
Repository name：填写 flash122u.github.io（必须严格匹配，否则 Pages 无法正常访问）；
Visibility：选择 Public（Pages 仓库必须公开）；
无需勾选「Add a README file」，直接点击「Create repository」。

仓库 2：源码仓库

再次点击「New repository」；
Repository name：填写 hugo-blog-source；
Visibility：可选择 Public 或 Private；
无需勾选「Add a README file」，直接点击「Create repository」。

2. 将本地 Hugo 站点关联至源码仓库

打开 Windows PowerShell，依次执行以下命令。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
# 1. 进入本地 Hugo 站点目录
cd D:\Blog

# 2. 创建 .gitignore 文件（排除无需推送的目录与文件）
echo "public/" >> .gitignore
echo "resources/" >> .gitignore
echo ".DS_Store" >> .gitignore
echo "Thumbs.db" >> .gitignore
echo ".hugo_build.lock" >> .gitignore

# 3. 关联源码仓库
git remote add origin https://github.com/flash122u/hugo-blog-source.git

# 4. 添加所有源码文件并提交
git add .
git commit -m "Initial commit: Hugo source with PaperMod theme"

# 5. 推送本地代码至源码仓库的 main 分支
git push -u origin main

3. 创建个人访问令牌（PAT）

默认的 GITHUB_TOKEN 无法访问其他仓库，因此需要创建 PAT 并赋予相应权限。

步骤1：点击 GitHub 右上角头像 →「Settings」→ 滚动至底部「Developer settings」； 步骤2：点击「Personal access tokens」→「Tokens (classic)」； 步骤3：点击「Generate new token (classic)」。

Note：填写令牌名称（例如 hugo-deploy-token）；
Expiration：选择 No expiration（避免令牌过期导致部署失败）；
Scopes：勾选 repo 下的所有权限（必须全部勾选，否则无法推送至 Pages 仓库）； 步骤4：滚动到底部并点击「Generate token」→ 立即复制生成的令牌（以 ghp_ 开头，关闭页面后将无法再次查看，先复制到文本编辑器）。

4. 将 PAT 添加至源码仓库的 Secrets

打开源码仓库：https://github.com/flash122u/hugo-blog-source；
点击「Settings」→ 左侧「Secrets and variables」→「Actions」；
点击「New repository secret」。
- Name：填写 PERSONAL_TOKEN（必须与后续的配置文件保持一致）；
- Value：粘贴刚才复制的 PAT 令牌；
点击「Add secret」保存。

5. 配置 GitHub Actions 实现自动部署

5.1 创建 Actions 配置文件

在本地 D:\Blog 目录下，手动创建文件夹 .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
name: Deploy Hugo to GitHub Pages

on:
  push:
    branches: ["main"]
  # 允许手动触发部署
  workflow_dispatch:

# 配置权限
permissions:
  contents: read  # 读取源码仓库内容
  pages: write    # Pages 相关权限
  id-token: write # 身份验证权限

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

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      # 步骤1.拉取源码仓库代码（包含 PaperMod 主题子模块）
      - name: Checkout source code
        uses: actions/checkout@v4
        with:
          submodules: true  # 必须开启，以拉取主题子模块
          fetch-depth: 0

      # 步骤2.安装 Hugo 环境
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: "latest"
          extended: true  # 使用扩展版以兼容 PaperMod 主题

      # 步骤3.生成静态文件（输出至 public 目录）
      - name: Build static files
        run: hugo --minify

      # 步骤4.部署静态文件至 Pages 仓库
      - name: Deploy to flash122u.github.io
        uses: peaceiris/actions-gh-pages@v4
        with:
          # 使用自定义 PAT 令牌（替代默认的 GITHUB_TOKEN）
          personal_token: ${{ secrets.PERSONAL_TOKEN }}
          # 指定 Pages 仓库地址（替换为自己的 Pages 仓库地址）
          external_repository: flash122u/flash122u.github.io
          # 静态文件目录
          publish_dir: ./public
          # 推送至 Pages 仓库的 main 分支
          publish_branch: main
          # 强制覆盖，确保 Pages 仓库仅包含静态文件
          force_orphan: true
          # 配置 Git 提交信息（避免报错）
          user_name: "github-actions[bot]"
          user_email = "github-actions[bot]@users.noreply.github.com"

5.2 将 Actions 配置推送至源码仓库

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# 进入本地站点目录
cd D:\Blog

# 添加配置文件
git add .

# 提交修改
git commit -m "Add GitHub Actions workflow for double repo deployment"

# 推送至源码仓库
git push origin main

6. 配置 Pages 仓库的 GitHub Pages 来源

（一般为默认配置，无需修改。）

打开 Pages 仓库：https://github.com/flash122u/flash122u.github.io；
点击「Settings」→ 左侧「Pages」；
在「Build and deployment」区域。
- Source：选择 Deploy from a branch；
- Branch：选择 main，目录选择 / (root)；
点击「Save」保存配置。

7. 验证部署结果

验证步骤1：打开源码仓库 hugo-blog-source → 点击「Actions」标签，查看 workflow 运行状态（绿色对勾表示成功）； 验证步骤2：运行成功后，打开 Pages 仓库 flash122u.github.io，可见 main 分支下已出现 html、css、js 等静态文件； 验证步骤3：等待 1-2 分钟，访问 https://flash122u.github.io，即可看到应用了 PaperMod 主题的 Hugo 站点，说明部署成功。

四、更新文章与配置

后续修改或添加内容。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# 1. 进入本地站点目录
cd D:\Blog

# 2. 创建新文章（示例）
hugo new content posts/my-new-article.md

# 3. 编辑文章（使用编辑器打开 posts/my-new-article.md 并撰写内容）

# 4. 提交修改至本地仓库
git add .
git commit -m "Add new article: 我的新文章"

# 5. 推送至源码仓库，触发自动部署
git push origin main  # 若本地分支为 master，请改为 git push origin master:main

推送后，GitHub Actions 将自动运行，等1-2分钟，新内容便会同步至 https://flash122u.github.io。

五.集成 Umami 统计

1.注册 Umami

访问 Umami Cloud 注册页，输入邮箱、密码完成注册。
查收邮箱验证码并验证，登录后按提示选择数据区域，进入控制台。
点击 Add website，输入博客域名，提交后复制生成的 websiteId（一串 UUID）。

2.配置 hugo.toml

在博客根目录的 hugo.toml 中添加以下配置（保留原有内容，新增 analytics 节点）：

1
2
3
4
5
[params]
  [params.analytics]
    [params.analytics.umami]
      src = "https://cloud.umami.is/script.js"  # Umami 官方脚本地址
      websiteId = "630fc019-42d4-4053-894a-95f696994ca3"  # 替换为你的 websiteId

3.创建 extend_head.html 模板

在博客根目录新建路径 layouts/partials/，在该目录下创建 extend_head.html 文件。
写入以下代码，实现脚本的条件加载：

1
2
3
4
5
6
7
{{- /* Umami Analytics */ -}}
{{- if .Site.Params.analytics.umami.src -}}
<script async defer
        data-website-id="{{ .Site.Params.analytics.umami.websiteId }}"
        src="{{ .Site.Params.analytics.umami.src }}">
</script>
{{- end -}}

4.部署与验证

提交代码并推送到 GitHub：

1
git add . && git commit -m "Add Umami analytics" && git push

等待 GitHub Actions 完成部署，访问博客。
打开浏览器开发者工具（F12），在 Network 面板搜索 script.js，确认请求成功且 data-website-id 正确。
回到 Umami 控制台，即可查看实时访问数据。

一、安装 Hugo#

1. 安装 Scoop 包管理器#

2. 安装 Hugo#

二、创建与配置站点#

1. 创建 Hugo 网站#

2. 配置主题#

2.1 配置 Hugo 使用主题#

2.2 测试主题是否生效#

2.3 修改主题配置#

三、部署到 GitHub Pages#

1. 创建两个 GitHub 仓库#

2. 将本地 Hugo 站点关联至源码仓库#

3. 创建个人访问令牌（PAT）#

4. 将 PAT 添加至源码仓库的 Secrets#

5. 配置 GitHub Actions 实现自动部署#

5.1 创建 Actions 配置文件#

5.2 将 Actions 配置推送至源码仓库#

6. 配置 Pages 仓库的 GitHub Pages 来源#

7. 验证部署结果#

四、更新文章与配置#

五.集成 Umami 统计#

1.注册 Umami#

2.配置 hugo.toml#

3.创建 extend_head.html 模板#

4.部署与验证#