# 将自定义工作流与 GitHub Pages 配合使用

您可以通过创建工作流文件或从预定义的工作流中进行选择，来利用 GitHub Actions 和 GitHub Pages。

## 关于自定义工作流

自定义工作流支持通过使用 GitHub Pages 构建 GitHub Actions 站点。 你仍然可以通过工作流文件选择要使用的分支，但使用自定义工作流可以执行更多操作。 若要开始使用自定义工作流，必须先为当前存储库启用它们。 有关详细信息，请参阅“[为您的 GitHub Pages 网站配置发布源](/zh/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow)”。

## 配置 `configure-pages` 操作

GitHub Actions 可通过 GitHub Pages 操作使用 `configure-pages`，该操作还允许收集有关网站的各种元数据。 有关详细信息，请参阅 [`configure-pages`](https://github.com/marketplace/actions/configure-github-pages) 操作。

若要使用此操作，请将此代码片段放在所需工作流的 `jobs` 下。

```yaml
- name: Configure GitHub Pages
  uses: actions/configure-pages@v5
```

此操作有助于支持从任何静态站点生成器到 GitHub Pages的部署。 若要减少此过程的重复性，可以对一些最广泛使用的静态站点生成器使用工作流模板。 有关详细信息，请参阅“[使用工作流模板](/zh/actions/how-tos/write-workflows/use-workflow-templates)”。

## 配置 `upload-pages-artifact` 操作

通过 `upload-pages-artifact` 操作可以打包和上传项目。
GitHub Pages构件应为一个压缩的`gzip`归档文件，其中包含单个`tar`文件。
`tar` 文件大小必须低于 10 GB，并且不应包含任何符号或硬链接。 有关详细信息，请参阅 [`upload-pages-artifact`](https://github.com/marketplace/actions/upload-github-pages-artifact) 操作。

若要在当前工作流中使用此操作，请将此代码片段放在 `jobs` 下。

```yaml
- name: Upload GitHub Pages artifact
  uses: actions/upload-pages-artifact@v4
```

## 部署 GitHub Pages 构件

`deploy-pages` 操作处理部署构件所需的设置。 为确保功能正常运行，应满足以下要求：

* 作业必须至少具有 `pages: write` 和 `id-token: write` 权限。
* `needs` 参数必须设置为生成步骤的 `id`。 不设置此参数可能会导致独立部署持续搜索尚未创建的项目。
* 必须建立 `environment` 以强制实施分支/部署保护规则。 默认环境为 `github-pages`。
* 若要将页面的 URL 指定为输出，请使用 `url:` 字段。

有关详细信息，请参阅 [`deploy-pages`](https://github.com/marketplace/actions/deploy-github-pages-site) 操作。

```yaml
# ...

jobs:
  deploy:
    permissions:
      contents: read
      pages: write
      id-token: write
    runs-on: ubuntu-latest
    needs: jekyll-build
    environment:
      name: github-pages
      url: ${{steps.deployment.outputs.page_url}}
    steps:
      - name: Deploy artifact
        id: deployment
        uses: actions/deploy-pages@v4
# ...
```

## 连接单独的构建和部署任务

可以在单个工作流文件中链接 `build` 和 `deploy` 作业，无需创建两个单独的文件即可获得相同的结果。 若要开始使用工作流文件，可以在 `jobs` 下定义 `build` 和 `deploy` 作业以执行作业。

```yaml
# ...

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5
      - name: Build with Jekyll
        uses: actions/jekyll-build-pages@v1
        with:
          source: ./
          destination: ./_site
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v4

  # Deployment job
  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
# ...
```

在某些情况下，可以选择将所有内容合并到单个作业中，尤其是在不需要生成过程的情况下。 因此，将只专注于部署步骤。

```yaml
# ...

jobs:
  # Single deploy job no building
  deploy:
    environment:
      name: github-pages
      url: ${{steps.deployment.outputs.page_url}}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload Artifact
        uses: actions/upload-pages-artifact@v4
        with:
          # upload entire directory
          path: '.'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

# ...
```

可以将作业定义为在不同的运行器上按顺序或并行运行。 有关详细信息，请参阅“[选择工作流执行的操作](/zh/actions/how-tos/write-workflows/choose-what-workflows-do)”。