Featured image of post Hugo + GitHub博客搭建记录
Hugo

Hugo + GitHub博客搭建记录

记录使用 Hugo + GitHub Pages 搭建个人博客的全过程，涵盖主题配置、部署与自动化

环境准备

  • 下载hugo

  • 将 Hugo 解压路径添加至系统 PATH

搭建博客

创建站点

hugo目录下打开命令行，输入hugo new site blog，新建一个存放网站文件的文件夹，成功后出现提示

屏幕截图

主题配置

  • 可以在Hugo Themes找到喜欢的主题，我用的是stack，下载后解压到blog\themes目录里
  • 在主题文件夹中找到exampleSite文件夹，复制其中content和hugo.yaml到blog文件夹下，并删除原本的配置文件hugo.toml
  • 修改themes文件夹下主题文件名，删除文件名中的版本号，使其和hugo.yaml中的主题名一样
  • 删除content>post>rich-content文件夹，因为文件内容引用了youtube视频，不删掉可能网络访问失败启动不了
  • 此时网站框架完成，输入hugo server --buildDrafts命令启动服务，打开输出的地址，如http://localhost:1313/，就可以看到网站的框架了

屏幕截图

主要文件夹

文件夹 功能描述
assets 放置图标、JS 脚本、CSS 样式等资源
content 存放文章与页面，如博客、分类、归档等
layouts 页面结构与布局模板
public Hugo 编译输出目录，不建议手动修改
static 静态文件，如图片等，会直接映射到根路径
themes 主题文件夹

content文件夹中：

  • categories是分类页面目录
  • page是归档、友链、关于等页面的目录
  • post是存放博客文件的目录

新建文章

  • blog\content\post文件夹用来存放文章

  • 命令行输入hugo new content post/myfirstblog/index.md

  • md文件名的后缀是语言编码，如index.en.md在英文环境，index.zh-cn在中文环境，默认使用 index.md 即可

注：文章中图片引用绝对路径会报错，因此在static文件夹下新建一个images文件夹，把文章中用到的图片放进去，改名使图片名中不含空格，引用时![图片名](/images/图片名)或<img src="/images/图片名" style="width: 缩放百分比%;" />

基本参数设置

注：改动参数时要在:后面加一个空格，否则会报错

外观设置

修改hugo.yaml文件，主要参数如下：

1
2
3
4
5

baseurl: https://example.com/ #网站地址
languageCode: zh-cn #网站使用的语言代码
theme: hugo-theme-stack	 #主题
title: Thaumazein's blog #网页标题
copyright: Thaumazein #自己的名字

  • DefaultContentLanguage: 默认语言

  • hasCJKLanguage: 设置为true

1
2
3
4
5
6
7
8
9

#里面的模块可以删掉不需要的语言
languages:
      zh-cn: #留下中文就可以
          languageName: 中文
          title: Thaumazein #改成自己的名字
          weight: 2
          params:
              sidebar:
                  subtitle: 404 Not Found #简介
  • pagination: pagerSize: 5:每页文章数
 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

params:
  mainSections:
    - post
  featuredImageField: image
  rssFullContent: true
  favicon: /favicon.ico
#网站小图标，将图片转换成`favicon.ico`，放在`static`目录下，然后将这个值设置为`/favicon.ico`

  footer:
    since: 2025 #创建时的年份
    customText: "May you find your worth in the waking world." #网站底下的小字

  dateFormat:
    published: "2006-01-02" #格式改成年份-月份-日期，如2006-01-02
    lastUpdated: "Jan 02, 2006 15:04 MST"

  sidebar:
    emoji: 😋 #头像旁边的表情
    subtitle: 
    avatar:
      enabled: true
      local: true
      src: img/avatar.png
#头像，将150*150，png格式图片放在\hugo\blog\assets\img目录下，改名avatar.png

  article:
    math: true #数学公式
    toc: true
    readingTime: false
    license:
      enabled: true
      default: "Licensed under CC BY-NC-SA 4.0"

注：头像和简介改完如果没有变化，输入hugo --gc清理一下缓存再重新启动服务

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

widgets: #页面右侧功能
        homepage:
            - type: search #搜索
            - type: archives #归档
              params:
                  limit: 5
            - type: categories #类别
              params:
                  limit: 10
            - type: tag-cloud #标签云
              params:
                  limit: 10
        page:
            - type: toc
  • 主页Archives,Search,Links显示英文解决方法:hugo\blog\content\page文件夹中对应名称的文件夹，打开其中的index.md,修改成中文标题

社交账号

  • 可以自己增加平台账号，图标从Tabler Icons下载svg格式
  • 在\hugo\blog\assets目录下创建icons文件夹，放入图标，然后修改hugo.yaml文件这一部分
1
2
3
4
5
6

    social:	
        - identifier: github #改成平台名
          name: GitHub #同上
          url: https://github.com/Th4uma #改成对应平台url
          params:
              icon: brand-github #图标文件名

到这里本地的设置和调试基本完成了，网站现在是这样：屏幕截图

部署到GitHub

手动部署

  • github新建一个公有仓库，命名建议github用户名.github.io
  • 修改hugo.yaml文件baseurl参数为https://用户名.github.io/
  • 我们需要把public文件夹下的文件上传，因此在此文件夹下打开命令行，然后依次输入下列命令
1
2
3
4
5
6

git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/Th4uma/Th4uma.github.io.git
git push -u origin main
  • 仓库界面进入settings>pages>branch选择main，保存，刷新后出现自己网站的url，部署成功

GitHub Action实现自动化部署

  • github新建一个仓库用来存放hugo主文件，建议设置成私有
  • 由于自动生成的文件比如public不需要上传，因此在\hugo\blog文件夹新建一个.gitignore文件来忽略上传，文件中写入
1
2
3

public
resources
.hugo_build.lock
  • 打开命令行，然后依次输入下列命令
1
2
3
4
5
6

git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/Th4uma/hugo_main.git
git push -u origin main

  • 在Personal Access Tokens (Classic)新建一个token，设置如下

  • 进入存放hugo主文件的仓库，选择Settings> Secrets and variables> Actions>Repository secrets新增环境变量，填入token

  • 在\hugo\blog文件夹下新建.github\workflows\xxxx.yaml文件,复制下面的代码到文件，并把参数改成自己的

 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.你的token变量名 }}
              EXTERNAL_REPOSITORY: 你的github名/你的仓库名
              PUBLISH_BRANCH: main
              PUBLISH_DIR: ./public
              commit_message: auto deploy
  • 把文件push上去
1
2
3

git add .
git commit -m "update"
git push
  • 仓库中显示运行成功，部署完成

新增功能（持续更新）

见Hugo 博客功能拓展

参考

Like 0
© 2025 Thaumazein
May you find your worth in the waking world.
使用 Hugo 构建
主题 Stack 由 Jimmy 设计