本文章没有找到对应的语言版本

部署Hugo博客到GitHub Pages详细教程

前言

本文将详细介绍如何将Hugo博客部署到GitHub Pages，让您的博客在互联网上免费托管访问。

准备工作

1. 确保已安装Git

如果尚未安装Git，请访问 Git官网 下载并安装。

验证Git是否安装成功：

git --version

2. 准备GitHub账号

如果没有GitHub账号，请先注册：https://github.com/

第一步：创建GitHub仓库

1. 登录GitHub

访问 https://github.com/ 并登录您的账号。

2. 创建新仓库

  • 点击右上角的 + 号，选择 New repository
  • 仓库名称：输入 username.github.io（将username替换为您的GitHub用户名）
    • 例如：如果您的用户名是 lxttz，则仓库名应为 lxttz.github.io
  • 可见性：选择 Public（公开）
  • 初始化：可以勾选 Add a README file（可选）
  • 点击 Create repository 创建仓库

重要说明：仓库名必须是 您的用户名.github.io，这样才能直接通过该域名访问您的博客。

第二步：本地Git配置

1. 配置Git用户信息（首次使用需要） 

git config --global user.name "您的GitHub用户名"
git config --global user.email "您的GitHub邮箱"

2. 生成SSH密钥（推荐方式） 

# 检查是否已有SSH密钥
ls ~/.ssh

# 如果没有，生成新的SSH密钥
ssh-keygen -t ed25519 -C "您的GitHub邮箱"

# 按提示操作，可以直接按回车使用默认设置

3. 添加SSH密钥到GitHub 

# 复制公钥内容
cat ~/.ssh/id_ed25519.pub

# 或者使用（仅适用于macOS）
pbcopy < ~/.ssh/id_ed25519.pub

然后在GitHub添加SSH密钥：

  1. 点击头像 → Settings
  2. 左侧菜单 → SSH and GPG keys
  3. 点击 New SSH key
  4. 粘贴刚才复制的公钥内容
  5. 点击 Add SSH key

4. 测试SSH连接 

ssh -T git@github.com

如果看到 Hi username! You've successfully authenticated... 说明配置成功。

第三步：初始化本地仓库并推送到GitHub

1. 进入博客项目目录 

cd g:/hugo/hugo主题/hugo-theme-reimu/blog

2. 初始化Git仓库 

git init

3. 创建 .gitignore 文件

为了避免提交不必要的文件，创建 .gitignore 文件：

# Windows PowerShell
New-Item .gitignore -ItemType File

编辑 .gitignore 文件，添加以下内容：

# Hugo生成的文件
public/
resources/

# 系统文件
.DS_Store
Thumbs.db

# 编辑器
.vscode/
.idea/
*.swp
*.swo

# 其他
node_modules/

4. 添加所有文件到暂存区 

git add .

5. 提交文件 

git commit -m "Initial commit"

6. 关联远程仓库 

# 使用SSH方式（推荐）
git remote add origin git@github.com:您的用户名/您的用户名.github.io.git

# 或使用HTTPS方式
git remote add origin https://github.com/您的用户名/您的用户名.github.io.git

7. 推送到GitHub 

# 第一次推送需要设置上游分支
git branch -M main
git push -u origin main

第四步：配置GitHub Pages

1. 进入仓库设置

在GitHub仓库页面，点击 Settings 标签。

2. 启用GitHub Pages

  1. 左侧菜单找到 Pages（在 Code and automation 部分）
  2. 在 Build and deployment 部分：
    • Source：选择 Deploy from a branch
    • Branch：选择 main 分支和 / (root) 目录
  3. 点击 Save 保存

3. 等待部署

GitHub会自动部署您的网站，通常需要1-2分钟。

  • 页面会显示 Your site is live at https://您的用户名.github.io/
  • 如果看到 ✓ Your site is live 表示部署成功

第五步：生成Hugo静态文件并推送

由于GitHub Pages默认使用Jekyll，而Hugo生成的静态文件在 public 目录，我们需要将生成的文件推送到仓库。

方法一：手动构建并推送（简单方式）

1. 生成静态文件 

hugo

这会在项目根目录生成 public 文件夹。

2. 将public文件夹推送到GitHub

创建一个子文件夹来管理public：

# 删除public文件夹中的.git（如果之前已经初始化）
rm -rf public/.git

# 进入public目录
cd public

# 初始化git仓库
git init

# 添加远程仓库（注意：这是你的GitHub Pages仓库）
git remote add origin git@github.com:您的用户名/您的用户名.github.io.git

# 添加所有文件
git add .

# 提交
git commit -m "Deploy Hugo site"

# 推送到main分支
git branch -M main
git push -u origin main --force

# 返回项目根目录
cd ..

方法二：使用GitHub Actions自动部署（推荐，更简单）

1. 创建GitHub Actions工作流

在项目根目录创建以下文件夹和文件：

.github/workflows/hugo.yml

2. 编辑 hugo.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
    env:
      HUGO_VERSION: 0.120.4
    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: Install Dart Sass Embedded
        run: sudo snap install dart-sass-embedded

      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive
          fetch-depth: 0

      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5

      - name: Install Node.js dependencies
        run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"

      - name: Build with Hugo
        env:
          HUGO_CACHEDIR: ${{ runner.temp }}/hugo_cache
          HUGO_ENVIRONMENT: production
        run: |
          hugo \
            --minify \
            --baseURL "${{ steps.pages.outputs.base_url }}/"

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        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@v4

3. 提交并推送GitHub Actions配置 

git add .github/workflows/hugo.yml
git commit -m "Add GitHub Actions workflow"
git push origin main

4. 启用GitHub Pages

  1. 进入仓库的 Settings → Pages
  2. 在 Build and deployment 中：
    • Source：选择 GitHub Actions
  3. 保存设置

这样，每次你推送代码到 main 分支，GitHub Actions会自动构建并部署你的博客。

第六步：访问你的博客

部署成功后，可以通过以下地址访问你的博客：

https://您的用户名.github.io/

例如：https://lxttz.github.io/

第七步：更新博客内容

当你添加新文章或修改内容后，只需：

如果使用GitHub Actions： 

# 添加修改的文件
git add .

# 提交
git commit -m "添加新文章：文章标题"

# 推送到GitHub
git push origin main

推送后，GitHub Actions会自动构建并部署，大约1-2分钟后即可访问。

如果手动部署： 

# 1. 先更新源代码
git add .
git commit -m "更新内容"
git push origin main

# 2. 生成静态文件
hugo

# 3. 推送public文件夹
cd public
git add .
git commit -m "Deploy Hugo site"
git push origin main --force
cd ..

常见问题排查

1. 部署后访问404

  • 检查仓库名是否正确（必须是 用户名.github.io）
  • 等待2-3分钟后刷新页面
  • 检查GitHub Pages设置是否正确启用

2. 样式或图片显示异常

  • 确保 config/_default/params.yml 中的路径配置正确
  • 检查图片是否在正确的目录（static/ 或 public/）
  • 确保baseURL配置正确

3. 评论系统在GitHub Pages不工作

  • 对于Utterances，确保GitHub仓库是公开的
  • 确保已在仓库设置中启用了Issues
  • 确保已安装Utterances GitHub App

4. 自定义域名

如果需要使用自定义域名：

  1. 在GitHub仓库的 Settings → Pages 中添加自定义域名
  2. 根据提示配置DNS记录
  3. 在项目中创建 static/CNAME 文件，内容为你的域名

更新baseURL配置

部署到GitHub Pages后，需要更新 hugo.toml 中的baseURL：

baseURL = 'https://您的用户名.github.io/'

例如：

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

总结

恭喜！你已经成功将Hugo博客部署到GitHub Pages了。现在你可以：

  • 通过 https://您的用户名.github.io/ 访问你的博客
  • 通过Git推送更新来发布新文章
  • 享受免费的GitHub Pages托管服务

祝你的博客之旅愉快！🎉

说些什么吧！

utterances