零基础构建个人博客：Hugo搭建和Github部署

前言

个人建站的热潮还是在零几年，那时候互联网就像一片无限大的荒原，也有一批站长在那个时间发家致富。可以确定的是，现在已经不是当时那个遍地都是机会的时代，但互联网依然是那片几乎无限大的土地，大到任何人都可以在中间几乎零成本的圈出自己的一块地。本文会教你如何划出自己的一块地皮。

准备

如你所见这个页面就是基于Hugo（雨果）部署在Github Pages的一个静态站点，之后的内容也基于这一点。

为此你需要准备：

一点点英语和计算机基础。后续的操作大多是英语界面，也需要使用命令行操作，完全不会也不是不行，靠网页翻译和说明硬啃吧，难度肯定会更大。
windows10或者windows11操作系统。
linux本身命令行操作会更简单一些，并且可以默认linux用户基础更好，资料更全，考虑到中文用户大多应该是windows系统，故以windows为主
可以访问Github的网络环境。Github是全球最大的开源社区，这里使用Github提供的Pages功能，该功能支持为项目部署静态网站（免费，但有一定使用限制），由于Github在国内存在DNS污染，因此访问Github对网络提供商，地点等等有一定要求，可以访问github.com测试，如果无法访问需要自行查找解决方案。
可以访问时自行使用邮箱注册账户。

步骤

打开系统的Microsoft Store，即微软商店，在windows10和windows11内置，如果被卸载，可参考我的脚本列表中恢复命令。
安装/更新 App Installer，该软件是微软官方的包管理器，安装该软件后可以用命令行安装软件，省去大量操作步骤。
以管理员模式运行powershell，使用win（徽标键，标准键盘空格左边第二个）+R打开运行，输入powershell，之后按ctrl+shift+enter（同时按住ctrl和shift同时点一下回车），如果弹出授权，同意即可，当能看到一个蓝色窗口时，欢迎来到命令行的世界。
命令行的操作是输入指令按回车执行，后续一切该操作不做说明。运行
```
    winget
```
如果能看到一串列表，那么说明包管理器正常。
换源，winget的内置源或许并不适合国内网络环境的访问，这里使用的是中科大的源，有其他的源可以把ustc更换为任意名称，链接更换为源地址。
```
    winget source add ustc https://mirrors.ustc.edu.cn/winget-source
```
想要检查有什么源可以使用：
```
    winget source list
```
想要移除源可以使用（将星号以及星号之间的内容更换为源列表的名称）：
```
    winget source remove *winget*
```
想恢复默认源可以：
```
    winget source reset --force
```
安装hugo，可以使用以下指令检查是否可以从源搜索到软件：
```
    winget search hugo
```
如果无法搜索到软件需要再检查是否成功配置源以及网络连接。之后安装Hugo。如果顺利搜索，可以看到这里有Hugo的三个不同版本，分别是标准版，扩展版和开发版，开发版并不适合一般用户使用，部分主题需要使用扩展版，因此一步到位直接安装扩展版Hugo。
```
    winget install Hugo.Hugo.Extended
```
同时再顺便安装一个git，等下要用。
```
    winget install git.git
```
关闭powershell，开启一个新的无管理员权限的powershell，这里务必使用无管理员权限的powershell运行，因为两者默认路径是不同的，第5步中由于换源，路径在系统目录下，现在需要在用户目录下进行下一步，因此直接新建无管理员权限的powershell最直接。使用指令：
```
    hugo
```
如果看到如下输出表示软件安装无误:
```
    Total in 1 ms
    Error: Unable to locate config file or config directory. Perhaps you need to create a new site.
    Run `hugo help new` for details.
```
确认建站位置，你的个人网站是需要一个文件夹用来存放的，在上一步中刚开启的powershell默认执行路径是用户文件夹，，即“C:\Users\My\用户名”，也是打开文件管理器看到左侧一串桌面等文件夹的上一级，对于没有学过命令行操作的用户来说，可以使用这样几个指令在命令行中操作文件夹。

进入目录:
```
    cd 目录名
```
回到上一级目录，这里的两个点表示上一级，注意是英文模式下的句号：
```
    cd ..
```
创建新目录：
```
    mkdir 目录名
```
比如如果想要在用户目录下新建一个站点目录，并且在里面创建站点FirstSite应该怎么办呢？
```
    mkdir site
    cd site
    hugo new site FirstSite
    cd FirstSite
```
完成这一步，就会有一个site\FirstSite目录作为站点的根目录，同时进入这个目录下，之后的所有操作都要在这里进行，也就是每次操作网站都需要先打开一个无管理员权限的powershell，然后使用cd指令进入根目录处理。
创建完网站后是没有默认主题的，可以在 https://themes.gohugo.io/ 处寻找喜欢的主题，想要使用这些主题，需要先在网站根目录创建一个git仓库，使用如下指令：
```
    git init
```
然后在喜欢的主题下面找到下载，进入得到对应的项目地址，使用如下指令将主题作为子模块克隆到本地网站根目录，这里实例使用了hugo官方的实例，可以根据个人选择修改网址，需要注意的是，不同的主题可能支持不同的特性，可能需要根据需求查看原文档获取详细的使用方法，本站所使用的主题为Book，后面我会单独发一篇文章分享该主题的详细设置：
```
    git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
```
克隆完主题后需要设置网站使用的主题，Hugo官方给出的是使用指令：
```
    echo "theme = 'ananke'" >> hugo.toml
```
这里我个人不推荐使用该方法，因为powershell和本地编码的问题，有时候或许会插入一些错误字符，个人建议直接打开网站根目录下的hugo.toml直接进行配置。在该文件中配置title后面单引号字符串为网站标题，baseURL为网站根域名，如果这里没有的话暂时不做处理，在title下面新开一行theme，后面的字符串为网站根目录下themes中的主题文件夹的文件夹名，如果配置好了应该是这样的：
```
baseURL = 'https://meirgoo.net/'
languageCode = 'zh-cn'
title = 'Meirgoo Site'
theme = 'hugo-book'
[caches]
[caches.images]
    dir = ':cacheDir/images'
```
完成这些步骤后使用如下命令就可以在本地看到自己的网站了:
```
    hugo server
```
此时网站会自动编译并且部署到本地服务器，如果看到输出的结尾是：
```
    Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
    Press Ctrl+C to stop
```
那就说明编译部署成功，此时可以在浏览器访问链接中的地址看到自己的网站了，如果想要退出，可以在powershell中使用ctrl+C组合键，或者直接关闭powershell都是可以的。
在上一步中已经成功使用hugo完成了静态站点的建立，并且成功渲染，但是只能在本地访问，现在想要把网站部署到网络上允许公开访问，可能有部分人认为部署网站需要服务器、域名，如果在国内还有备案要求等等，但事实上这些绝大部分并不是必须的，如果想要一个动态的网站，那么一台服务器基本是必不可少的，如果是纯粹的静态网站，目前已经有了许多种免费方案，虽然在带宽流量方面略有限制，但是对访问量不高的个人小站点来说绝对是绰绰有余，我个人用过的方案有vercel和github page，本文选择使用github page方式实现。
在之前的步骤中已经使用了git安装主题，因此到了这一步默认已经安装好git，如果没有，返回到第六步安装git。

什么是git，简单来说就是一个项目仓库方面的网站，也有其他的一些服务，更多的内容不多赘述，现在我们要做的就是把本地的网站项目链接到这个网站上的一个仓库中，并且使用仓库的自动流功能自动部署，这样每次完成网站的更新后就可以将更改推送到远程仓库并由仓库自动完成部署。

首选需要对git进行配置，运行以下指令：
```
     git config --global user.email "邮箱"
     git config --global user.name 用户名
```
然后运行以下指令：
```
    ssh-keygen -t rsa -C "xxxxxx@outlook.com"
```
双引号内的内容更换为自己的邮箱，保留双引号。此时系统中会生成一个用于验证身份的密钥，后续会询问密钥存储位置和加密指令，如果不需要的话可以按几下回车跳过。

注意！密钥的公钥和私钥是验证身份用的，如果珍惜账号，以及仓库内的内容，请勿随意泄露，丢失可以重新生成，泄露了需要在账号后台中及时取消密钥可用性，确保账号安全。

现在登陆github网站，点击右上角头像，选择Settings，在左侧的"SSH and GPG keys"中点击"New SSH key"，在"Title"中为密钥填写一个名称，然后将默认位置为"C:\Users\用户名\.ssh\id_rsa.pub"中的内容以记事本打开，并将内容粘贴到"Key"中，保存。

如果想作废某个身份凭证来这里删除key就可以。
现在点击左上角的猫头，左侧仓库选择"New"，新建两个仓库。
1. 第一个仓库名称一定是"用户名.github.io"，公开(Public)表示，只有这样命名才表示这是用户的一个个人网站，只有公开仓库对外展示的内容会放在这里，建议选择不添加README.md，建立完成后来到项目的设置页面，在Pages选项卡中将Branch下的None更改为main。
2. 第二个仓库可以随意命名，建议私有(Private)表示，这里是施工现场，如果公开表示可能会有不想公开的内容泄露，因此一般私有，如果没有有价值内容，用户认为公开无所谓，那也行，同样建议选择不添加README.md。
3. 同样点击右上角来到个人设置，拖到页面最低端，点击左侧"Developer settings"，在下面的"Personal access tokens"下选择"Fine-grained tokens"点击右上角"Generate new token"生成新令牌，注意该令牌需要绝对保密。
  在之后的令牌名输入一个好记的令牌名，我用的是"Github page action token"，默认三十天旗下可以更改为无限期(No expiration)，可访问仓库(Repository access)更改为第三个仅选择的仓库(Only select repositories)，之后选择公开的仓库，也就是"用户名.github.io"的仓库，并在下面的仓库权限(Repositories permissions)将目录(Contents)更改为允许读写(Read and Write)。
  设置完成后生成仓库并且复制得到的key，关闭页面后是看不到这个key的，回到项目仓库的设置，在秘密和变量(Secrets and variables)的action中新建一个仓库秘密(New repository secret)，填写一个好记的名称并且在下面粘贴刚刚生成的公有仓库的key，此时该私有项目仓库就有了读写公有网站仓库的权限，之后网站的更新可以完全在私有的环境下部署到公开站点。
4. 在本地文件系统的项目中新建 .github 文件夹，在其中新建一个 hugo.yaml 的文本文件，复制以下内容进去：
```
name: GitHub Pages

on:
push:
    branches:
    - main  # Set a branch to deploy
pull_request:

jobs:
deploy:
    runs-on: ubuntu-22.04
    concurrency:
    group: ${{ github.workflow }}-${{ github.ref }}
    steps:
    - uses: actions/checkout@v4
        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@v3
        with:
        hugo-version: 'latest'
        extended: true

    - name: Build
        run: hugo --minify

    - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/main'
        with:
        personal_token: ${{ secrets.Deploy }}
        external_repository: Meirgoo/Meirgoo.github.io
        keep_files: false
        publish_branch: main
        publish_dir: ./public
        cname: 
```
在这里需要修改部分内容，将personnal_token后面的secrets.Deploy的"Deploy"部分更改为刚刚你设置好的仓库访问令牌名称，目标仓库(external_repository)后面的内容更改为用户名/用户名.gtihub.io 最后的cname需要填写自己的域名，如果没有自己的域名可以写用户名.github.io 。
现在来到施工现场的仓库，可以看到一些指令提示，不用管，说明目前仓库中没有内容，回到powershell中，确定路径是网站根项目文件夹，依次运行施工现场底部三条指令，为项目添加一个远程源，然后运行指令：
```
    git add .
    git commit -m "init"
    git push
```
这些指令的意思是，将所有文件添加到更改，提交并且备注"init"，注意提交后不等于提交到远程仓库，push才是推送到远程仓库。

如果顺利的话，就可以在建立的私有项目中看到文件，等待几分钟后可以在公有项目中看到生成好的文件，此时可以尝试通过用户名.github.io 进行访问。
现在已经完成了网站的建立，那么怎么完成内容更新呢？同样采用类似的方式，只是比起完整建站简单的多。

回到网站根项目中，可以看到一个"content"文件夹，这个文件夹就是网站内容的存放位置，当然会根据网站主题的不同，目录组织方式有所不同，有些主题对文件结构有所要求，具体情况需要具体分析，hugo的内容主要是以Markdown语言构成的，想要添加一个新的md文件，需要在网站根目录下运行如下指令：
```
    hugo new ./content/文件名.md
```
然后可以打开这个文件进行编辑，这里推荐使用vscode方式，可以使用以下指令安装vscode：
```
    winget install Microsoft.VisualStudioCode
```
打开文件编辑后，想要上传到网站，则需要类似于远程仓库初始化将本地项目上传到github，同样在网站根目录下运行指令：
```
    git add .
    git commit -m "update"
    git push
```
之后的内容就由Action自动渲染发布。

结语

这篇内容是我个人建立站点的全步骤，它当然不全，还有些是我比较个人化的内容或者没有完全理解的内容，例如DNS配置，域名购买，页面的进一步扩展，这些内容都需要我继续深入后才能写，目前还是比较粗糙的，我会随着其余内容的添加慢慢修改这篇内容。

零基础构建个人博客：Hugo搭建和Github部署#

前言#

准备#

步骤#

结语#

零基础构建个人博客：Hugo搭建和Github部署

前言

准备

步骤

结语