如何在 Github Pages 上部署 Hugo 网站 • Overstarry Site

31 Aug 2024

4 minutes reading time

#前言

本文将介绍当初我搭建这个博客网站的时候，是如何将 Hugo 网站部署到 GitHub 上的，本文会采用与 hugo 官方不同的方式进行部署。

#创建仓库

首先我们在 GitHub 上创建一个仓库，仓库名称为 username.github.io，其中 username 为你的 GitHub 用户名。这个仓库是用来存储hugo最终生成的静态网站文件的。再创建一个名称为 blogs 的仓库，这个仓库是用来存储 hugo 网站源内容文件的。

#启用 GitHub Pages

在 username.github.io 仓库中，点击 Settings 选项卡，在 GitHub Pages 中选择 Source 为从分支部署，然后点击 Save 按钮。

#启用 GitHub Actions

接下来要实现提交 hugo 网站源文件到 blogs 仓库后，自动将 hugo 网站源文件编译成静态网站文件，并提交到 username.github.io 仓库中，这样就可以通过访问 username.github.io 仓库来访问 hugo 网站了。

#生成 personal_token

在配置 Actions 前，需要先生成 personal_token，用于在 GitHub Actions 中使用。我们进入 Settings 选项卡，在 Developer settings 中选择 Personal access tokens，然后选择 Tokens (classic)，然后点击 Generate new token 下的Generate new token(classic)按钮，在 Note 中输入 blog，在 Expiration 中选择 No expiration，在 Select scopes 中选择 repo 和 admin:repo_hook，然后点击 Generate token 按钮，生成 personal_token。

保存好 personal_token，后面会用到。

#配置 personal_token secret

在 blogs 仓库中，点击 Settings 选项卡，在 Secrets and variables 中选择 Actions，然后点击 New repository secret，在 Name 中输入 ACTION_ACCESS_TOKEN，在 Value 中输入刚刚生成的 personal_token，然后点击 Add secret 按钮。

#配置 GitHub Actions

在 blogs 仓库中，在 .github/workflows 目录下创建一个名为 deploy.yml 的 GitHub Actions 配置文件，内容如下：

name: github pages # 名字自取

on:
  push:
    branches:
      - master  # 这里的意思是当 main分支发生push的时候，运行下面的jobs，这里先改为github-actions

jobs:
  deploy: # 任务名自取
    runs-on: ubuntu-22.04	# 在什么环境运行任务
    steps:
      - uses: actions/checkout@v4	# 引用actions/checkout这个action，与所在的github仓库同名
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive) 获取submodule主题
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo	# 步骤名自取
        uses: peaceiris/actions-hugo@v3	# hugo官方提供的action，用于在任务环境中获取hugo
        with:
          hugo-version: 'latest'	# 获取最新版本的hugo
          # extended: true

      - name: Build
        run: hugo --minify	# 使用hugo构建静态网页

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3	# 一个自动发布github pages的action
        with:
          # github_token: ${{ secrets.GITHUB_TOKEN }} 该项适用于发布到源码相同repo的情况，不能用于发布到其他repo
          external_repository: overstarry/overstarry.github.io	# 发布到哪个repo
          personal_token: ${{ secrets.ACTION_ACCESS_TOKEN }}	# 发布到其他repo需要提供上面生成的personal access token
          publish_dir: ./public	# 注意这里指的是要发布哪个文件夹的内容，而不是指发布到目的仓库的什么位置，因为hugo默认生成静态网页到public文件夹，所以这里发布public文件夹里的内容
          publish_branch: master	# 发布到哪个branch

personal_token 修改为刚刚配置的 personal_token 名称，external_repository 修改为 username.github.io 仓库的地址，publish_branch 修改为 username.github.io 仓库的 branch。

截止到此，我们就实现了使用 Github Pages 部署 Hugo 网站。如果你想要使用自定义域名，可以参考 Hugo Github Pages自定义域名进行配置。

如果你想将 hugo 网站部署到 cloudflare pages 上，可以参考 Hugo Cloudflare Pages 进行配置。

#参考

https://hugo.opendocs.io/hosting-and-deployment/hosting-on-github/
https://pages.github.com/
https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site
https://overstarry.vip/posts/github_page%E8%87%AA%E5%AE%9A%E4%B9%89%E5%9F%9F%E5%90%8D/
https://developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-site/