Hugo + LoveIt + GitHub Pages 博客部署完整指南

基于 Hugo + LoveIt + GitHub Pages 的完整部署流程与常见问题

咔咔收录于

2026-04-10 约 744 字预计阅读 4 分钟

本文记录基于 Hugo + LoveIt 主题 + GitHub Pages 的博客部署全过程，包括配置步骤、遇到的问题及解决方案。

一、环境准备

1.1 必要工具

工具	版本要求	用途
Hugo Extended	0.128.0+	静态网站生成器
Git	最新版	版本控制

1.2 安装 Hugo

# macOS
brew install hugo

# Windows (使用 winget)
winget install Hugo.Hugo.Extended

# Linux
sudo apt install hugo

验证安装：

hugo version  # 应显示 extended 版本

二、项目初始化

2.1 创建 Hugo 站点

hugo new site myblog
cd myblog
git init

2.2 添加 LoveIt 主题（Git 子模块）

git submodule add https://github.com/dillonzq/LoveIt.git themes/LoveIt
git submodule update --init --recursive

注意：使用子模块后，在其他机器克隆时需要加 --recursive 参数，或事后运行 git submodule update --init --recursive

三、核心配置

3.1 基础站点配置 (hugo.toml)

baseURL = 'https://yourname.github.io'
languageCode = 'zh-CN'
defaultContentLanguage = 'zh-cn'
title = 'Your Blog'
theme = 'LoveIt'

[params]
  description = "技术博客，记录学习与生活"
  keywords = ["博客", "技术", "Hugo", "LoveIt"]
  dateFormat = "2006-01-02"

  # 搜索配置 - 使用本地搜索（lunr.js）
  [params.search]
    enable = true
    type = "lunr"
    contentLength = 4000
    placeholder = "搜索..."
    maxResultLength = 10
    snippetLength = 50
    highlightTag = "em"
    absoluteURL = false

  # 首页配置
  [params.home]
    rss = 10
    [params.home.profile]
      enable = true
      avatarURL = "/images/avatar.png"
      title = "Your Name"
      subtitle = "博客副标题"
      typeit = true
      social = true

  # 代码高亮
  [params.page.code]
    copy = true
    maxShownLines = 50

  # 页脚配置
  [params.footer]
    enable = true
    hugo = false      # 隐藏 "由 Hugo 强力驱动"
    copyright = true
    since = 2020

四、GitHub Actions 自动部署

4.1 创建工作流文件

创建 .github/workflows/hugo.yml：

name: Deploy Hugo site to Pages

on:
  push:
    branches:
      - main
    paths:
      - 'content/**'
      - 'static/images/**'
      - 'hugo.toml'
      - 'themes/**'
      - '.github/workflows/hugo.yml'
  workflow_dispatch:

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

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

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HUGO_VERSION: 0.160.1
    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: Setup Pages
        id: pages
        uses: actions/configure-pages@v5

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

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        if: github.ref == 'refs/heads/main'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public
          publish_branch: gh-pages
          force_orphan: true    # 解决 gh-pages 分支冲突

4.2 启用 GitHub Pages

进入仓库 Settings → Pages
Source 选择 “Deploy from a branch”
Branch 选择 “gh-pages” /root
保存

五、常见问题与解决方案

问题 1：GitHub Actions 部署失败 - “gh-pages 分支冲突”

错误信息：

Error: Deployment failed: Resource not accessible by integration

原因：gh-pages 分支历史与当前构建冲突

解决：在部署配置中添加 force_orphan: true

- name: Deploy to GitHub Pages
  uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./public
    publish_branch: gh-pages
    force_orphan: true    # 强制重建分支，解决冲突

问题 2：文章不显示 - 日期为未来时间

现象：新建的文章在首页不显示

原因：Hugo 默认不显示未来日期的文章

解决：

将文章日期改为过去时间
或使用 hugo server -D 预览包含草稿的内容
生产构建时确保日期正确

问题 3：主题样式丢失 - 子模块未拉取

现象：网站没有样式，排版错乱

原因：克隆时未拉取主题子模块

解决：

# 方法 1：克隆时加 --recursive
git clone --recursive <repo-url>

# 方法 2：已克隆后初始化
git submodule update --init --recursive

问题 4：构建失败 - “partial not found”

错误信息：

execute of template failed: partial "opengraph.html" not found

原因：Hugo 内置模板路径错误

解决：使用正确的前缀：

<!-- 错误 -->
{{ partial "opengraph.html" . }}

<!-- 正确 -->
{{ partial "_internal/opengraph.html" . }}
{{ partial "_internal/twitter_cards.html" . }}

问题 5：GitHub Actions 频繁触发

现象：每次推送都触发构建，包括非内容更新

解决：配置路径过滤，仅相关内容变更时触发

on:
  push:
    branches:
      - main
    paths:
      - 'content/**'           # 文章内容
      - 'static/images/**'     # 图片资源
      - 'hugo.toml'            # 站点配置
      - 'themes/**'            # 主题更新

六、功能扩展配置

6.1 添加 utterances 评论系统

[params.page.comment]
  enable = true
  [params.page.comment.utterances]
    enable = true
    repo = "username/repo"      # 你的 GitHub 仓库
    issueTerm = "pathname"
    label = "comment"
    lightTheme = "github-light"
    darkTheme = "github-dark"

必要步骤：访问 https://github.com/apps/utterances/installations/new 安装 GitHub App

6.2 首页文章网格布局（2-3列）

创建 layouts/home.html：

{{- define "content" -}}
    <!-- ... 原有内容 ... -->
    <div class="posts-grid">
        {{- range $pages.Pages -}}
            {{- .Render "summary" -}}
        {{- end -}}
    </div>
    {{- partial "paginator.html" . -}}
{{- end -}}

创建 assets/css/_custom.scss：

.posts-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(320px, 1fr));
  gap: 1.5rem;
  margin: 1.5rem 0;

  .single.summary {
    margin: 0;
    height: 100%;
    display: flex;
    flex-direction: column;

    .featured-image-preview img {
      width: 100%;
      height: 160px;
      object-fit: cover;
    }
  }
}

// 响应式
@media screen and (max-width: 768px) {
  .posts-grid { grid-template-columns: 1fr; }
}
@media screen and (min-width: 769px) and (max-width: 1200px) {
  .posts-grid { grid-template-columns: repeat(2, 1fr); }
}
@media screen and (min-width: 1201px) {
  .posts-grid { grid-template-columns: repeat(3, 1fr); }
}

6.3 隐藏页脚 Hugo 和主题信息

[params.footer]
  enable = true
  hugo = false      # 隐藏 "由 Hugo 强力驱动 | 主题 - LoveIt"
  copyright = true
  since = 2020

七、本地开发命令

# 启动开发服务器（包含草稿）
hugo server -D

# 启动并允许局域网访问
hugo server -D --bind 0.0.0.0

# 生产构建（与 CI 一致）
hugo --gc --minify

# 创建新文章
hugo new content posts/my-post.md

八、部署检查清单

发布前确认：

hugo.toml 中 baseURL 配置正确
主题子模块已正确拉取
GitHub Actions 工作流配置正确
仓库 Settings → Pages 已启用
评论系统 App 已安装（如使用 utterances/giscus）
文章日期为未来时设置为 draft: true

目录