这篇文章主要记录我搭建Hugo博客的详细过程，包括搭建、配置、主题选择和部署到GitHub Pages的完整步骤，以及搭建过程中遇到的问题及解决方法。

1. 准备工作

1.1 安装Git

首先需要安装Git，用于版本控制和部署到GitHub。

  • Windows用户：从Git官网下载安装包并安装
  • macOS用户：使用Homebrew安装 brew install git
  • Linux用户：使用包管理器安装，如 sudo apt install git

1.2 注册GitHub账号

如果还没有GitHub账号，需要先注册一个。

2. 创建GitHub仓库

  1. 登录GitHub账号
  2. 点击右上角的"+“按钮，选择"New repository”
  3. 仓库名称填写为"你的GitHub用户名.github.io"（例如：username.github.io）
  4. 选择公开仓库（Public）
  5. 勾选"Initialize this repository with a README"
  6. 点击"Create repository"创建仓库

3. 安装Hugo

3.1 下载Hugo

从Hugo官方GitHub releases页面下载适合你操作系统的版本：

  • Windows：选择 hugo_extended_{版本}_Windows-64bit.zip
  • macOS：选择 hugo_extended_{版本}_macOS-64bit.tar.gz
  • Linux：选择 hugo_extended_{版本}_Linux-64bit.tar.gz

3.2 安装Hugo

Windows用户：

  1. 解压下载的zip文件
  2. 将解压得到的 hugo.exe 文件复制到一个固定的文件夹，例如 C:\hugo\bin
  3. 右键点击"此电脑" → “属性” → “高级系统设置” → “环境变量”
  4. 在"系统变量"中找到"Path"，点击"编辑"
  5. 点击"新建"，添加 C:\hugo\bin 路径
  6. 点击"确定"保存设置

macOS/Linux用户：

  1. 解压下载的tar.gz文件
  2. 将解压得到的 hugo 可执行文件移动到 /usr/local/bin 目录 
    1

    sudo mv hugo /usr/local/bin/

3.3 验证安装

打开终端或命令提示符，运行以下命令验证Hugo是否安装成功：

1

hugo version

如果显示Hugo版本信息，则安装成功。

4. 创建Hugo网站

4.1 初始化网站

选择一个合适的目录，运行以下命令创建一个新的Hugo网站：

1

hugo new site my-blog

这将创建一个名为 my-blog 的文件夹，包含Hugo网站的基本结构。

4.2 进入网站目录

1

cd my-blog

5. 选择并安装主题

5.1 选择主题

Hugo有很多优秀的主题，可以在Hugo Themes网站上浏览选择。本文使用的是PaperMod主题，这是一个简洁美观的主题。

5.2 安装主题

使用Git克隆主题到 themes 目录：

1

git clone https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

5.3 配置主题

在网站根目录下找到 config.toml 或 config.yml 文件（如果没有，需要创建一个），添加以下配置：

1
2
3
4
5

# config.yml
baseURL: https://yourusername.github.io
languageCode: zh-cn
title: Your Blog Title
theme: PaperMod

6. 配置网站

6.1 基本配置

根据你的需求，进一步配置网站信息：

 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

# 网站基本信息
baseURL: https://yourusername.github.io
languageCode: zh-cn
title: Your Blog Title
theme: PaperMod

# 作者信息
params:
  author: Your Name
  description: "Your blog description"
  defaultTheme: auto
  ShowReadingTime: true
  ShowShareButtons: true
  ShowPostNavLinks: true
  ShowBreadCrumbs: true

# 菜单配置
menu:
  main:
    - identifier: home
      name: 首页
      url: /
      weight: 1
    - identifier: posts
      name: 文章
      url: /posts/
      weight: 2
    - identifier: categories
      name: 分类
      url: /categories/
      weight: 3
    - identifier: tags
      name: 标签
      url: /tags/
      weight: 4
    - identifier: about
      name: 关于
      url: /about/
      weight: 5

# 输出格式
outputs:
  home:
    - HTML
    - RSS
    - JSON

6.2 创建内容

创建第一篇博客文章：

1

hugo new posts/first-post.md

编辑 content/posts/first-post.md 文件，添加文章内容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

---
title: "我的第一篇文章"
date: 2023-03-05T12:00:00+08:00
author: "Your Name"
categories:
  - 技术
tags:
  - Hugo
  - 博客
description: "这是我的第一篇博客文章"
---

# 欢迎来到我的博客

这是我使用Hugo搭建的博客的第一篇文章。

## 为什么选择Hugo？

- 速度快
- 配置简单
- 主题丰富
- 支持Markdown

7. 本地预览

在网站根目录运行以下命令启动本地服务器：

1

hugo server -D

然后在浏览器中访问 http://localhost:1313 查看网站效果。

8. 部署到GitHub Pages

8.1 构建网站

在网站根目录运行以下命令构建静态网站：

1

hugo

这将在 public 目录生成静态网站文件。

8.2 部署到GitHub

方法一：手动部署

  1. 进入 public 目录

    1

    cd public

  2. 初始化Git仓库

    1
2

    git init
git remote add origin https://github.com/yourusername/yourusername.github.io.git

  3. 提交并推送

    1
2
3

    git add .
git commit -m "Initial commit"
git push -u origin main

方法二：使用GitHub Actions自动部署

  1. 在网站根目录创建 .github/workflows/gh-pages.yml 文件

  2. 添加以下内容：

     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

    name: Deploy Hugo site to Pages

on:
  push:
    branches:
      - main  # 或者你的主分支名称

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true  # 包含主题
          fetch-depth: 0

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

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

  3. 推送更改到GitHub

    1
2
3

    git add .
git commit -m "Add GitHub Actions workflow"
git push

9. 常见问题及解决方法

9.1 主题安装后不显示

  • 检查主题名称是否正确配置
  • 检查主题文件是否正确克隆到 themes 目录
  • 运行 hugo server -D 重新启动本地服务器

9.2 部署后GitHub Pages显示404

  • 检查仓库名称是否正确（必须是 username.github.io）
  • 检查是否推送到了 main 分支
  • 等待几分钟，GitHub Pages需要时间更新

9.3 本地预览时样式丢失

  • 检查 baseURL 配置是否正确
  • 尝试清除浏览器缓存

10. 后续优化

  • 添加网站统计（如Google Analytics）
  • 配置评论系统（如Disqus、Utterances）
  • 优化网站SEO
  • 定期更新主题
  • 备份网站内容

通过以上步骤，你已经成功搭建了一个基于Hugo的个人博客，并部署到了GitHub Pages。随着使用的深入，你可以根据自己的需求进一步定制和优化你的博客。