前言

之前试过在blogger和GitHub Pages搭建博客，也用过docker+WordPress搭建，但是后者因为日志过大，加上markdown写起来不是很方面，所以现在又用hugo+GitHub Pages +Actions来搭，这样markdown写起来方便，离线的时候用起来方便

优势

对于docker搭建wordpress的博客是很舒服的，不用考虑图床之类的问题。只需要担心的是wordpress插件会不会出问题之类的，配置需要一些时间，反向代理域名和端口，还有CF配置SSL等。

hugo相比hexo生成个人感觉好用一些。首先hugo部署很方便，而且环境配置只需要配置环境变量然后就能用了。配置问题主要是Actions的部分，还有就是CF的ip添加一次只能添加一个，比Google的麻烦一些。但是Actions确实很好用，省去了本地生成的麻烦，只需要push到博客仓库就行了（此处的博客仓库是一个私有仓库，不是公开的仓库）。

部署

首先，需要拥有一个github账号，并且在这个账号中建立两个仓库：

1.用于存储hugo site的源码，并且在这个仓库中加入Actions的文件，用于实现github的actions生成。

2.用于存储生成之后的网站的源码，这个仓库就是用于展示的仓库。

完成前置条件之后，部署博客的大体思路是这样的：

作者首先安装Go语言的环境和hugo，然后初始化site，配置本地的site文件，推送到github的源码仓库，由源码仓库中的Actions执行生成name.github.io仓库中的内容，打开这个链接就可以访问了，之后配置cloudflare之类的比较简单了。

go和hugo环境配置

下载go语言的安装包，添加bin目录到环境变量中（win平台是安装的，所以不需要）：

下载地址：https://go.dev/dl/

1
2
3
4
tar -zxvf '下载的文件名字' go
# 添加环境变量
export PATH=$PATH:/usr/local/go/bin
authorized_keys

安装hugo并且配置hugo

1
2
3
4
# 下载地址：https://github.com/gohugoio/hugo/releases
# 解压缩到对应的目录，然后添加环境变量，当在win中运行
where hugo
#如果有结果就说明hugo配置好了

在网站的父目录中创建网站：

1
hugo new site "your site's name"

添加主题，因为这个时候的hugo网站是没有主题的，所以需要添加主题，在此之前，先说明hugo在本地的生成是有两种的，一种是hugo server -D这种是生成所有的文章预览，包括草稿，如果开始的框中的draft:true这种情况下，只用hugo server是无法生成预览的，把true改为false，才能生成预览，这种情况之下，及时推送到github然后actions也没有文章可以看到。

清除git所用的代理配置：

1
2
3
git config --global --unset http.proxy
git config --global --unset https.proxy
# 手动删除 ~/.gitconfig 也可以实现重置配置的效果

将theme\examplseSite里面的config.yoml东西复制出来，放到网站的根目录中，这时候就基本相当于配置好了一个基本的网站了（里面的内容还是examplesite的）。

推送到github

推送到github需要有两个步骤，首先需要将账户登录到git，这里需要配置密钥对，生成的方式：

1
2
ssh-keygen -t rsa -b 4096 -C "deploy_github_pages" -f '这里是你想要给密钥的命名'
# 生成一个key文件还有一个key.pub文件（假设在-f之后的名字是key）

第一个密钥对：

首先配置github认证需要的两个密钥，私钥放到本地，公钥上传到Settins|SSH and GPG keys|Authentication Keys 这里。

然后就可以git来推送文件了。

第二个密钥对：

用于连接两个仓库，一个是私有仓库用于存放hugo site根目录中的所有文件，在这个仓库中的Settings|Secrets and variables|中部署私钥，这里的私钥就是类似key里面的内容，直接全部复制到里面就行了，这里的名字要记住，然后在actions中的文件配置需要用到。

公钥的位置放到name.github.io仓库中的Settings|Deploy keys位置，建议起名字的时候可以和前面的私钥对应，或者方便识别。

配置好了密钥之后，可以初始化本地仓库，完成之后就可以推送到远程的私有仓库，在私有仓库中的actions页面执行生成静态网站的步骤。

1
2
3
4
5
git init -b main
# 合并仓库到私有仓库
git remote add origin git@github.com:xxx/xxxx.git
# 没办法的情况下强行合并
git push -f origin master #注意，这一步可能有问题，建议根据自己的实际的branch更改master或者main

一般情况下如果顺利的部署步骤是：

1
2
3
4
# cd 到网站的根目录
git add .
git commit -m "你为这次推送的评论"
git push origin main # 因为我的分支是main，所以推送到main

配置actions

actions是一个可以进行自动化测试的工具，比如可以通过配置文件，将源代码生成为./public中的静态网站，并且推送到一个共有的仓库，这样私有仓库中的一些源码等内容不会在共有仓库中显示。

对于github 的actions工具，会有一个类似shell的运行结果，如果出现了失败，会有报错，根据报错搜索就可以找到解决方案，一般来说google出来的结果可以解决，actions的运行报错类似如

报错实例

配置这个文件，需要在网站的根目录中添加目录：.github/workflows/写一个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
name: Hugo Blog GitHub Pages Actions

on:
  push:
    branches:
      - main  # Set a branch name to trigger deployment
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-22.04
    permissions:
      contents: write
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v3.5.3
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.114.1'
          # extended: true

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        # If you're changing the branch from main,
        # also change the `main` in `refs/heads/main`
        # below accordingly.
        if: github.ref == 'refs/heads/main'
        with:
          external_repository: name/name.github.io  # 更改这里适配你的仓库
          deploy_key: ${{ secrets.xxxxxx }} #　这里的就是上面提到的私有仓库的私钥
          publish_branch: main
          publish_dir: ./public

这个文件的配置我也是参考了网上的连接，是一个github仓库，在里面会有指导怎么写yml文件，我这个文件是满足部署，可以运行的。

报错解决

Not submodule

在部署的时候，出现"Not submodule……."（这里的报错涉及到的是主题），这个需要在根目录中写一个名字是.gitmodules的文件，然后将你的主题的submodule放进去就行，一般hugo的主题有一个仓库是存放了一堆submodule的，在里面更改为如下的方式就好：

1
2
3
4
5
# 比如我的主题是 hugo-tranquilpeak-theme
# 添加如下文件到.gitmodules文件中，需要注意的是目录和双引号中的目录问题，和仓库中的有区别
[submodule "themes/hugo-tranquilpeak-theme"]
	path = themes/hugo-tranquilpeak-theme
	url = https://github.com/kakawait/hugo-tranquilpeak-theme.git

或者在添加主题的时候，就将主题以子模组的形式添加到themes文件夹中：

1
2
# 主题：stack
git submodule add https://github.com/CaiJimmy/hugo-theme-stack/ themes/hugo-theme-stack

如果markdown文件中出现了错误，也会导致报错，不放心的话可以在push的时候看着actions的运行状态。

图片无法显示

设置图片的根目录，在文章首框中加入：

1
2
3
typora-root-url: ./..\..\static
# 偏好设置：复制到相对路径
../../static/images/${filename}

或者将markdown文件命名为：index.md，然后将图片复制到文章的项目目录下，形成如下的结构：

1
2
├─2023
│  └─Hugo+GithubPages+Actions博客搭建

这个文章中下含有了文章index.md和图片报错实例，这个图片的名字是可以命名的，这样也好在本地使用。

站点修改

设置avatar.png

在根目录中的assets文件夹中新建img文件夹，放入avatar.png。

站点头像

实际目录：/static/images/favicon.ico

设置：

1
2
3
4
5
6
params:
    mainSections:
        - post
    featuredImageField: image
    rssFullContent: true
    favicon: /images/favicon.ico 

设置评论

采用Disqus作为评论系统，只需要更改网站根目录中的config.yaml文件中disqusShortname的值即可，改为Disqus的账户名称（需要注册Disqus账户并且用邮箱激活）。

需要在Disqus添加站点，访问：🔗，选择I want to install Disqus on my site，选择免费计划，可以不配置平台，然后在配置中一路默认最后选择完成配置就行。

更换域名、用户名、仓库名字

域名

更换域名需要更换cloudflare的DNS记录，nameserver还给CF的，强制https，A记录添加为185.199.10x.153（x为9-11），代理状态为仅DNS。

用户名字

如果更换了仓库名字或者github用户名字、域名，需要更改配置文件（ymal中的内容，和hugo.yml external_repository:，static中的CNAME记录，这里可以用everything搜索CNAME修改）。

一般是更改config中的内容，改为用户名+github…的形式，域名需要将所有的旧域名替换成新域名，如果出现无法push的情况，可以更换密钥，添加到公开仓库的时候可以勾选上Allow write access，可以解决128报错无法推送的问题。

报错

如果ssh更新但是没有添加邮箱（-C），可以把私钥名字改为id_rsa重新push。

发布文章

上面用的是index.md来存放文章内容，所以写新文章的时候用：

1
2
hugo new .\content\post\2023\文章标题\index.md
# 或者直接new post也可以

这样图片直接复制到当前文件夹就行了。

开启KaTex支持

通过修改根目录下的config.yaml中的

1
2
article:
        math: true

即可开启数学公式支持。

双机更新

如果有两个不同系统的笔记本，比如一个Ubuntu和一个Windows，可以在两个设备上同时clone下来仓库，比如已经完成了另一个设备上的git安装，还没clone仓库到本地时候。

首先将私钥复制到用户目录的ssh文件中，然后在相关目录中直接：

1
git clone ......

发生更新之后，即使博客的更新只有一个人，但是仍然需要检查是不是相比仓库发生了更新，如在win上更新之后但是没有pull，但是mac端先pull 到主要分支，如果下次在win上直接pull而不比较内容，会出现覆盖mac端pull的情况，所以需要检测当前的版本是不是最新的，如果和远程仓库有区别需要先把远程仓库的更新拉到本地然后pull：

1
2
3
4
5
6
git fetch # 会在不更新本地仓库的情况下获取远程仓库的更新情况
git diff --stat main origin/main # 比较本地和远程仓库内容区别,如果没有结果就是ok，如果有区别，视情况选择merge
git merge # 将远程已经更新的内容更新到本地
# 如果merge 报错，如果确定了远程是需要拉到本地的情况，就stash
git stash
git merge

到此就完成了两个主机上博客的更新部署，只不过需要在更新的时候先检查远程和本地的区别，然后再选择是否更新。

报错

参考：如果git diff无反应怎么办

merge 报错：如果merge提示报错怎么办

hugo server 出现Page not found：

1
2
3
WARN  found no layout file for "html" for layout "archives" for kind "page": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.
WARN  found no layout file for "html" for kind "page": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.
WARN  found no layout file for "html" for layout "search" for kind "page": You should create a template 

这种情况就是hugo的theme文件夹中的主题问题，因为之前配置过submodule，github pull下来之后，发现主题文件夹是空的，因为之前改过主题，所以直接把主题过来了，此时在生成就是动态的网页了。

参考

Hugo actions的指导：https://github.com/peaceiris/actions-hugo

报错解决：https://www.youtube.com/watch?v=DMgEGpqXEM4

主题gitmodules：https://github.com/gohugoio/hugoThemes/blob/master/.gitmodules

标题无法从一级标题开始显示：https://huweim.github.io/post/blog_hugo_%E7%9B%AE%E5%BD%95%E7%BB%93%E6%9E%84/