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

教程：从零开始创建 GitLab Pages 网站

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

本教程教你如何使用 Jekyll 静态站点生成器（SSG）从零开始创建 Pages 网站。你从一个空白项目开始，创建自己的 CI/CD 配置文件，该文件向 runner 提供指令。当你的 CI/CD pipeline 运行时，Pages 网站就会被创建。

本示例使用 Jekyll，但其他 SSG 遵循类似的步骤。完成本教程不需要熟悉 Jekyll 或 SSG。

要创建 GitLab Pages 网站：

前置条件

你必须在 GitLab 中有一个 空白项目。

创建项目文件

在根目录（顶级目录）中创建三个文件：

  • .gitlab-ci.yml：一个包含你想要运行的命令的 YAML 文件。目前，保持文件内容为空。

  • index.html：一个非空的 HTML 文件，你可以用任何你喜欢的 HTML 内容填充它，例如：

    <html>
<head>
  <title>Home</title>
</head>
<body>
  <h1>Hello World!</h1>
</body>
</html>

  • Gemfile：一个描述 Ruby 程序依赖项的文件。

    用以下内容填充它：

    source "https://rubygems.org"

gem "jekyll"

选择 Docker 镜像

在本示例中，runner 使用 Docker image 来运行脚本和部署站点。

这个特定的 Ruby 镜像在 DockerHub 上维护。

通过将此 CI/CD 配置添加到 .gitlab-ci.yml 文件的开头，为你的 pipeline 添加默认镜像：

default:
  image: ruby:3.2

如果你的 SSG 需要 NodeJS 来构建，你必须指定一个包含 NodeJS 作为其文件系统一部分的镜像。例如，对于 Hexo 网站，你可以使用 image: node:12.17.0。

安装 Jekyll

要在本地运行 Jekyll，你必须安装它：

  1. 打开你的终端。
  2. 通过运行 gem install bundler 安装 Bundler。
  3. 通过运行 bundle install 创建 Gemfile.lock。
  4. 通过运行 bundle exec jekyll build 安装 Jekyll。

要在你的项目中运行 Jekyll，编辑 .gitlab-ci.yml 文件并添加安装命令：

script:
  - gem install bundler
  - bundle install
  - bundle exec jekyll build

此外，在 .gitlab-ci.yml 文件中，每个 script 都由一个 job 组织。一个 job 包含你想要应用于该特定任务的脚本和设置。

job:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build

对于 GitLab Pages，这个 job 必须包含一个名为 pages 的属性。这个设置告诉 runner 你希望该 job 使用 GitLab Pages 部署你的网站：

create-pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build
  pages: true  # specifies that this is a Pages job

本页面的示例使用 用户定义的作业名称。

指定输出的 public 目录

Jekyll 需要知道在哪里生成其输出。GitLab Pages 只考虑名为 public 的目录中的文件。

Jekyll 使用目标标志 (-d) 来指定构建网站的输出目录。将目标添加到你的 .gitlab-ci.yml 文件中：

create-pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  pages: true  # specifies that this is a Pages job

指定 artifacts 的 public 目录

现在 Jekyll 已经将文件输出到 public 目录，runner 需要知道从哪里获取它们。在 GitLab 17.10 及更高版本中，仅对于 Pages 作业，当未明确指定 pages.publish 路径时，public 目录会自动附加到 artifacts:paths：

create-pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  pages: true  # specifies that this is a Pages job and publishes the default public directory

你的 .gitlab-ci.yml 文件现在应该如下所示：

default:
  image: ruby:3.2

create-pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  pages: true  # specifies that this is a Pages job and publishes the default public directory

部署并查看你的网站

完成上述步骤后，部署你的网站：

  1. 保存并提交 .gitlab-ci.yml 文件。
  2. 转到 Build > Pipelines 查看 pipeline。
  3. 当 pipeline 完成后，转到 Deploy > Pages 找到你的 Pages 网站的链接。

当这个 pages job 成功完成时，一个特殊的 pages:deploy job 会在 pipeline 视图中出现。它为 GitLab Pages 守护进程准备网站内容。GitLab 在后台运行它，不使用 runner。

CI/CD 文件的其他选项

如果你想执行更高级的任务，可以使用 其他 CI/CD YAML 关键字 更新你的 .gitlab-ci.yml 文件。你可以使用 GitLab 附带的 CI Lint 工具验证你的 .gitlab-ci.yml 文件。

以下主题展示了你可以添加到 CI/CD 文件的其他选项的其他示例。

将特定分支部署到 Pages 网站

你可能只想从特定分支部署到 Pages 网站。

首先，添加一个 workflow 部分，强制 pipeline 仅在更改推送到分支时运行：

default:
  image: ruby:3.2

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

create-pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  pages: true  # specifies that this is a Pages job and publishes the default public directory

然后配置 pipeline 仅对 默认分支（这里是 main）运行 job。

default:
  image: ruby:3.2

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

create-pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  pages: true  # specifies that this is a Pages job and publishes the default public directory
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

指定部署的阶段

GitLab CI/CD 有三个默认阶段：build、test 和 deploy。

如果你想在部署到生产环境之前测试脚本并检查构建的站点，可以像推送到 默认分支（这里是 main）时一样运行测试。

要指定你的 job 运行的阶段，向你的 CI 文件添加一个 stage 行：

default:
  image: ruby:3.2

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

create-pages:
  stage: deploy
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  pages: true  # specifies that this is a Pages job and publishes the default public directory
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  environment: production

现在向 CI 文件添加另一个 job，告诉它测试除 main 分支外的每个分支的每次推送：

default:
  image: ruby:3.2

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

create-pages:
  stage: deploy
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  pages: true  # specifies that this is a Pages job and publishes the default public directory
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  environment: production

test:
  stage: test
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d test
  artifacts:
    paths:
      - test
  rules:
    - if: $CI_COMMIT_BRANCH != "main"

当 test job 在 test 阶段运行时，Jekyll 在名为 test 的目录中构建站点。该 job 影响除 main 外的所有分支。

当你将阶段应用于不同的 job 时，同一阶段中的每个 job 都会并行构建。如果你的 Web 应用程序在部署前需要多个测试，可以同时运行所有测试。

删除重复命令

为了避免在每个 job 中重复相同的 before_script 命令，可以将它们添加到默认部分。

在示例中，gem install bundler 和 bundle install 都在运行，适用于 pages 和 test 两个 job。

将这些命令移动到 default 部分：

default:
  image: ruby:3.2
  before_script:
    - gem install bundler
    - bundle install

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

create-pages:
  stage: deploy
  script:
    - bundle exec jekyll build -d public
  pages: true  # specifies that this is a Pages job and publishes the default public directory
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  environment: production

test:
  stage: test
  script:
    - bundle exec jekyll build -d test
  artifacts:
    paths:
      - test
  rules:
    - if: $CI_COMMIT_BRANCH != "main"

使用缓存的依赖项构建更快

为了更快地构建，可以使用 cache 参数缓存项目依赖项的安装文件。

此示例在运行 bundle install 时将 Jekyll 依赖项缓存在 vendor 目录中：

default:
  image: ruby:3.2
  before_script:
    - gem install bundler
    - bundle install --path vendor
  cache:
    paths:
      - vendor/

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH


create-pages:
  stage: deploy
  script:
    - bundle exec jekyll build -d public
  pages: true  # specifies that this is a Pages job and publishes the default public directory
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  environment: production

test:
  stage: test
  script:
    - bundle exec jekyll build -d test
  artifacts:
    paths:
      - test
  rules:
    - if: $CI_COMMIT_BRANCH != "main"

在这种情况下，你需要从 Jekyll 构建的文件夹列表中排除 /vendor 目录。否则，Jekyll 会尝试构建目录内容以及站点。

在根目录中，创建一个名为 _config.yml 的文件并添加以下内容：

exclude:
  - vendor

现在 GitLab CI/CD 不仅构建网站，还：

  • 向功能分支推送 连续测试。
  • 缓存 使用 Bundler 安装的依赖项。
  • 连续部署 每次推送到 main 分支。

要查看为站点创建的 HTML 和其他资源，下载 job artifacts。

本页面的示例使用 用户定义的作业名称。

相关主题