GitLab Pages 设置

GitLab Pages 提供了配置选项，用于自定义您的静态网站的部署和展示。 通过 Pages 设置，您可以：

• 为 403 和 404 响应提供自定义错误页面。
• 通过 _redirects 文件配置 URL 重定向。
• 使用 CI/CD 规则从任何分支部署页面。
• 提供预压缩资源以加快页面加载速度。
• 自定义网站发布的文件夹。
• 为您的网站生成和管理唯一域名。

本指南介绍了 GitLab Pages 网站可用的设置和配置选项。 有关 Pages 的介绍，请参阅 GitLab Pages。

GitLab Pages 要求

简单来说，要在 GitLab Pages 上传您的网站，您需要：

1. 实例域名：用于 GitLab Pages 的域名 （请咨询您的管理员）。
2. GitLab CI/CD：在仓库根目录中包含一个特定名称为 pages 作业的 .gitlab-ci.yml 文件。
3. 为项目启用 GitLab Runner。

GitLab.com 上的 GitLab Pages

如果您使用 GitLab.com 上的 GitLab Pages 来托管您的网站，那么：

• GitLab.com 上 GitLab Pages 的域名是 gitlab.io。
• 启用了自定义域名和 TLS 支持。
• 默认启用实例 Runner，免费提供并可用于构建您的网站。如果您愿意，仍然可以自带 Runner。

示例项目

访问 GitLab Pages 组 获取完整的示例项目列表。非常欢迎贡献。

自定义错误代码页面

您可以通过在 public/ 目录的根目录中创建 403.html 和 404.html 文件来提供您自己的 403 和 404 错误页面。这通常是您项目的根目录，但可能因您的静态生成器配置而异。

对于 404.html，存在不同的情况。例如：

• 如果您使用项目页面（在 /project-slug/ 下提供服务）并尝试访问 /project-slug/non/existing_file，GitLab Pages 会先尝试提供 /project-slug/404.html，然后是 /404.html。
• 如果您使用用户或组页面（在 / 下提供服务）并尝试访问 /non/existing_file，GitLab Pages 会尝试提供 /404.html。
• 如果您使用自定义域名并尝试访问 /non/existing_file，GitLab Pages 只会尝试提供 /404.html。

GitLab Pages 中的重定向

您可以使用 _redirects 文件为您的网站配置重定向。更多信息，请参阅 为 GitLab Pages 创建重定向。

删除 Pages 网站

永久删除项目的所有 Pages 部署。 此操作是永久性的，无法撤销。

要删除您的页面：

1. 在左侧边栏，选择 搜索或转到 并找到您的项目。
2. 选择 部署 > Pages。
3. 选择 删除页面。

您的 Pages 网站不再部署。 要再次部署此 Pages 网站，请运行新的流水线。

子域的子域

在使用 GitLab 实例的顶级域名（*.example.io）下的 Pages 时，您不能对子域的子域使用 HTTPS。如果您的命名空间或组名称包含点（例如 foo.bar），则域名 https://foo.bar.example.io 不 工作。

此限制是由于 HTTP Over TLS 协议。只要您不将 HTTP 重定向到 HTTPS，HTTP 页面就可以正常工作。

项目和组中的 GitLab Pages

您必须在项目中托管您的 GitLab Pages 网站。该项目可以是 私有、内部或公开，并属于 组 或 子组。

对于 组网站， 该组必须是顶级组，而不是子组。

对于 项目网站， 您可以先创建您的项目，然后在 http(s)://namespace.example.io/project-path 下访问它。

Pages 的特定配置选项

了解如何为特定用例设置 GitLab CI/CD。

纯 HTML 网站的 .gitlab-ci.yml

假设您的仓库包含以下文件：

├── index.html
├── css
│   └── main.css
└── js
    └── main.js

那么下面的 .gitlab-ci.yml 示例将所有文件从项目的根目录移动到 public/ 目录。.public 的解决方法是为了防止 cp 在无限循环中将 public/ 复制到自身：

create-pages:
  script:
    - mkdir .public
    - cp -r * .public
    - mv .public public
  pages: true  # 指定这是一个 Pages 作业，并发布默认的 public 目录
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

前面的 YAML 示例使用了 用户定义的作业名称。

静态站点生成器的 .gitlab-ci.yml

有关分步指南，请参阅此文档 [getting_started/pages_from_scratch.md]。

包含代码的仓库的 .gitlab-ci.yml

请记住，GitLab Pages 默认与分支/标签无关，其部署完全取决于您在 .gitlab-ci.yml 中指定的内容。您可以使用 rules:if 限制 pages 作业，每当有新提交推送到专门用于您的页面的分支时。

这样，您可以将项目的代码放在 main 分支中，并使用一个孤立分支（我们称之为 pages）来托管您的静态生成器网站。

您可以像这样创建一个新的空分支：

git checkout --orphan pages

在此新分支上进行的第一次提交没有父提交，是与其他所有分支和提交完全断开的新历史的根。将您的静态生成器的源文件推送到 pages 分支。

下面是 .gitlab-ci.yml 的副本，其中最重要的是最后一行，指定在 pages 分支中执行所有操作：

create-pages:
  image: ruby:2.6
  script:
    - gem install jekyll
    - jekyll build -d public/
  pages: true  # 指定这是一个 Pages 作业，并发布默认的 public 目录
  rules:
    - if: '$CI_COMMIT_REF_NAME == "pages"'

请参阅一个示例，其中 main 分支 中有不同的文件，而 Jekyll 的源文件在 pages 分支 中，该分支也包含 .gitlab-ci.yml。

前面的 YAML 示例使用了 用户定义的作业名称。

提供压缩资源

大多数现代浏览器支持以压缩格式下载文件。这通过减小文件大小来加快下载速度。

在提供未压缩文件之前，Pages 会检查是否存在具有 .br 或 .gz 扩展名的相同文件。如果存在，并且浏览器支持接收压缩文件，它将提供该版本而不是未压缩版本。

要利用此功能，您上传到 Pages 的工件应具有以下结构：

public/
├─┬ index.html
│ | index.html.br
│ └ index.html.gz
│
├── css/
│   └─┬ main.css
│     | main.css.br
│     └ main.css.gz
│
└── js/
    └─┬ main.js
      | main.js.br
      └ main.js.gz

这可以通过在您的 .gitlab-ci.yml pages 作业中包含一个 script: 命令来实现：

create-pages:
  # 其他指令
  script:
    # 首先构建 public/ 目录
    - find public -type f -regex '.*\.\(htm\|html\|xml\|txt\|text\|js\|css\|svg\)$' -exec gzip -f -k {} \;
    - find public -type f -regex '.*\.\(htm\|html\|xml\|txt\|text\|js\|css\|svg\)$' -exec brotli -f -k {} \;
  pages: true  # 指定这是一个 Pages 作业

通过预压缩文件并在工件中包含两个版本，Pages 可以在需要时为压缩和未压缩内容提供服务，而无需按需压缩文件。

前面的 YAML 示例使用了 用户定义的作业名称。

解析模糊的 URL

当接收到不包含扩展名的 URL 请求时，GitLab Pages 会假设要提供哪些文件。

考虑使用以下文件部署的 Pages 网站：

public/
├── index.html
├── data.html
├── info.html
├── data/
│   └── index.html
└── info/
    └── details.html

Pages 支持通过几种不同的 URL 访问这些文件。特别是，如果 URL 仅指定目录，它总是查找 index.html 文件。如果 URL 引用了不存在的文件，但向 URL 添加 .html 后存在该文件，则提供该文件。以下是给定前面 Pages 网站时发生情况的示例：

当 public/data/index.html 存在时，对于 /data 和 /data/ URL 路径，它优先于 public/data.html 文件。

自定义默认文件夹

默认情况下，Pages 在您的构建文件中查找名为 public 的文件夹来发布它。

要将该文件夹名称更改为任何其他值，请在 .gitlab-ci.yml 中的 deploy-pages 作业配置中添加一个 pages.publish 属性。

以下示例发布一个名为 dist 的文件夹：

create-pages:
  script:
    - npm run build
  pages:  # 指定这是一个 Pages 作业
    publish: dist

前面的 YAML 示例使用了 用户定义的作业名称。

要在 pages.publish 字段中使用变量，请参阅 pages.publish。

Pages 使用工件来存储您网站的文件，因此 pages.publish 的值会自动追加到 artifacts:paths。前面的示例等效于：

create-pages:
  script:
    - npm run build
  pages:
    publish: dist
  artifacts:
    paths:
      - dist

重新生成 GitLab Pages 的唯一域名

您可以重新生成 GitLab Pages 网站的唯一域名。

重新生成域名后，之前的 URL 不再有效。 如果有人尝试访问旧 URL，他们将收到 404 错误。

先决条件

• 您必须至少拥有项目的 Maintainer 角色。
• 使用唯一域名 设置 必须启用 在您项目的 Pages 设置中。

要为您的 GitLab Pages 网站重新生成唯一域名：

1. 在左侧边栏，选择 部署 > Pages。
2. 在 访问页面 旁边，按 重新生成唯一域名。
3. GitLab 为您的 Pages 网站生成一个新的唯一域名。

已知问题

有关已知问题列表，请参阅 GitLab 公共问题跟踪器。

故障排除

访问 GitLab Pages 网站 URL 时出现 404 错误

此问题很可能是因为 public 目录中缺少 index.html 文件。如果在部署 Pages 网站后遇到 404 错误，请确认 public 目录包含 index.html 文件。如果文件包含不同的名称，如 test.html，Pages 网站仍然可以访问，但需要完整路径。例如：https//group-name.pages.example.com/project-slug/test.html。

可以通过 浏览最新流水线的工件 来确认 public 目录的内容。

public 目录下列出的文件可以通过项目的 Pages URL 访问。

404 错误也可能与不正确的权限有关。如果启用了 Pages 访问控制，并且用户访问 Pages URL 时收到 404 响应，可能是该用户没有查看网站的权限。要解决此问题，请验证该用户是否是项目的成员。

损坏的相对链接

GitLab Pages 支持无扩展名的 URL。然而，由于 问题 #354 中描述的问题，如果无扩展名的 URL 以正斜杠（/）结尾，它会破坏页面上的任何相对链接。

要解决此问题：

• 确保指向您 Pages 网站的任何 URL 都有扩展名，或者不包含尾部斜杠。
• 如果可能，在您的网站上仅使用绝对 URL。

无法在 Safari 上播放媒体内容

Safari 要求 Web 服务器支持 Range 请求头 来播放您的媒体内容。要让 GitLab Pages 提供 HTTP Range 请求，您应该在 .gitlab-ci.yml 文件中使用以下两个变量：

create-pages:
  stage: deploy
  variables:
    FF_USE_FASTZIP: "true"
    ARTIFACT_COMPRESSION_LEVEL: "fastest"
  script:
    - echo "Deploying pages"
  pages: true  # 指定这是一个 Pages 作业，并发布默认的 public 目录
  environment: production

FF_USE_FASTZIP 变量启用了所需的 功能标志，该标志是 ARTIFACT_COMPRESSION_LEVEL 所需的。

前面的 YAML 示例使用了 用户定义的作业名称。

在多个浏览器选项卡中访问私有 GitLab Pages 网站时出现 401 错误

当您尝试在没有预先认证的情况下同时在两个不同的选项卡中访问私有 Pages URL 时，每个选项卡会返回两个不同的 state 值。 然而，在 Pages 会话中，只为给定客户端存储最新的 state 值。 因此，提交凭据后，其中一个选项卡返回 401 Unauthorized 错误。

要解决 401 错误，请刷新页面。

pages:deploy 作业失败

要使用 GitLab Pages 部署，根内容目录必须包含一个非空的 index.html 文件，否则 pages:deploy 作业将失败。

内容目录默认为 public/，或者在您的 .gitlab-ci.yml 文件中使用 pages.publish 关键字指定的目录。