通过 GitHub Pages 部署 Hugo 博客完整指南

本文将详细介绍如何使用 Hugo 构建博客并通过 GitHub Pages 进行部署，从零开始搭建属于自己的技术博客。

写在前面

在数字化时代，拥有一个个人博客已经成为技术人员分享知识、记录学习历程的重要方式。Hugo 作为一个快速、现代的静态站点生成器，结合 GitHub Pages 的免费托管服务，为我们提供了一个完美的博客解决方案。

GitHub Pages 部署方案概述

GitHub Pages 支持多种部署方式，对于 Hugo 博客，我们主要有以下几种选择：

方案一：双仓库模式（推荐）

这是最常用的部署方式：

  • 源码仓库：存储 Hugo 项目源码（markdown 文件、配置文件等）
  • 部署仓库：存储生成的静态网站文件（username.github.io）

优势：

  • 源码和生成文件分离，管理清晰
  • 可以保持源码的隐私性
  • 便于版本控制和协作

方案二：单仓库 + GitHub Actions

使用 GitHub Actions 自动化构建和部署：

  • 源码推送到主分支
  • GitHub Actions 自动构建并部署到 gh-pages 分支

优势：

  • 自动化程度高
  • 只需要一个仓库
  • 支持自定义域名

具体部署步骤

1. 准备工作

# 确保已安装 Hugo
hugo version

# 检查你的 Hugo 项目结构
tree -L 2 myblog/

2. 创建 GitHub 仓库

  1. 创建源码仓库：blog-source（或任意名称）
  2. 创建部署仓库：username.github.io

3. 配置 Hugo 项目

在 hugo.toml 中配置正确的 baseURL：

baseURL = 'https://username.github.io'

4. 使用 GitHub Actions 自动部署

创建 .github/workflows/deploy.yml：

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@v4
        with:
          submodules: recursive

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true

      - 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

主题管理最佳实践

Git Submodule 方式

# 添加主题作为子模块
git submodule add https://github.com/theme-author/theme-name.git themes/theme-name

# 初始化和更新子模块
git submodule update --init --recursive

Hugo Modules 方式（推荐）

# 初始化 Hugo 模块
hugo mod init github.com/username/blog-source

# 在 hugo.toml 中配置主题
# [module]
#   [[module.imports]]
#     path = "github.com/theme-author/theme-name"

域名配置

自定义域名设置

  1. 在仓库根目录创建 static/CNAME 文件
  2. 文件内容为你的域名：blog.example.com
  3. 在域名服务商处添加 CNAME 记录指向 username.github.io

DNS 配置示例

Type: CNAME
Name: blog (或 www)
Value: username.github.io

常见问题及解决方案

1. 主题文件丢失

问题：部署后网站样式丢失 解决：确保主题文件正确上传，检查 .gitignore 配置

2. 相对路径问题

问题：本地正常，部署后链接错误 解决：检查 baseURL 配置，使用相对路径

3. 构建失败

问题：GitHub Actions 构建失败 解决：检查 Hugo 版本兼容性，查看构建日志

性能优化建议

图片优化

  • 使用 WebP 格式
  • 压缩图片大小
  • 启用 CDN 加速

代码优化

# hugo.toml 优化配置
[minify]
  disableCSS = false
  disableHTML = false
  disableJS = false
  minifyOutput = true

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true

总结

通过 GitHub Pages 部署 Hugo 博客具有以下优势：

  • ✅ 完全免费
  • ✅ 自动化部署
  • ✅ 版本控制
  • ✅ 支持自定义域名
  • ✅ 全球 CDN 加速

掌握这套流程后，你就可以专注于内容创作，而不用担心服务器运维问题。开始你的博客之旅吧！

部署愉快！如有问题欢迎交流讨论。