前言

首先介绍用到的工具：

Hugo：一个静态网站生成器，内置大量好看的主题，可以将 Markdown 文件转换为 HTML 文件，应该是开源项目，使用 go 语言编写（Google 开发的语言–大概）。
简而言之，这是一个框架，可以快速搭建个人博客。

Github：一个代码托管平台，可以托管代码，提供版本控制，可以与 Hugo 配合使用。
简而言之，这是一个开源的远程仓库云端存储，可以存储代码，提供版本控制追踪，可以用于托管部署我们的 Hugo 网站。

Git Cmd：一个 Git 命令行工具，可以与 Github 配合使用，可以方便地管理执行 Git 命令代码。

部署步骤

安装 Hugo

• 下载 Hugo 压缩包，解压到任意目录，比如 C:\Hugo。

配置 Hugo

• 打开命令行工具，切换到 Hugo 目录，输入以下命令：

1

hugo new site dev

• 该命令用于创建一个名为 dev 的网站目录。

1

cd dev

• 进入 dev 目录。

安装 Hugo 主题

• 下载喜欢的 Hugo 主题，解压到 themes 目录，即 dev\themes。

• 复制 exampleSite 文件夹下的 content 与 hugo.yaml 文件到 dev 目录。

• 打开 hugo.yaml 文件，修改 baseurl 与 theme 选项。

• 如图所示：baseurl对应的是网站的根目录（即网站的域名此处应为 yourusername.github.io如果按接下里的流程走的话），theme对应的是主题名称。

• 补充：此处的 hugo.yaml 文件是 Hugo 的配置文件，同样的还有另一种 config.toml 文件，同为配置文件，可以根据自己的需求进行修改。

安装 Git

• 下载 Git 压缩包，安装到任意目录，比如 C:\Git。

配置 Git

• 打开 Git 命令行工具，输入以下命令：

1

git init

• 此举是 Git 版本控制系统中的一个基本命令，它的主要作用是在指定目录下创建一个新的 Git 仓库。这个命令会初始化一个空的仓库，为项目的版本控制和代码管理奠定基础。

• 补充：执行 git init 后，Git 会在当前目录下创建一个名为 .git 的隐藏文件夹。这个文件夹是非常重要的，因为它包含了版本控制系统的所有必要信息，如配置文件、分支、标签等。这个文件夹是 Git 仓库的心脏，没有它，版本控制就无法进行，git 开头代码将报错。

1
2

git config --global user.name "your name"
git config --global user.email "your email"

• 将 your name 和 your email 替换为你的真实姓名和邮箱。

• 此举是首次执行 Git 命令，会在你的电脑上创建一个全局配置，之后就表示你这台机器上所有的 Git 仓库都会使用这个配置，当然也可以对某个仓库指定不同的用户名和 Email 地址。

• 补充： 查看全局配置代码：git config -l（这是 l 不是 1）

补充 Git （自动部署需要）

• 新建 .gitignore 文件，添加忽略规则，存放在项目根目录下（此处即 dev 目录）。

• 新建 deploy.yaml 文件，添加自动部署脚本，存放在项目根目录(dev 目录)下的 .github/workflows 目录下(该目录需自己创建)。

 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

name: deploy

# 代码提交到main分支时触发github action
on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: "latest"
          extended: true

      - name: Build Web
        run: hugo -D

      - name: Deploy Web
        uses: peaceiris/actions-gh-pages@v4
        with:
          PERSONAL_TOKEN: ${{ secrets.变量名 }}----需要修改
          EXTERNAL_REPOSITORY: 用户名/博客域名（yourusername.github.io）------需要修改
          PUBLISH_BRANCH: main
          PUBLISH_DIR: ./public
          commit_message: auto deploy

创建 Github 仓库（重点）

• 登录 Github 网站，点击右上角的 + 号，选择 New repository，输入仓库名称，点击 Create repository。

• 此处重点在于仓库名称的设置：

• 创建一个部署 Hugo 网站的仓库，设置为公开仓库，并命名为 yourusername.github.io，其中 yourusername 是你的 Github 用户名。 （注意：仓库名称应为 yourusername.github.io，否则可能导致后期混乱。）

• 创建一个存储主要资源的仓库，设置为私有仓库，并命名为 yourusername.github.io.source，其中 yourusername 是你的 Github 用户名。 （此处名称随意，但应与网站仓库名称不同且便于记忆。）

获取 token （自动部署需要）

• 点击个人头像，选择 Settings（设置），选择 Developer settings（开发者设置），选择 Personal access tokens（个人访问令牌），点击 Generate new token（生成新令牌，两个都可以）。

• 输入 Token description（令牌描述），日期选择 No expiration（永不过期），勾选 repo（仓库），workflow（工作流），点击 Generate token（生成令牌）。

• 复制生成的 ACCESS_TOKEN 值（该值只会显示一次，请务必妥善保管），点击 Close 按钮。

• 进入刚刚创建的 yourusername.github.io.source 仓库，点击 Settings，选择 Secrets（机密），点击 New repository secret（新增机密），输入 ACCESS_TOKEN（刚复制的令牌值），点击 Add secret（添加机密）。

• 此处的 ACCESS_TOKEN 即为 Github 网站生成的个人访问令牌，用于自动部署。

部署网站

• 切换到 dev 目录，输入以下命令：

1

hugo -D

• 该命令用于将 Markdown 文件转换为 HTML 文件，并将生成的 HTML 文件保存在 dev\public 目录下。
• (hugo -D 是 Hugo 的编译命令，-D 参数表示将生成的 HTML 文件放入 public 目录下，方便部署。)

1

git branch -M main

• 该命令用于将当前分支重命名为 main，因为 Github 网站的默认分支名为 main。
• （git branch -M为重命名分支命令，-M参数为强制重命名，main是新分支名）

1
2

git remote add origin https://github.com/yourusername/yourusername.github.io.git
git remote add source https://github.com/yourusername/yourusername.github.io.source.git

• 该命令用于将本地仓库与 Github 仓库建立联系，并将本地仓库推送到 Github 仓库。
• （git remote add为添加远程仓库命令，origin和是部署博客展示的远程仓库名称，https://github.com/yourusername/yourusername.github.io.git是远程仓库的地址，source是存储主要资源的远程仓库名称，https://github.com/yourusername/yourusername.github.io.source.git是远程仓库的地址—-分为两个仓库，一个用于部署博客展示，一个用于存储主要资源）

1

git add .

• 该命令用于将所有修改的文件添加到暂存区（.不可省略且此命令必须在 git commit 命令之前否则推送上去的仍然是旧文件）。

1

git commit -m "save local changes before update"

• 该命令用于将暂存区中的更改提交到本地的仓库，并添加消息，引号中消息根据内容自定义。

1
2

git push origin main
git push source main

• 该命令用于将本地仓库推送到 Github 仓库的 main 分支。
• （ git push 为推送命令， -u 参数为设置默认推送分支， origin 和 source 是远程仓库的名称， main 是分支名）

• 等待几分钟，访问 https://yourusername.github.io 即可看到部署成功的网站。

扩展

1

git remote -v

• 验证远程库配置是否正确

1

git branch -a

• 显示所有本地和远程分支（*代表当前分支–红字代表远程分支）

1

git log

• 查看提交历史(可以通过此处获取 hash 值，用于回退版本—慎用)

1

hugo server -D

• 启动本地服务器，实时预览网站内容（-D 参数表示将生成的 HTML 文件放入 public 目录下，方便部署(写博客)。）

1
2
3
4
5
6

@echo off
git add .
git commit -m "update Blog"
git push source main
echo Blog Finished！
pause

• 一键部署脚本（将以上命令写入脚本（.bat）文件，双击运行即可—适用于 windows 系统）

1
2
3
4
5
6
7

@echo off
set /p postname="输入文章名称（不需要加.md）: "

hugo new "post/%postname%/index.md"

echo 成功创建：content\post\%postname%\index.md
pause

• 一键创建文章脚本（将以上命令写入脚本（.bat）文件，双击运行即可—适用于 windows 系统）

1
2
3

@echo off
hugo server -D
pause

• 一键启动本地服务器脚本（将以上命令写入脚本（.bat）文件，双击运行即可—适用于 windows 系统）

报错处理

• 此报错发生于 git push 时（并非网络问题）

• 解决方法：

  • 重设当前分支为 main(git branch -m 旧分支名 main)
  • 检查 git push source main 中 main 拼写是否正确

• 此报错发生于 git push 时（网络问题）

• 解决方法：更换未污染的 DNS 或添加代理

参考链接

• 莱特雷-letere 个人博客

• Jules in Spring 个人博客

• Git 切换到指定远程分支

• Git 常见错误简单解决方法