如何使用Hugo创建并部署个人博客

介绍

Hugo是一个用Go语言编写的静态网站生成器，以其快速、灵活和易用性而闻名。本文将介绍如何使用Hugo创建个人博客并将其部署到GitHub Pages上。

准备工作

安装Hugo

1
2
3
4
5
# Ubuntu/Debian
sudo apt-get install hugo

# macOS
brew install hugo

安装Git

1
2
# Ubuntu/Debian
sudo apt-get install git

创建新的Hugo站点

创建新站点

1
2
hugo new site my-blog
cd my-blog

添加主题（以Stack主题为例）

1
2
git init
git submodule add https://github.com/CaiJimmy/hugo-theme-stack.git themes/hugo-theme-stack

配置站点创建或编辑hugo.yaml文件，添加基本配置：

1
2
3
4
baseURL: 'https://yourusername.github.io/'
languageCode: 'zh-cn'
title: '我的博客'
theme: 'hugo-theme-stack'

创建新文章

使用以下命令创建新文章：

1
hugo new post/my-first-post/index.md

设置博客封面图片

Hugo支持为每篇文章设置封面图片，有以下几种方式：

在文章前言（Front Matter）中设置

1
2
3
4
5
---
title: "文章标题"
date: 2025-06-01
image: cover.jpg  # 图片放在文章同级目录下
---

使用外部图片链接

1
2
3
4
5
---
title: "文章标题"
date: 2025-06-01
image: "https://example.com/image.jpg"  # 使用完整的URL
---

图片存放规则：

将图片放在文章目录下（推荐）：

1
2
3
4
5
content/
└── post/
    └── my-first-post/
        ├── index.md
        └── cover.jpg

或放在全局静态目录：
1 2 3
static/ └── images/ └── cover.jpg
然后在文章中引用：image: "/images/cover.jpg"

图片最佳实践：
- 建议使用 JPEG 或 WebP 格式
- 推荐尺寸：1200x630 像素（16:9）
- 控制图片大小在 500KB 以内
- 使用有意义的文件名，避免特殊字符

本地预览

运行Hugo服务器进行本地预览：

1
hugo server -D

访问 http://localhost:1313 查看效果。

部署到GitHub Pages

在部署之前，需要明确理解Hugo博客的两个重要概念：

源码目录：包含所有的文章源文件、配置文件和主题
构建目录（public/）：包含Hugo生成的静态网站文件

为了正确管理博客，我们需要创建两个独立的GitHub仓库：

博客源码仓库（比如：blog-source）
- 用途：存储和版本控制博客的源代码
- 内容：所有的markdown文件、配置文件、主题等
- 特点：需要在 .gitignore 中忽略 public/ 目录，因为它是构建产物
静态网站仓库（必须命名为：username.github.io）
- 用途：通过GitHub Pages提供网站访问
- 内容：只包含 public/ 目录中的构建产物
- 特点：这个仓库就是您的网站的实际托管位置

部署步骤

1. 设置源码仓库

首先，在博客根目录（blog/）下执行：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# 1. 创建 .gitignore 文件，忽略构建产物
echo "public/" > .gitignore

# 2. 初始化源码仓库
git init
git add .
git commit -m "Initial commit: Blog source code"
git branch -M main
git remote add origin https://github.com/username/blog-source.git
git push -u origin main

2. 设置静态网站仓库

然后，处理构建后的静态文件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# 1. 生成静态网站文件
hugo --minify

# 2. 进入构建目录
cd public

# 3. 初始化静态网站仓库
git init
git add .
git commit -m "Initial commit: Static website files"
git branch -M main
git remote add origin https://github.com/username/username.github.io.git
git push -u origin main

更新博客流程

每次更新博客内容时：

在源码仓库中修改内容（比如写新文章）：

1
2
3
4
# 在blog目录下
git add .
git commit -m "Add new blog post"
git push

更新静态网站：

1
2
3
4
5
6
7
# 在blog目录下
hugo --minify                    # 重新生成静态文件
cd public                        # 进入构建目录
git add .                       # 添加新生成的文件
git commit -m "Update website"   # 提交更改
git push                        # 推送到GitHub Pages
cd ..                          # 返回博客根目录

这种双仓库的设置确保了：

源代码得到完整的版本控制
构建产物独立管理
GitHub Pages能正确托管网站

提示：如果这个手动部署过程太繁琐，可以使用GitHub Actions自动化它。

自动化部署

可以使用GitHub Actions实现自动部署。这种方式的优势是：

无需手动构建和部署
每次推送代码后自动更新网站
确保部署过程的一致性
可以在任何设备上更新博客

在仓库根目录创建.github/workflows/deploy.yml文件，这个配置文件的主要功能是：

触发条件：

1
2
3
4
5
on:
  push:
    branches:
      - main  # 当推送到main分支时触发
  workflow_dispatch:  # 支持手动触发部署

权限设置：

1
2
3
4
permissions:
  contents: read    # 仓库内容的读取权限
  pages: write     # GitHub Pages的写入权限
  id-token: write  # 身份令牌的写入权限

构建任务（build job）：
- 检出代码：使用 actions/checkout@v3 获取仓库代码
- 设置Hugo环境：安装最新版本的Hugo
- 构建网站：运行 hugo --minify 生成优化后的静态文件
- 上传构建结果：将 public 目录打包作为部署制品
部署任务（deploy job）：
- 等待构建任务完成
- 将构建好的文件部署到GitHub Pages
- 输出部署后的网站URL

完整的配置文件如下：

 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
35
36
37
38
39
40
41
42
43
44
45
46
47
48
name: Deploy Hugo site to Pages

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

defaults:
  run:
    shell: bash

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
      - name: Build with Hugo
        run: hugo --minify
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: ./public

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

要启用自动部署，还需要进行以下设置：

在GitHub仓库设置中启用Pages功能：
- 进入仓库的 Settings > Pages
- 在 Build and deployment 部分
- Source 选择 “GitHub Actions”
确保仓库的 Actions 权限已开启：
- 进入仓库的 Settings > Actions > General
- 确保 Actions permissions 允许工作流运行

设置完成后，每次你推送更改到main分支，GitHub Actions就会自动：

拉取最新代码
安装Hugo环境
构建你的网站
部署到GitHub Pages

你可以在仓库的Actions标签页查看部署状态和日志。

维护博客

定期更新内容

1
hugo new post/new-article/index.md

本地预览

1
hugo server -D

部署更新

1
2
3
4
hugo --minify
git add .
git commit -m "Update content"
git push

结论

现在你已经掌握了使用Hugo创建博客并部署到GitHub Pages的基本流程。通过这个方法，你可以免费托管你的个人博客，并且可以方便地进行更新和维护。

常见问题解答

配置评论系统

Stack主题支持多种评论系统，包括：

Disqus（默认配置）
DisqusJS
Utterances（GitHub Issues驱动）
Giscus（GitHub Discussions驱动）
Twikoo
Waline
等其他系统

配置Disqus（最简单）

在 Disqus官网注册账号
创建一个站点，获取shortname
修改 hugo.yaml 中的配置：

1
2
3
4
5
6
7
8
services:
    disqus:
        shortname: "你的shortname"  # 替换为你的Disqus shortname

params:
    comments:
        enabled: true
        provider: disqus    # 使用disqus作为评论系统

配置Utterances（基于GitHub）

安装 Utterances GitHub App
修改 hugo.yaml 配置：

1
2
3
4
5
6
7
8
params:
    comments:
        enabled: true
        provider: utterances
        utterances:
            repo: owner/repo-name      # 替换为你的GitHub仓库
            issueTerm: pathname        # 文章和issue的映射方式
            label: comment             # issue的标签

配置Giscus（新一代GitHub评论）

安装 Giscus GitHub App
在仓库设置中启用Discussions功能
访问 Giscus.app 生成配置
修改 hugo.yaml 配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
params:
    comments:
        enabled: true
        provider: giscus
        giscus:
            repo: owner/repo-name      # 你的GitHub仓库
            repoID: "R_xxx"           # 仓库ID
            category: "Announcements"  # discussion分类
            categoryID: "DIC_xxx"      # 分类ID
            mapping: "pathname"        # 映射方式
            reactionsEnabled: 1        # 允许反应
            emitMetadata: 0           # 元数据

最佳实践

对于个人博客：
- 如果想要最简单的设置：选择Disqus
- 如果想要与GitHub集成：选择Giscus
- 如果注重隐私：选择self-hosted的Waline
评论系统管理：
- 定期审核评论
- 设置合适的垃圾评论过滤
- 保持与读者的互动
性能考虑：
- 评论系统通常会增加页面加载时间
- 考虑使用懒加载方式加载评论系统
- 可以设置评论区在用户滚动到底部时才加载