Hugo + GitHub 搭建静态网站：完整流程、踩坑点与专业知识

Hugo + GitHub 搭建静态网站：完整流程、踩坑点与专业知识

Hugo 是一款快速、灵活的静态网站生成器，结合 GitHub Pages 或 Cloudflare Pages，可以轻松搭建和部署个人博客或项目站点。以下是完整的搭建流程，以及可能遇到的坑和相关技术知识。

1. 准备工作

安装 Hugo

  • Mac: brew install hugo
  • Windows: 用 Scoop 或 Chocolatey choco install hugo-extended
  • Linux: sudo apt install hugo 或 dnf install hugo

注意

  • 必须安装 hugo-extended 版本，否则无法处理某些主题（如 SCSS）
  • 检查版本：hugo version

配置 Git 和 GitHub

  1. 安装 Git（如果未安装）：
    • Mac: brew install git
    • Windows: 用 Git Bash
    • Linux: sudo apt install git
  2. 设置 Git 用户信息： 
    git config --global user.name "Your Name"
git config --global user.email "[email protected]"

踩坑点

  • Git 未配置 SSH Key，会导致 GitHub 操作失败
    • 解决：使用 ssh-keygen -t ed25519 生成 SSH key，并添加到 GitHub

2. 创建 Hugo 项目

hugo new site my-blog
cd my-blog

选择主题

Hugo 使用主题来自定义外观和功能：

git submodule add https://github.com/nanxiaobei/hugo-paper themes/paper
echo 'theme = "paper"' >> config.toml

或者直接下载：

git clone --depth=1 https://github.com/nanxiaobei/hugo-paper themes/paper

踩坑点

  • 主题未正确安装，导致 hugo 命令报错
    • 解决：git submodule update --init --recursive
  • 某些主题需要 hugo-extended，否则 CSS/JS 可能无法正常加载

3. 编写内容

hugo new posts/my-first-post.md

然后编辑 content/posts/my-first-post.md 并写文章。

踩坑点

  • 文章默认 draft: true，不会被 hugo 渲染
    • 解决：发布时改为 draft: false，或者使用 hugo server -D 预览所有文章

4. 本地预览

hugo server -D

浏览器打开 http://localhost:1313/ 预览网站。

踩坑点

  • CSS/JS 404，可能是 baseURL 没有正确设置
    • 解决：在 config.toml 设置 baseURL = "http://localhost:1313/"

5. 部署到 GitHub Pages

初始化 Git 仓库

git init
git add .
git commit -m "First commit"
git branch -M main
git remote add origin https://github.com/yourusername/yourrepo.git
git push -u origin main

踩坑点

  • fatal: remote origin already exists
    • 解决：git remote remove origin 后重新 git remote add origin ...

配置 GitHub Actions（推荐）

在 .github/workflows/deploy.yml 添加：

name: Deploy Hugo site
on:
  push:
    branches:
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          submodules: true
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true
      - name: Build
        run: hugo --minify
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

踩坑点

  • GitHub Actions 失败，可能是 hugo-extended 版本不匹配
    • 解决：确保 hugo-version: 'latest' 并且 extended: true

6. 绑定自定义域名

配置 GitHub Pages

  1. 在 GitHub 仓库的 Settings > Pages 里，设置 Branch: gh-pages（或 main）
  2. 在 public/CNAME 文件写入你的域名 komox.me： 
    echo "komox.me" > public/CNAME

配置 Cloudflare

如果你用 Cloudflare 代理，需要：

  1. 在 Cloudflare 添加 DNS 记录：
    • A 记录（指向 GitHub Pages 的 IP）
    • CNAME 记录：komox.me -> yourusername.github.io
  2. 启用 HTTPS：
    • 在 Cloudflare 开启 SSL/TLS > Full (Strict)，防止 HTTPS 失效

踩坑点

  • Cloudflare 代理模式影响 Hugo 站点加载
    • 解决：尝试切换代理模式（橙色云朵 ☁️ ➝ 灰色云朵 ☁️）

7. 其他进阶优化

开启 Google Analytics & SEO

在 config.toml 添加：

googleAnalytics = "UA-XXXXXXXXX-X"

自动生成 sitemap

[sitemap]
  changefreq = "weekly"
  filename = "sitemap.xml"

开启 Open Graph / Twitter Card

[params]
  description = "My awesome blog"
  images = ["og-image.jpg"]

踩坑点

  • og:image 地址需使用绝对路径，否则社交媒体抓取不到图片

8. 迁移 Hugo 站点到 Cloudflare Pages（可选）

  1. 创建 Cloudflare Pages，绑定 GitHub 仓库
  2. Cloudflare Pages 自动构建，无需 GitHub Actions：
    • Build command: hugo --minify
    • Output directory: public
  3. 绑定自定义域名：在 Cloudflare Pages 里设置 komox.me

踩坑点

  • Cloudflare Pages 不支持 .gitmodules
    • 解决方案：hugo mod get -u，或者 git clone 主题后删除 .gitmodules

总结

步骤 关键命令 踩坑点 安装 Hugo brew install hugo 确保是 hugo-extended 版本 创建站点 hugo new site my-blog 主题需正确安装 本地预览 hugo server -D baseURL 需匹配 部署 GitHub Pages git push + GitHub Actions 主题 submodule 需正确配置 绑定自定义域名 Cloudflare DNS + CNAME Cloudflare 代理模式可能影响访问 Cloudflare Pages 直接连接 GitHub .gitmodules 可能不兼容

Hugo + GitHub 是一个高效、低成本的静态站点方案，结合 Cloudflare 可以获得更好的性能和安全性！ 🚀