在 GitHub Pages 上托管

网站类型

GitHub Pages 网站有三种类型：项目、用户和组织。项目网站连接到 GitHub 上托管的特定项目。用户和组织网站连接到 GitHub.com 上的特定账户。

前提条件

请在继续之前完成以下任务：

1. 创建 GitHub 账户
2. 登录 您的 GitHub 账户
3. 创建 项目的 GitHub 仓库
4. 创建 项目的本地 Git 仓库，并带有指向 GitHub 仓库的 远程 引用
5. 在本地 Git 仓库中创建 Hugo 网站，并使用 hugo server 命令测试
6. 将更改提交到本地 Git 仓库并推送到 GitHub 仓库

步骤

步骤 1

访问您的 GitHub 仓库。从主菜单选择 Settings > Pages。在屏幕中央您将看到：

将 Source 更改为 GitHub Actions。更改立即生效；您无需按保存按钮。

步骤 2

在网站配置中，更改图像缓存的位置到 cacheDir，如下所示：

caches:
  images:
    dir: :cacheDir/images

[caches]
  [caches.images]
    dir = ':cacheDir/images'

{
   "caches": {
      "images": {
         "dir": ":cacheDir/images"
      }
   }
}

有关更多信息，请参阅 配置文件缓存。

步骤 3

在名为 .github/workflows 的目录中创建名为 hugo.yaml 的文件。

mkdir -p .github/workflows
touch .github/workflows/hugo.yaml

步骤 4

将下面的 YAML 复制并粘贴到您创建的文件中。

.github/workflows/hugo.yaml

name: Build and deploy
on:
  push:
    branches:
      - main
  workflow_dispatch:
permissions:
  contents: read
  pages: write
  id-token: write
concurrency:
  group: pages
  cancel-in-progress: false
defaults:
  run:
    shell: bash
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      DART_SASS_VERSION: 1.97.3
      GO_VERSION: 1.25.6
      HUGO_VERSION: 0.155.3
      NODE_VERSION: 24.13.0
      TZ: Europe/Oslo
    steps:
      - name: Checkout
        uses: actions/checkout@v6
        with:
          submodules: recursive
          fetch-depth: 0
      - name: Setup Go
        uses: actions/setup-go@v6
        with:
          go-version: ${{ env.GO_VERSION }}
          cache: false
      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: ${{ env.NODE_VERSION }}
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5
      - name: Create directory for user-specific executable files
        run: |
          mkdir -p "${HOME}/.local"
      - name: Install Dart Sass
        run: |
          curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
          tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
          rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
          echo "${HOME}/.local/dart-sass" >> "${GITHUB_PATH}"
      - name: Install Hugo
        run: |
          curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
          mkdir "${HOME}/.local/hugo"
          tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
          rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
          echo "${HOME}/.local/hugo" >> "${GITHUB_PATH}"
      - name: Verify installations
        run: |
          echo "Dart Sass: $(sass --version)"
          echo "Go: $(go version)"
          echo "Hugo: $(hugo version)"
          echo "Node.js: $(node --version)"
      - name: Install Node.js dependencies
        run: |
          [[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true
      - name: Configure Git
        run: |
          git config core.quotepath false
      - name: Cache restore
        id: cache-restore
        uses: actions/cache/restore@v5
        with:
          path: ${{ runner.temp }}/hugo_cache
          key: hugo-${{ github.run_id }}
          restore-keys:
            hugo-
      - name: Build the site
        run: |
          hugo \
            --gc \
            --minify \
            --baseURL "${{ steps.pages.outputs.base_url }}/" \
            --cacheDir "${{ runner.temp }}/hugo_cache"
      - name: Cache save
        id: cache-save
        uses: actions/cache/save@v5
        with:
          path: ${{ runner.temp }}/hugo_cache
          key: ${{ steps.cache-restore.outputs.cache-primary-key }}
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

步骤 5

将更改提交到本地 Git 仓库并推送到 GitHub 仓库。

步骤 6

从 GitHub 主菜单，选择 Actions。您将看到类似的内容：

步骤 7

当 GitHub 完成构建和部署您的网站后，状态指示器的颜色将变为绿色。

步骤 8

按所示点击提交消息。在部署步骤下，您将看到指向您实时网站的链接。

将来，每当您从本地 Git 仓库推送更改时，GitHub Pages 将重新构建和部署您的网站。

自定义工作流

上面的示例工作流包括此步骤，通常需要 10-15 秒：

- name: Install Dart Sass
  run: sudo snap install dart-sass

如果您的网站、主题和模块不使用 Dart Sass 转译器将 Sass 转译为 CSS，您可以移除此步骤。

其他资源

• 了解更多关于 GitHub Actions
• 缓存依赖项以加快工作流速度
• 管理 GitHub Pages 网站的自定义域名