**笔记保留仅供个人复习，请不要参考这篇笔记搭建博客。写了新的思路更清晰的 Hugo 博客搭建与部署博文 → 利用 Github Pages 与 Github Action 搭建并部署 Hugo 博客 **

在 Windows 上搭建 Hugo 博客之 Github 部署填坑记

这篇博文记录了本 CS 菜鸟搭建 Hugo 博客的崎岖过程，内容涵盖以下方面：

  1. Hugo 在 Windows 10 系统上的下载与安装（简略说明）
  2. Hugo 主题的下载、安装与配置（简略说明）
  3. 将 Hugo 从本地部署到 Github 个人页面
  4. 发布、修改、删除博文
  5. 将 Github 默认的个人页面 URL 修改为自定义二级域名

正式阅读正文前您需要了解，本人在 CS 方面完完全全就是菜鸟一只。到底有多菜鸟呢？在 Hugo 的部署过程中需要大量 git 操作，而我是因为要建 Hugo 才开始学习 git 的基础操作。这篇博文算是我在自建 Hugo 博客过程中各路乱抄的作业答案整理归纳，抄作业过程中，我由于不明原理而抄错答案，导致博客运行出现了很多问题，这篇博文也对这些错误、错误原因和解决方式进行了总结。博文中可能难免出现描述性错误或可以进一步完善的地方，如有修改建议，希望您可以在下方评论指正，或通过 fediverse 账号、邮箱联系我修改。

Table of Contents

一、Hugo 在 Windows 10 系统上的下载与安装

Hugo 的官方网站上有 Hugo 在各种系统上安装的详细说明视频，对于熟悉 Window 10 系统操作的朋友来说并不困难，这里不再做复述和进一步说明，详情请看 Hugo-Getting Started-Install Hugo 。

按照视频下载安装后，您的计算机中应该有一个名为"Hugo"的目录、一个名为"Sites"的用于存放所有博客站点的目录，Hugo 目录下应有三个文件；同时，您的计算中应已下载 Git 程序。

二、Hugo 主题的下载、安装与配置

这部分内容在网络上可以搜索到很多指南，我在操作过程中也遇到没什么问题，也不再进行详细说明。大致有这几个步骤：创建博客、下载安装主题、主题配置、本地测试，完成这部分操作后，您应该已经可以通过 http://localhost:1313/ 查看您选择的主题成功安装在 Hugo 博客上的样子了。

因为每个主题的配置文件、目录都略有不同，在主题配置过程中的具体操作请参考每个主题的说明文档。我的博客选用的主题是 tranquilpeak 。

此时您的博客目录下应该有已经配置完毕的 config.toml 文件，themes 目录下存放着您已经安装完毕的主题。一般这个主题目录不做改动，除非您是主题设计者，对主体魔改有强烈的需求。tranquilpeak 主题目录中有一个名为"exampleSite"的目录，将目录下的所有目录与文件复制粘贴到博客根目录下并覆盖原有的目录、文件，通常主题应该都有类似 exampleSite 的目录，普通的主题调整一般只需在 config.toml 文件与 static 目录中进行。

我建议您主题下载完成后在本地其他的目录再保存一份主题文档。在我自己搭建博客的过程中，混乱的窗口、git 操作失误导致我的博客目录混乱不堪，不得不将整个目录删除重建，通过 Hugo 下载主题，速度可能由于众所周知的网络原因而变得十分缓慢（尽管主题文件往往并不大）。（假如您不幸和我一样需要重建博客，）将备份的主题目录直接粘贴到博客目录下会大大减少您的博客搭建测试时间。

三、将 Hugo 从本地部署到 Github 个人页面

这部分是我自己踩坑最多的地方，其实直到现在，我也没有完全弄清楚这一步怎么做是最好的或最适合自己的，所以在我把 git 基础教程看完并再去整理之前看过的各个教程后，这部分内容应该会再做修改更新。

Hugo 部署到 Github 似乎有两种方式：

  • 创建两个 repository，一个存放 hugo 博客源文件，一个存放个人博客 public 中的文件
  • 创建一个 repository 和两个分支，分支分别存放源文件与 public 目录下的文件（也可创建一个分支，将 public 目录下文件存放进/doc）

但是大多数教程在这部分说得比较模糊，按照一般的教程，教程仅让你创建一个 gh-pages 的 repository（即.github.io，替换为 github 账户用户名）。这部分在网上也能找到很多教程，同样不过多阐释。目前我的博客也是在仅使用默认分支 master 与一个 repository 的情况下建立起来的，并没有上传源文件，这样大概是没办法使用 github actions（自动部署工具）的，不过目前并不影响我正常使用。

特别提醒两点：

第一，创建 repository 完毕后，请在您的 repository 页面上方找到 Settings，点击进入，在下方找到添加主题按钮为你的 github 页面添加一个主题，添加主题后，这个 repository 下会生成两个新文件：README.md 和_config.yml。

hugo
cd public
git add .
git commit -m "xxx(任意内容)"
git remote add origin https://github.com/<user>/<user>.github.io.git
# 这里如果 git 地址写错误上传，可执行 git remote remove origin
git pull origin master
# 这一步将 repository 上的两个文件拉到本地，如果今后远程 repository 中出现变动，需要这一步拉取远程数据，否则无法进行 git push
git push -u origin master

（有一些教程中可能会提示您若 git push 后报错就用 git push -f origin master 这个命令，-f 即 –force ，是强制执行的意思，这个命令会强行删除远程 repository 中的文件后将本地文件 push 到远程，不建议使用；如果本地与远程不同步，请尽量使用 git pull 命令，或使用 git status 寻找的具体问题。）

为什么需要添加主题呢，如果缺少这一步，部署成功后打开你的博客页面可能会出现 css、js 文件加载失败的问题；除此之外，如果您有自定义域名并让博客域名由 http 转换为 https 的需求，这个_comfig.yml 文件是必须的。

第二，执行上面的命令过程中可能会出现这个报错： Git The requested URL returned error:403

出现这个报错有三种可能：

  1. 您没有权限
  2. 您修改过 github 账户用户名与密码
  3. 您曾在电脑上使用过其他 github 账户

我当时出现了两次这个报错，第一次是因为我曾在电脑上安装 hexo 博客，当时我使用的是另一个 github 账户，也就是第三种情况。这是您需要打开控制面板->用户账户->管理 Windows 凭据，向下看有普通凭据，找到关于 git: https://github.com 并删除。 方法来自 WANGXIAOZHANG 的博文

第二次报错是因为我注册的新 github 账户没有在电脑上使用过，也就是第一种情况，这时您需要生成 SSH 添加到 GitHub。

git config --global user.name <username>
git config --global user.email <useremail">

根据您的 github 账户信息替换上面的内容，之后创建 SSH：

ssh-keygen -t rsa -C <useremail>

之后输入：

cat ~/.ssh/id_rsa.pub

将输出结果复制下来，请在您的 repository 页面上方找到 Settings，点击进入并在左边找到 SSH and GPG keys，创建 SSH keys，Title 处可随意填写，在 Key 处输入刚刚复制的结果，之后保存。

在 git bash 输入：

ssh -T [email protected]

输出了你的 github 用户名即代表 SSH 添加成功。 第一次在本地使用这个 github 账户可能跳出新窗口，按照指示输入 github 用户名、邮箱、密钥等信息即可，之后不会再出现这个窗口。

到现在您可以刷新您的 github 页面，里面的内容应该已经更新为和本地的 public 目录下同样的状态，在 url 栏输入 .github.io 应就该会跳出您的博客页面啦~

四、发布、修改、删除博文

添加新博文，在根目录执行命令：

hugo new post/标题.md

或者直接将 markdown 文件拖到您主题对应的存放博文的目录下并添加修改前置数据。

在此之前可以先在 archetypes 目录下添加编辑 post.md 文件，设置文章模板。这里要根据您安装的主题去编辑，在 tranquilpeak 主题中，博文默认储存在 content/post/中，默认博文样式文件名为 post.md，有些主题 content 下的目录可能为 posts，请在您安装的主题目录中的 content 与 archetypes 目录中找到正确的格式。

对于 tranquilpeak 主题，可以这么设置 post.md: (这部分内容来自 SAquarius 的梦想屋 )

---
title: "{{ replace .TranslationBaseName "-" " " | title }}"
date: {{ .Date }}
categories:
- category
- subcategory
tags:
- tag1
- tag2
keywords:
- tech
# 每次编辑文档时请删去这些解释的注释
# 缩略图，最好采用宽度为 750 的图片，可以使用本地文件或者使用 git 图床
# 使用本地图库，请把图片存在 themes/static/images 文件夹下，并且用下面的路径引用
thumbnailImage: /images/cover.jpg
# 缩略图位置，我觉得放在上面好看，如果用的小图片作缩略图
# 可以放在（left 或者 right），设置此项会取代配置文件中默认在下边的设置
thumbnailImagePosition: top
# 这个下边默认就好了，暂时不清楚有什么影响
autoThumbnailImage: yes
metaAlignment: center
# 封面图片，如果选用本地文件的话，和缩略图同样的路径，21：9 的图片效果很好看
coverImage: /images/cover.jpg
# 封面图片的描述引号中的文字可以自己选
coverCaption: "文章 cover 图片描述"
# in 表示文章标题显示在封面图片上，out 表示显示在封面图片的外边，也就是文章开头
coverMeta: in
# 封面图片的覆盖大小，直接默认为 full 吧，21:9 的图片这样设置显示效果真的不错
coverSize: full
---
#缩略显示的梗概，这里把注释删去，写成文章的简介或者梗概，在首页时候可以只显示梗概
<!--more-->
<!-- toc -->

除此之外还可以添加：

slug: xxx
# 标题中含中文时可以利用 slug 简化 url，纯英文标题一般不需要。
# 比如标题"在 Debian 10 / Ubuntu 20.04 上安装 Pleroma（版本：2.2.1）"的默认 url 会很混乱
# 此时可以在 slug 后输入"Pleroma-Installation-on-Linux-using-OTP-releases"（注意冒号后的空格）
# 这篇博文的 url 就会变为"https://suicablog.cobaltkiss.blue/2020/09/pleroma-installation-on-linux-using-otp-releases/"

draft: false
#false 表示这篇博文不是草稿，push 后的博文将直接公开出现在播客主页上
# 若设置为 true，则代表这篇博文是草稿状态。
  • 发布新博文/修改博文
hugo
cd public
git add .
git commit -m "new post added(或任意内容)"
git push -u origin master
  • 删除博文

在尝试删除博文时，由于我之前不了解 git 基础操作，误删了连接本地与和远程 repository 的重要目录".git"，之后便是不断地报错。前往不要直接将 public 删除，这回将里面的隐藏目录".git"以及之前手动 pull 的两个文件一并删除（如果之后设置了自定义域名，CNAME 文件也会被删除），所以请在删除 public 中其他文件时保留：

    • .git 目录
    • README.md
    • _config.yml
    • CNAME

以防万一可以给这几个文件目录做个本地备份）

之后在根目录正常执行：

hugo
cd public
git add .
git commit -m "post deleted(或任意内容)"
git push -u origin master

五、将 Github 默认的个人页面 URL 修改为自定义二级域名

将博客 url 弄到二级域名上是个不错的选择，顶级域名则可用作其他用途。 首先您需要先有个自己的域名，关于买域名购买方式这里也不多阐释，国内的域名需要备案，非国内域名则无需备案；之后您需要为域名申请证书，常见的免费证书申请方案是 Let’s encrypt（三个月后失效，需手动重新申请或添加自动申请 certbot），或者您也可以将您的域名绑定到 cloudflare 上，申请免费的 15 年根域名与通配符域名证书。

之后，您需要在您的域名购买商那边或者 CF 的 DNS 设置界面添加 A 记录，我的顶级域名已添加 A 记录到我的服务器 IP 用作其他用途，这里只需为二级域名添加一条新的 A 记录，指向下面四个域名中的任意一条：

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

详细步骤请参考这篇博文： GitHub Pages 域名绑定及 https 支持的配置步骤

我在操作过程中，始终无法通过 github 强制我的博客 URL 支持 https 协议，最终我是通过在 CF 为耳机域名指定强制 https 页面规则达到 https 支持的。

这样操作后会有个问题，强制导向 https 的博客页面有可能无法加载 CSS、JS 文件，这时您需要对之前我们手动添加的_config.yml 文件进行修改。 （您既可以在 github 上修改后 git pull，也可在本地修改后 git push）

在文件中添加这么两行：

root: /xxx.github.io
url: https://custom.url

（把 xxx 和 custom.url 分别替换为 github 默认页面 url 以及自定义的 url）

之后保存文件 git push 或 git pull 即可让博客页面加载 CSS、JS 文件。

到此为止一个个性化的 Hugo 博客就建好啦！