GitHub 部署 hugo 博客

hugo 项目地址：https://github.com/gohugoio/hugo
hugo 主题：https://themes.gohugo.io/
hugo 本地地址：https://localhost:1313
我的 hugo GitHub地址：https://meimolihan.github.io/

一、windows 安装 hugo

1 、安装 scoop

Scoop是一款适用于Windows系统的命令行包管理工具。
在以管理员身份运行的 PowerShell 中，运行以下命令来启用管理员安装：

1
2
3

$env:SCOOP_REPO = 'https://github.com/ScoopInstaller/Scoop'
irm get.scoop.sh -outfile 'install.ps1'
.\install.ps1 -RunAsAdmin

或者克隆仓库

1 2	cd "$env:USERPROFILE\scoop\buckets\main" git pull origin master

查看 scoop 版本

1	scoop --version

2 、安装 hugo

1	scoop install hugo-extended

查看 hugo 版本

1	hugo version

二、创建站点

1 、电脑桌面创建 Hugo 目录

1	mkdir %USERPROFILE%\Desktop\Hugo

2 、进去 Hugo 目录，并创建 myblog 站点

1	cd %USERPROFILE%\Desktop\Hugo && hugo new site myblog

三、安装主题

1 、克隆 stack 主题

1	cd %USERPROFILE%\Desktop\Hugo\myblog\themes && git clone https://github.com/CaiJimmy/hugo-theme-stack stack

克隆成功后，删除 %USERPROFILE%\Desktop\Hugo\myblog\themes\stack\.git 文件
日后 git 推送 hugo 会有影响

2 、拷贝配置文件

拷贝 hugo.toml 文件

1	copy %USERPROFILE%\Desktop\Hugo\myblog\themes\stack\exampleSite\hugo.yaml %USERPROFILE%\Desktop\Hugo\myblog\ && del %USERPROFILE%\Desktop\Hugo\myblog\hugo.toml

拷贝 content 文件夹

1	copy %USERPROFILE%\Desktop\Hugo\myblog\themes\stack\exampleSite\content %USERPROFILE%\Desktop\Hugo\myblog\content && rd /s /q "%USERPROFILE%\Desktop\Hugo\myblog\content\post\rich-content"

3 、开启主题

编辑 hugo.yaml 配置文件

1	theme: stack

四、新建文章

1 、修改文章模板

模板路径：%USERPROFILE%\Desktop\Hugo\myblog\archetypes\default.md

---
title: "{{ replace .Name "-" " " | title }}"
slug: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
description: "" # 文章描述，用于搜索优化
summary: "" # 文章简要描述，展示在主页
math: true # 是否渲染数学公式：true 渲染，false 不渲染
hidden: false # 文章可见性：false 可见，true 隐藏
comments: true # 评论系统：false 关闭，true 显示
draft: false # 文章状态：true 草稿，false 发布
showToc: true # 是否显示目录：true 显示，false 不显示
TocOpen: true # 目录默认展开：true 展开，false 折叠
autonumbering: true # 目录自动编号：true 自动，false 不自动
hidemeta: false # 是否隐藏元信息：true 隐藏，false 显示
disableShare: true # 底部分享栏：true 不显示，false 显示
searchHidden: false # 搜索引擎收录：true 不收录，false 可收录
showbreadcrumbs: true # 当前路径显示：true 显示，false 不显示
# 文章顶置，输入1可以顶置文章
weight: 
# 文章封面，例如：hugo.jpg
image: 
# 文章分类
categories: 
  - 默认分类
# 文章标签
tags:
  - Blog
---

2 、Hugo 新建文章

1	cd %USERPROFILE%\Desktop\Hugo\myblog && hugo new "post\hugo 部署\index.md"

3 、编辑文章

打开文章目录
编辑 Markdown 格式文章

1	%USERPROFILE%\Desktop\Hugo\myblog\content\post

4 、修改文章属性

在C:\hugo\myblog\content\post目录找到新建的文章
修改文章，将草稿draft = true修改为draft = false发布

5 、hugo 命令

生成静态并启动

1	cd %USERPROFILE%\Desktop\Hugo\myblog && hugo server -D

浏览器地址：http://localhost:1313/
- Ctrl+C停止服务（hugo默认是没有主题的，需要进行主题配置）

五、修改 hugo.yaml 配置文件

1 、修改默认语言

修改默认语言为：中文

DefaultContentLanguage: zh-cn # 默认内容语言
hasCJKLanguage: true # 默认为false，修改为true。
languages:
    zh-cn:
        languageName: 中文
        title: 演示站点 # 标题
        weight: 2
        params:
            sidebar:
                subtitle: 演示说明

2、网页标签页上显示的图标

【favicon 图标下载】

params:
    mainSections:
        - post
    featuredImageField: image
    rssFullContent: true
    favicon: /favicon.ico # static/favicon.ico

3、网站创建时间

1
2
3

footer:
    since: 2025 # 网站创建时间
    customText:

4、时间格式

日期格式,必须是符合 Go 语言的日期格式

1
2
3

dateFormat:
    published: 2006-01-02 # 发布日期格式
    lastUpdated: 2006-01-02 # 文章更新时间，或者：2006-01-02 15:04

5、博客头像配置

sidebar:
    emoji: 🍥
    subtitle: # 副标题
    avatar: # 作者头像
        enabled: true # 是否启用头像，false为关闭，true为开启。
        local: true # 是否使用本地头像，false为关闭，true为开启。
        src: img/avatar.png # 头像图片路径

6、文章配置

article:
    math: false # 数学公式渲染，false为关闭，true为开启。
    toc: true # 是否启用目录，false为关闭，true为开启。
    readingTime: true # 是否显示阅读时间，false为关闭，true为开启。
    license:
        enabled: true # 是否启用许可证
        default: Licensed under CC BY-NC-SA 4.0

7、评论系统配置

1
2
3

comments:
    enabled: true # 是否启用评论
    provider: giscus # 评论系统提供商

8、右侧小部件配置

widgets:
    homepage:
        - type: search # 搜索
        - type: archives # 归档
          params:
              limit: 5 # 【归档】显示数量限制
        - type: categories # 分类
          params:
              limit: 10 # 【分类】显示数量限制
        - type: tag-cloud # 标签云
          params:
              limit: 10 # 【标签云】显示数量限制
    page:
        - type: toc # 目录

9、主题默认颜色

1
2
3

colorScheme:
    toggle: true # 是否显示切换按钮
    default: dark # 默认颜色方案，auto自动，light白色，dark黑色。

10、图片处理

imageProcessing:
    cover:
        enabled: false # 封面图片压缩处理，false为关闭，true为开启
    content:
        enabled: false # 内容图片压缩处理，false为关闭，true为开启

11、社交信息

menu:
    main: []
    social:
    
        - identifier: bilibili # 标识符
          name: Bilibili # 显示名称
          url: https://space.bilibili.com/35158479 # 链接地址
          weight: 100 # 项目的优先级，值越低，优先级越高。
          params:
              icon: brand-bilibili # 图标名称
              newTab: true # 新标签页中打开此链接，false为关闭，true为开启
              
        - identifier: github # 标识符
          name: GitHub # 显示名称
          url: https://github.com/meimolihan # 链接地址
          weight: 200 # 项目的优先级，值越低，优先级越高。
          params:
              icon: brand-github # 图标名称
              newTab: true # 新标签页中打开此链接，false为关闭，true为开启

12、TOC 目录

tableOfContents:
    endLevel: 4 # 目录结束级别
    ordered: false # 是否有序，false为关闭，true为开启（开启后TOC目录会显示1.2.3.）
    startLevel: 2 # 目录起始级别

13、代码围栏

highlight:
    noClasses: false # 是否禁用类名
    codeFences: true # 是否启用代码围栏
    guessSyntax: true # 是否自动检测语法
    lineNoStart: 1 # 行号起始值
    lineNos: true # 是否显示行号
    lineNumbersInTable: true # 是否在表格中显示行号
    tabWidth: 4 # 制表符宽度

六、部署在 GitHub

1 、安装 Git

前往【Git官网】，下载安装程序
一直点下一步，默认安装即可

2、Github 常规部署

（2.1）前往【Github官网】，创建仓库 {github用户名}.github.io

（2.2）前往Setting -> Pages -> Branch选择main分支，然后保存，会自动开启 https://{github用户名}.github.io 的地址，这地址也是以后访问博客的地址

（2.3）回到hugo文件中，执行命令hugo -D，会生成 public 静态资源文件夹

（2.4）在 public 执行以下命令上传到github仓库上，第一次上传可能需要输入账号密码

git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin {你的github仓库地址}
git push -u origin main

（2.5）上传成功后访问 https://{github用户名}.github.io，成功搭建属于自己的Hugo博客

3 、 Github Action 自动部署

（3.1）Github创建一个新的仓库，用于存放Hugo的主文件
（3.2）前往Setttings -> Developer Settings -> Personal access tokens，创建一个token(classic)

（3.3）token选择永不过期，并勾选 repo 和 workflow 选项

（3.4）为保证安全，将生成的token，保存的仓库的变量中，前往 Settings -> Secrets and variables -> Actions中设置

（3.5）在hugo主文件创建一个.github/workflows/xxxx.yaml文件，将以下内容复制进去，想具体了解更多，可查看【Github Action文档】

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

（3.6）在hugo主文件创建.gitignore文件，来避免提交不必要的文件

### 自动生成的文件
public
resources
.hugo_build.lock

# hugo命令
hugo.exe

（3.7）将hugo的主文件上传到仓库，上传成功后会触发Github Action，来自动部署你的静态页面

git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin {你的github仓库地址}
git push -u origin main

4 、后期更新项目

1
2
3

git add .
git commit -m "update"
git push

一 、windows 安装 hugo

二 、创建站点

三 、安装主题

四 、新建文章

五 、修改 hugo.yaml 配置文件

六 、部署在 GitHub