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

进入仓库 → Settings → Pages
设置 Source 为 Deploy from a branch
选择分支 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. 更新内容流程

编辑 Markdown 文件
本地测试：
复制代码
hugo server -D
生成并推送：
复制代码
hugo && git add . && git commit -m "Update content" && git push

常见问题解决

页面显示 404：
1. 检查 baseURL 配置是否正确
2. 确认 publishDir 设置为 docs
主题未加载：
1. 确保使用 git submodule 添加主题
2. 运行 git submodule update --init --recursive
构建超时：
1. 简化模板或减少图片数量
2. 使用 CDN 托管大型资源

通过此方案，您将获得：

✅ 完全免费的静态网站托管
⚡ 极快的加载速度（Hugo + GitHub CDN）
🔄 自动化部署工作流
📱 响应式设计（通过现代主题实现）

如需进阶功能，可扩展：

添加评论系统（如 utterances）
集成 Google Analytics
使用 Netlify 实现表单提交功能