Featured image of post Hugo搭建博客
Hugo

Hugo搭建博客

手把手教你用Hugo搭建个人博客，结合Github Pages部署，零基础也能上手

前言

本教程将介绍如何使用 Hugo 和 GitHub Pages 搭建一个静态博客。Hugo 是一款功能强大的静态站点生成器，可以帮助您轻松创建美观、响应式的博客页面。GitHub Pages 则是 GitHub 提供的免费托管服务，可用于托管您的 Hugo 博客。

环境搭建

首先s下载所需的工具：

[Hugo](The world’s fastest framework for building websites)

[Git](Git - 安装 - Git 版本控制系统)

[Go](Download and install - The Go Programming Language)

将Hugo和Git的指令添加环境变量

创建博客

创建Hugo新站点

使用 Hugo 创建新站点非常简单，在想要创建的目录下，命令行中输入以下命令：

1

hugo new site blog

其中blog 是博客名称，可以根据需要修改。

执行该命令后，会自动生成 Hugo 博客的标准目录结构，生成的目录如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

blog/
├── archetypes/       # 内容模板（新建文章时的默认格式）
├── assets/           # 未编译的静态资源（如 SCSS、JS）
├── hugo.toml         # 核心配置文件（Toml 格式，也可改用 Yaml/Json）
├── content/          # 博客文章内容（核心目录，放 Markdown 文章）
├── data/             # 自定义数据文件（如 JSON/Yaml，可在模板中调用）
├── layouts/          # 自定义模板（覆盖主题模板）
├── public/           # 编译后生成的静态网站文件（部署用）
├── static/           # 静态资源（如图片、CSS、JS，会直接复制到 public）
└── themes/           # 主题文件夹（存放下载的 Hugo 主题）

这将创建必要的配置文件和文件夹，并提示接下来如何创建一个博客。

image-20260131091447380

进入新创建的站点目录，并运行以下命令进行初始化：

1

cd blog

选择主题（Hugo module)

浏览和选择主题

Hugo 提供了丰富的主题模板，您可以根据自己的喜好选择合适的主题。

官方主题仓库 第三方主题仓库

下载及应用主题(官方推荐，Hugo module)

用这种方法，目录下不会有文件。要修改主题，你需要把想修改的文件复制到目录下的同一个目录。themes``layouts

不是很推荐，想要自己配置的可以使用，如果想要快速使用的话，查看3.Git配置

这里演示stack主题，通过[官方文档下载](Getting Started | Stack)

最低要求的 Hugo 版本可以在主题的 theme.toml 文件中看到

1

git init

首先，把你的网站变成Hugo模块（如果你还没做过）：

1

hugo mod init github.com/me/my-new-blog

github.com/你的用户名/你的博客名，随便填也可以

执行成功后，项目根目录会生成一个 go.mod 文件，这是 Hugo Module 的核心配置文件，不用手动修改。

在项目根目录的 hugo.toml 文件中，添加

1
2

[[module.imports]]
path = "github.com/CaiJimmy/hugo-theme-stack/v3"

这使得 Hugo 使用了主题的最新稳定版本（发布页面可获得，可能不会与分支中最新的提交时间重合）

要将主题更新到最新版本，请执行以下命令：

1
2

hugo mod get -u github.com/CaiJimmy/hugo-theme-stack/v3
hugo mod tidy

由于版本问题，在项目根目录执行命令，指定降级到稳定兼容版（v3.28.0 经测试适配 Hugo 0.15x 系列）：

1
2

hugo mod get github.com/CaiJimmy/hugo-theme-stack/v3@v3.28.0
hugo mod tidy

预览主题 

1

hugo server -D

image-20260131104232402

成功是上面那样，这将在您的浏览器中打开一个本地服务器，您可以访问 http://localhost:1313 来查看您的博客页面。

效果如下：

image-20260131104441721

这样的话一切内容就需要自己配置，非常麻烦。

选择主题（Git配置）

下载合适的安装包 

1
2
3

git clone https://github.com/CaiJimmy/hugo-theme-stack/ themes/hugo-theme-stack
cd themes/hugo-theme-stack
git checkout tags/v3.28.0

这种方法，就是将主题放到了themes中

应用主题

进入到\themes\hugo-theme-stack\exampleSite中，这里面是官方给的stack案例

将其中的content文件和hugo.yaml文件一起复制到博客的根目录

由于hugo.toml和hugo.yaml性质一样，删除原先的hugo.toml

就可以快速配置好一个默认的页面

1

hugo server -D

可以访问 http://localhost:1313 来查看您的博客页面。

image-20260131112409477

设置配置文件

Hugo 的配置文件hugo.yaml用于配置站点信息、主题、菜单等。

修改里面的内容，就可以将这个页面换为自己的内容

具体怎么配置可以查看bilibili博主Letere-莱特雷stack主题配置_哔哩哔哩_bilibili

部署到 GitHub Pages

部署准备

首先,前往【Github官网】，创建仓库 {github用户名}.github.io这将是你博客的主域名。 在将您的 Hugo 博客部署到 GitHub Pages 之前，请确保您已经：

  • 创建了一个 GitHub 账户。
  • 创建一个新的 GitHub 仓库。

常规部署

首先，修改我们的hugo.yaml中baseurl中的地址，修改为我们创建的仓库的地址，格式如下

1

baseurl: https://你的仓库/

然后把public 静态资源文件夹删除

重新生成静态站点，会自动生成新的public 静态资源文件夹

1

hugo -D

现在,我们进入public ，就可以将Hugo生成的静态网站文件推送到GitHub仓库:

1
2
3
4
5
6
7

cd public
git init
git remote add origin git@github.com:your-github-username/your-github-project-name.git
git add .
git branch -M main
git commit -m "First commit"
git push origin main

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

image-20260131121547206

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

自动部署

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

image-20260131122332449

  • （3）token选择永不过期，并勾选 repo 和 workflow 选项，记得复制一下

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

image-20260131123417464

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

 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
  • （6）在hugo主文件创建.gitignore文件，来避免提交不必要的文件
1
2
3
4
5
6
7

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

# hugo命令
hugo.exe
  • （7）将hugo的主文件上传到仓库，上传成功后会触发Github Action，来自动部署你的静态页面
1
2
3
4
5
6

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

stack进阶

浏览器搜索Stack主题美化,查看大佬的配置

Hugo + Stack 主题美化指南 🎨

【博客装修日记】Hugo➕ Stack ➕ Giscus魔改美化 细节满满

搭建图床

图床概述

图床就是一个专门用来存放图片并提供在线访问链接的服务或工具，你可以把它理解成 “图片的网盘”。

简单来说，当你在写文章或发帖子时，直接插入本地图片只能在自己的设备上看到。但用图床上传后，它会给你一个公开的图片链接，任何人在任何设备上都能通过这个链接看到图片。

对于博客场景来说，图床的选择会更看重稳定性、速度、长期可用性和链接的可靠性，因为你的博客内容会长期在线，图片链接一旦失效会直接影响阅读体验。

推荐 CloudflareR2+ PicGo

简单说就一个核心：免费、稳定、国内访问快，还能一键自动上传，新手零门槛

image-20260131232717900

具体步骤

注册并开通 Cloudflare R2

  • 前往 Cloudflare 注册账号，并绑定支付方式（如信用卡或 PayPal）。

  • 登录后，进入 R2 对象存储，点击开通服务。

    image-20260131233644994
    img

创建存储桶

  • 在 R2 控制台中，创建一个存储桶： 填写存储桶名称。 选择存储区域（建议默认）。 确认后完成创建。

    image-20260131234008513

配置自定义域名

设置访问桶的域名，有两种方法，一种是有一个私有域名（需托管在Cloudflare上），另一个是用默认的

  • 先允许公网访问，启用后，通过公共开发URL将该R2桶的内容暴露到互联网。

image-20260131234158049

image-20260131234410850

这样配置后，就搭建好图床，使用的默认域名。

可以上传图片

image-20260131234736253

上传图片后，点击链接，就可以看图片的详情

可以得到，图片的公网地址

​

image-20260131235049101

  • 自定义域名，得有自己的域名

    image-20260131235752499

image-20260131235844128

就实现了，自己的域名访问

image-20260201000152873

配置 PicGo

  1. 下载并安装 PicGo。

  2. 在 PicGo 中安装 Amazon S3 插件：

    • 打开插件设置，选择 S3 -IIS 1.0.2。
      image-20260201000353064
    • 点击图床设置，找到Amazon S3 ，填写相应的信息
      image-20260201000538812

    image-20260201000826777

    • 应用密钥ID、应用密钥

      image-20260201001101219

      image-20260201001129196

      image-20260201001234207

      image-20260201001300852

    • 自定义节点、域名

      image-20260201001503882

      image-20260201001613468

      自定义节点,账号ID就是上图的ID

      1

      https://<账户ID>.r2.cloudflarestorage.com

      自定义域名

      1

      https://你的自定义域名

  3. 配置完成后，可直接拖拽图片到 PicGo 上传，生成的链接会自动复制到剪贴板。

最后更新于 2026-03-03 21:02
© 2026 郭小胖