Help us learn about your current experience with the documentation. Take the survey.

教程：使用 GitLab 构建、测试和部署您的 Hugo 网站

本教程将指导您创建一个 CI/CD 管道，用于构建、测试和部署 Hugo 网站。

完成本教程后，您将拥有一个可用的管道和一个部署在 GitLab Pages 上的 Hugo 网站。

以下是您将要完成的任务概览：

  1. 准备您的 Hugo 网站。
  2. 创建一个 GitLab 项目。
  3. 将您的 Hugo 网站推送到 GitLab。
  4. 使用 CI/CD 管道构建您的 Hugo 网站。
  5. 使用 GitLab Pages 部署您的 Hugo 网站。

开始之前

  • 一个 GitLab.com 账户。
  • 熟悉 Git。
  • 一个 Hugo 网站（如果您还没有，可以遵循 Hugo 快速入门）。

准备您的 Hugo 网站

首先，确保您的 Hugo 网站已准备好推送到 GitLab。您需要拥有内容、主题和 Hugo 配置文件。

不要构建您的网站，因为 GitLab 会为您完成。实际上，不要上传您的 public 文件夹，因为这可能会导致后续冲突。

排除 public 文件夹的最简单方法是创建一个 .gitignore 文件，并添加一行 public/ 作为文本。

您可以在 Hugo 项目的顶层使用以下命令执行此操作：

echo "public/" >> .gitignore

这会将 public/ 添加到新的 .gitignore 文件中，或追加到现有文件中。

好的，在创建 GitLab 项目后，您的 Hugo 网站已准备好推送。

创建 GitLab 项目

如果您尚未完成，请为您的 Hugo 网站创建一个空的 GitLab 项目。

要在 GitLab 中创建空白项目：

  1. 在左侧边栏顶部，选择 新建 ( plus ) 和 新建项目/仓库。
  2. 选择 创建空白项目。
  3. 输入项目详情：
    • 在 项目名称 字段中，输入您的项目名称。名称必须以小写或大写字母（a-zA-Z）、数字（0-9）、表情符号或下划线（_）开头。它还可以包含点（.）、加号（+）、连字符（-）或空格。
    • 在 项目标识符 字段中，输入您的项目路径。GitLab 实例使用标识符作为项目的 URL 路径。要更改标识符，首先输入项目名称，然后更改标识符。
    • 可见性级别 可以是私有或公开。如果您选择私有，您的网站仍然可以公开访问，但您的代码保持私有。
    • 因为您正在推送现有仓库，请清除 使用 README 初始化仓库 复选框。
  4. 准备好后，选择 创建项目。
  5. 您应该会看到将代码推送到此新项目的说明。您在下一步中需要这些说明。

现在您的 Hugo 网站有了家！

将您的 Hugo 网站推送到 GitLab

接下来，您需要将本地的 Hugo 网站推送到远程的 GitLab 项目。

如果您在上一步中创建了新的 GitLab 项目，您将看到初始化仓库、提交和推送文件的说明。

否则，请确保本地 Git 仓库的远程源与您的 GitLab 项目匹配。

假设您的默认分支是 main，您可以使用以下命令推送您的 Hugo 网站：

git push origin main

推送您的网站后，您应该会看到除 public 文件夹外的所有内容。public 文件夹被 .gitignore 文件排除了。

在下一步中，您将使用 CI/CD 管道构建您的网站并重新创建该 public 文件夹。

使用 CI/CD 管道构建您的 Hugo 网站

要使用 GitLab 构建 Hugo 网站，您首先需要创建一个 .gitlab-ci.yml 文件来指定 CI/CD 管道的说明。如果您以前没有做过，这听起来可能令人望而生畏。但是，GitLab 提供了您所需的一切。

要使用下面显示的 .gitlab-ci.yml 文件，请确保您的 hugo.toml 文件也指示匹配的主题路径。下面的示例 hugo.toml 文件还显示了 GitLab Pages 项目的 baseURL 设置。

baseURL = 'https://<your-namespace>.gitlab.io/<project-path>'
languageCode = 'en-us'
title = 'Hugo on GitLab'
[module]
[[module.imports]]
  path = 'github.com/adityatelange/hugo-PaperMod'

添加您的 GitLab 配置选项

您在名为 .gitlab-ci.yml 的特殊文件中指定您的配置选项。

要使用 Hugo 模板创建 .gitlab-ci.yml 文件：

  1. 在左侧边栏，选择 代码 > 仓库。
  2. 在文件列表上方，选择加号图标（ + ），然后从下拉列表中选择 新建文件。
  3. 对于文件名，输入 .gitlab-ci.yml。不要省略开头的句点。
  4. 选择 应用模板 下拉列表，然后在筛选框中输入 “Hugo”。
  5. 选择结果 Hugo，您的文件将填充使用 CI/CD 构建 Hugo 网站所需的所有代码。

让我们更仔细地看看这个 .gitlab-ci.yml 文件中发生了什么。

default:
  image: "hugomods/hugo:exts"

variables:
  GIT_SUBMODULE_STRATEGY: recursive
  THEME_URL: "github.com/adityatelange/hugo-PaperMod"

test:  # 构建并测试您的网站
  script:
    - hugo
  rules:
    - if: $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH

create-pages:  # 一个用户定义的作业，用于构建您的页面并将其保存到指定路径。
  script:
    - hugo
  pages: true  # 指定这是一个 Pages 作业
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  environment: production
  • image 指定来自 GitLab Registry 的包含 Hugo 的镜像。此镜像用于创建构建您的网站的环境。
  • GIT_SUBMODULE_STRATEGY 变量确保 GitLab 也查看您的 Git 子模块，这些子模块有时用于 Hugo 主题。
  • test 是一个作业，您可以在部署 Hugo 网站之前对其运行测试。测试作业在所有情况下都会运行，除非您正在向默认分支提交更改。您将任何命令放在 script 下。此作业中的命令 - hugo- 构建您的网站以便进行测试。
  • deploy-pages 是用于从静态站点生成器创建页面的用户定义作业。同样，此作业使用 用户定义的作业名称 并运行 hugo 命令来构建您的网站。然后 pages: true 指定这是一个 Pages 作业，artifacts 指定将生成的页面添加到名为 public 的目录中。通过 rules，您正在检查此提交是否在默认分支上完成。通常，您不希望从另一个分支构建和部署实时网站。

您无需向此文件添加任何其他内容。准备好后，选择页面顶部的 提交更改。

您刚刚触发了一个构建您的 Hugo 网站的管道！

使用 GitLab Pages 部署您的 Hugo 网站

如果您动作快，可以看到 GitLab 构建和部署您的网站。

从左侧导航，选择 构建 > 管道。

您会看到 GitLab 运行了您的 test 和 deploy-pages 作业。

要查看您的网站，当管道完成后，在左侧导航中选择 部署 > Pages 以找到您 Pages 网站的链接。

添加您的 Hugo 配置选项

当您第一次查看您的 Hugo 网站时，样式表将无法工作。别担心，您需要在 Hugo 配置文件中进行一些小更改。Hugo 需要知道您的 GitLab Pages 网站的 URL，以便它可以构建指向样式表和其他资源的相对链接：

  1. 在您的本地 Hugo 网站中，拉取最新的更改，并打开您的 config.yaml 或 config.toml 文件。
  2. 更改 BaseURL 参数的值以匹配您的 GitLab Pages 设置中显示的 URL。
  3. 将更改后的文件推送到 GitLab，您的管道将再次触发。

查找您的 GitLab Pages URL

当管道完成后，转到 部署 > Pages 以找到您 Pages 网站的链接。

您管道中的 pages 作业已将 public 目录的内容部署到 GitLab Pages。在 访问 Pages 下，您应该看到格式的链接：https://<your-namespace>.gitlab.io/<project-path>。

如果您尚未运行管道，您将看不到此链接。

选择显示的链接以查看您的网站。您需要更改 Hugo 配置中的 BaseURL 设置以匹配 GitLab 部署 URL。

设置您的 GitLab Pages 可见性

如果您的 Hugo 网站存储在私有仓库中，您需要更改权限以便 Pages 网站可见。否则，它仅对项目成员可见。要更改网站权限：

  1. 转到 设置 > 常规 > 可见性，项目功能，权限。
  2. 向下滚动到 Pages 部分，并从下拉列表中选择 所有人。
  3. 选择 保存更改。

现在每个人都可以在 URL 上看到该网站。

您已经使用 GitLab 构建了、测试并部署了您的 Hugo 网站。干得好！

每次您更改网站并将其推送到 GitLab 时，您的网站都会使用 .gitlab-ci.yml 文件中的规则自动构建、测试和部署。

要了解更多关于 CI/CD 管道的信息，请尝试 这个关于如何创建复杂管道的教程。您还可以了解更多关于 可用的不同类型测试。