Github Page 配置

今日初战，花了五六个小时在 Hugo 方案的 GitHub Pages 上折腾，以下是总结的几大问题。

YAML & TOML 的使用 YAML 的 post 匹配使用 —。 TOML 文件使用 +++。这意味着不同的格式可能会对主题的切换有一定的门槛。不同的主题可能要求使用不同的格式。

项目名称项目名称最好用：<用户名>.github.io。如果是组织的 GitHub Pages，名称为：<组织名>.github.io。当然，如果有自定义域名，最好使用自定义域名。步骤逻辑 GitHub Pages 的逻辑：GitHub Pages 只需要源代码，并且可以是 private 的仓库。通过 workflow 在线上编译 Hugo 生成的所有 public 文件。 Public 文件的位置：需要设置一个 branch 来放置 public 文件，否则会覆盖源代码的分支。编译逻辑：GitHub Pages 会根据 workflow 和 public 文件再编译成真正的静态网站。 Source 设置：选择 from branch 模式。另一种模式暂未尝试。 Workflow Hugo 最坑的地方就是 workflow 配置了。尽管 Hugo 使用广泛，但能直接跑通的教程并不多。

很多提供 GitHub Actions 配置的仓库推荐 Hugo 的版本最好直接指定，而不是使用 latest，因为使用 latest 可能会遇到如下错误：

bash 复制代码 Error: fatal: Fetched in submodule path ’themes/hugo-theme-stack’, but it did not contain 25644648dcc6e96d9860d94f0837ec93abd17c8c. Direct fetching of that commit failed. 这种问题非常烦人，尤其当你没有改动太多配置却频繁报错时。最终，我通过直接指定 Hugo 的准确版本，才成功运行。

示例 GitHub Actions Workflow 以下是一个成功运行的 GitHub Actions 配置，供参考：

yaml 复制代码 name: GitHub Pages

on: push: branches: - main # 当推送到 main 分支时触发工作流

jobs: deploy: runs-on: ubuntu-22.04 steps: # Step 1: Checkout the repository and submodules - uses: actions/checkout@v4 with: submodules: true # 确保拉取子模块（例如主题） fetch-depth: 0 # 获取所有历史记录，确保 .GitInfo 和 .Lastmod 正确

  # Step 2: Setup Hugo
  - name: Setup Hugo
    uses: peaceiris/actions-hugo@v3
    with:
      hugo-version: '0.136.2' # 指定准确的 Hugo 版本，避免兼容性问题
      extended: true  # 使用 Hugo 扩展版（支持 SCSS）

  # Step 3: Build the Hugo site
  - name: Build
    run: hugo --minify

  # Step 4: Deploy to GitHub Pages
  - name: Deploy
    uses: peaceiris/actions-gh-pages@v3
    with:
      personal_token: ${{ secrets.密钥名 }}  # 使用 Personal Access Token
      publish_dir: ./public  # Hugo 默认生成的静态网站目录
      publish_branch: gh-pages  # 发布到 gh-pages 分支
      commit_message: "Deploy GitHub Pages site"

总结通过指定正确的 Hugo 版本，并按照以上配置的 GitHub Actions 工作流，成功部署 Hugo 站点到 GitHub Pages。