Hugo 生成静态网站并部署到 GitHub Pages 的完整流程

扩展阅读：[ Hugo 生成静态网站并部署到 GitHub Pages 的完整流程]

以下是使用 Hugo 生成静态网站并部署到 GitHub Pages 的完整流程，包含代码示例和最佳实践：

1. 环境准备

1.1 安装 Hugo

# macOS (通过 Homebrew) brew install hugo # Windows (Chocolatey) choco install hugo # Linux (apt) sudo apt-get install hugo

验证安装：

hugo version # 输出示例: hugo v0.127.0+extended linux/amd64 BuildDate=...

1.2 创建 GitHub 仓库

• 仓库名格式：<username>.github.io（例如 johnsmith.github.io）

• 初始化时 不添加 README 或 LICENSE（Hugo 会自动生成）

2. 创建 Hugo 项目

2.1 初始化站点

hugo new site myblog --force cd myblog

2.2 添加主题（以 PaperMod 为例）

git init git submodule add https://github.com/adityatelange/hugo-PaperMod themes/PaperMod

2.3 配置主题

# config.toml baseURL = "https://<username>.github.io/" languageCode = "en-us" title = "My Hugo Blog" theme = "PaperMod" [params] defaultTheme = "auto" # 自动切换日间/夜间模式

3. 创建内容

3.1 新建文章

hugo new posts/first-post.md

编辑内容：

# content/posts/first-post.md --- title: "Hello Hugo!" date: 2024-07-20 draft: false --- 这是我的第一篇 Hugo 文章！

3.2 本地预览

hugo server -D # -D 显示草稿

访问 http://localhost:1313 查看效果

4. 部署到 GitHub Pages

4.1 配置发布目录

# config.toml 添加 publishDir = "docs" # GitHub Pages 默认从 docs 目录发布

4.2 生成静态文件

hugo # 生成的文件将保存到 docs 目录

4.3 推送代码到 GitHub

git remote add origin https://github.com/<username>/<username>.github.io.git git add . git commit -m "Initialize Hugo site" git push -u origin main

4.4 配置 GitHub Pages

1. 进入仓库 → Settings → Pages

2. 设置 Source 为 Deploy from a branch

3. 选择分支 main 和目录 /docs

5. 自动化部署（可选）

使用 GitHub Actions 实现自动构建：

# .github/workflows/gh-pages.yml name: GitHub Pages on: push: branches: [ "main" ] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: submodules: recursive - name: Setup Hugo uses: peaceiris/actions-hugo@v2 with: hugo-version: '0.127.0' - name: Build run: hugo --minify - name: Deploy uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./docs

6. 访问网站

• 自动生成地址：https://<username>.github.io

• 首次部署需等待 1-5 分钟生效

7. 更新内容流程

1. 编辑 Markdown 文件

2. 本地测试：

   hugo server -D

3. 生成并推送：

   hugo && git add . && git commit -m "Update content" && git push

常见问题解决

1. 页面显示 404：

   1. 检查 baseURL 配置是否正确

   2. 确认 publishDir 设置为 docs

2. 主题未加载：

   1. 确保使用 git submodule 添加主题

   2. 运行 git submodule update --init --recursive

3. 构建超时：

   1. 简化模板或减少图片数量

   2. 使用 CDN 托管大型资源

通过此方案，您将获得：

• ✅ 完全免费的静态网站托管

• ⚡ 极快的加载速度（Hugo + GitHub CDN）

• 🔄 自动化部署工作流

• 📱 响应式设计（通过现代主题实现）

如需进阶功能，可扩展：

• 添加评论系统（如 utterances）

• 集成 Google Analytics

• 使用 Netlify 实现表单提交功能