IT

使用 Hugo + GitHub 搭建个人博客（自动部署）

想要一个自己的博客，省心又免费？

试试 Hugo + GitHub Pages！只需几个步骤，就能搭建一个 高速、免费、可自动部署 的个人博客网站。

1. 安装 Hugo

Windows

用 Scoop（推荐）：

scoop install hugo

或者直接去 Hugo 官方网站 下载。

Mac 

brew install hugo

Linux 

sudo apt install hugo  # Debian/Ubuntu
sudo dnf install hugo  # Fedora

检查是否安装成功：

hugo version

2. 创建 Hugo 博客 

hugo new site myblog
cd myblog

Hugo 会生成一个网站的基本目录结构。

3. 选择并安装主题

去 Hugo Themes 找个喜欢的主题，比如 ananke，然后安装：

git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke

然后编辑 config.toml：

theme = "ananke"
baseURL = "https://<username>.github.io/"

4. 添加第一篇文章 

hugo new posts/my-first-post.md

然后编辑 content/posts/my-first-post.md，加上内容：

---
title: "我的第一篇博客"
date: 2025-01-31T12:00:00+08:00
draft: false
---
Hello, Hugo!

5. 本地预览 

hugo server -D

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

6. 发布到 GitHub

（1）创建 GitHub 仓库

  • 私有仓库：myblog-src（存源码）
  • 公开仓库：<username>.github.io（存生成的网站文件）

（2）把源码推送到私有仓库 

git remote add origin https://github.com/<username>/myblog-src.git
git branch -M master
git add .
git commit -m "初始化 Hugo 博客"
git push -u origin master

7. 创建 GitHub Token（GITHUB_TOKEN）

由于我们要把生成的静态网站推送到 username.github.io 仓库，需要 GitHub Token 进行授权。

（1）生成 Token

  1. 进入 GitHub，点击右上角头像，选择 Settings
  2. 在左侧菜单选择 Developer settings → Personal access tokens → Fine-grained tokens
  3. 点击 Generate new token，然后：
    • Repository access 选择 Only select repositories，勾选 <username>.github.io
    • Permissions：
      • Contents: 选择 Read and Write
      • 其他保持默认
    • 点击 Generate token
  4. 复制 Token，保存到本地（只能看一次）。

（2）添加到 GitHub Actions

  1. 进入 myblog-src 仓库
  2. 打开 Settings → Secrets and variables → Actions → New repository secret
  3. Name 填写 DEPLOY_TOKEN，Value 粘贴刚才复制的 Token，点击 Add secret

8. 配置 GitHub Actions（自动部署）

在 myblog-src 仓库中，新建 .github/workflows/deploy.yml，写入：

# Sample workflow for building and deploying a Hugo site to GitHub Pages
name: Deploy Hugo site to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches:
      - master

# Default to bash
defaults:
  run:
    shell: bash

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      HUGO_VERSION: 0.142.0
    steps:
      - name: Install Hugo CLI
        run: |
          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
          && sudo dpkg -i ${{ runner.temp }}/hugo.deb
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive
          fetch-depth: 0
      - name: Build Web
        run: hugo -D
      - name: Deploy Web
        uses: peaceiris/actions-gh-pages@v4
        with:
            PERSONAL_TOKEN: ${{ secrets.BLOG_TOKEN }}
            EXTERNAL_REPOSITORY: <username>/<username>.github.io
            PUBLISH_BRANCH: master
            PUBLISH_DIR: ./public
            commit_message: auto deploy

9. 配置 GitHub Pages

进入 <username>.github.io 仓库：

  • Settings → Pages
  • Branch 选择 master
  • 点击 Save

10. 提交修改，自动部署！

以后只需提交博客源码，GitHub Actions 会自动部署：

git add .
git commit -m "更新文章"
git push

稍等片刻，你的博客就会出现在：
👉 https://<username>.github.io/

总结

你已经成功使用 Hugo + GitHub Pages 搭建了一个 私有源码、自动部署 的个人博客！🎉
随时写文章，推送后 自动上线，是不是超简单？💡

🚀 快去试试吧！