• 极狐GitLab Pages 要求
• 自定义错误码 Pages
• 重定向
• Pages 访问控制
• 取消发布
• 子域名的子域名
• 极狐GitLab Pages 和子组
• Pages 的特定配置选项
  • .gitlab-ci.yml 用于纯 HTML 网站
  • .gitlab-ci.yml 用于静态站点生成器
  • .gitlab-ci.yml 用于包含实际代码的仓库
  • 提供压缩的 assets
  • 解析不明确的 URL
• 常见问题
  • 能下载生成的页面吗？
  • 如果项目是私有的，可以使用极狐GitLab Pages 吗？
  • 可以创建个人或群组网站吗？
  • 在创建项目网站之前是否需要创建用户/群组网站？
• 故障排除
  • 访问 Pages 站点 URL 时出现 404 错误
  • 无法在 Safari 上播放媒体内容

探索极狐GitLab Pages

本文档是探索极狐GitLab Pages 提供的选项和设置的用户指南。

极狐GitLab Pages 要求

简而言之，以下是您在极狐GitLab Pages 中上传网站所需的内容：

1. 实例的域名：用于 Pages 的域名（询问您的管理员）。
2. 极狐GitLab CI/CD：一个 .gitlab-ci.yml 文件，在您的仓库的根目录中有一个名为 pages 的特定作业。
3. 站点仓库中名为 public 的目录，其中包含要发布的内容。
4. 为项目启用了极狐GitLab Runner。

自定义错误码 Pages

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

如果是 404.html 的情况，有不同的场景。例如：

• 如果您使用项目 Pages（在 /projectname/ 下提供），并尝试访问 /projectname/non/existing_file，Pages 会尝试首先提供 /projectname/404.html，然后是 /404.html。
• 如果您使用用户/群组 Pages（在 / 下提供）并尝试访问 /non/existing_file，Pages 会尝试提供 /404.html。
• 如果您使用自定义域名并尝试访问 /non/existing_file，Pages 仅尝试提供 /404.html。

重定向

您可以使用 _redirects 文件为您的站点配置重定向。要了解更多信息，请阅读重定向文档。

Pages 访问控制

要限制对您网站的访问，请启用 Pages 访问控制。

取消发布

如果您觉得需要清除 Pages 内容，可以通过右上角的齿轮图标转到项目设置，然后导航到 Pages。选择 删除页面 按钮，删除您的 Pages 网站。

子域名的子域名

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

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

极狐GitLab Pages 和子组

您必须在项目中托管您的 Pages 网站。该项目可以属于群组或子组。对于群组网站，群组必须位于顶层，不可以是子组。

Pages 的特定配置选项

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

.gitlab-ci.yml 用于纯 HTML 网站

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

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

然后下面的 .gitlab-ci.yml 示例简单地将所有文件从项目的根目录移动到 public/ 目录。.public 的解决方法是，cp 不会在无限循环中将 public/ 复制到自身：

pages:
  script:
    - mkdir .public
    - cp -r * .public
    - mv .public public
  artifacts:
    paths:
      - public
  only:
    - main

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

.gitlab-ci.yml 用于包含实际代码的仓库

请记住，Pages 默认情况下与分支/标签无关，它们的部署仅依赖于您在 .gitlab-ci.yml 中指定的内容。每当新的提交被推送到专门用于您的页面的分支时，您可以使用 only 参数 限制 pages 作业。

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

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

git checkout --orphan pages

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

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

image: ruby:2.6

pages:
  script:
    - gem install jekyll
    - jekyll build -d public/
  artifacts:
    paths:
      - public
  only:
    - pages

提供压缩的 assets

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

在提供未压缩文件之前，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 页面作业中包含这样的 script: 命令来实现：

pages:
  # Other directives
  script:
    # Build the public/ directory first
    - find public -type f -regex '.*\.\(htm\|html\|txt\|text\|js\|css\)$' -exec gzip -f -k {} \;
    - find public -type f -regex '.*\.\(htm\|html\|txt\|text\|js\|css\)$' -exec brotli -f -k {} \;

通过预压缩文件并在产物中包含这两个版本，Pages 可以为压缩和未压缩内容的请求提供服务，而无需按需压缩文件。

解析不明确的 URL

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

例如使用以下文件部署的 Pages 站点：

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

Pages 支持通过多个不同的 URL 访问这些文件中的每一个。特别是，如果 URL 仅指定目录，它总是会查找 index.html 文件。如果 URL 引用了一个不存在的文件，但将 .html 添加到 URL 会导致文件确实存在，则它会被提供。以下是给定上述 Pages 网站的一些示例：

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

常见问题

能下载生成的页面吗？

当然。您需要做的就是从作业页面下载产物存档。

如果项目是私有的，可以使用极狐GitLab Pages 吗？

是的。极狐GitLab Pages 不关心您将项目的可见性级别设置为私有、内部或公开。

可以创建个人或群组网站吗？

是的。

在创建项目网站之前是否需要创建用户/群组网站？

不。您可以先创建您的项目并在 http(s)://namespace.example.io/projectname 下面访问它。

故障排除

访问 Pages 站点 URL 时出现 404 错误

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

Public 目录的内容可以通过从最新的流水线中浏览产物来确认。

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

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

无法在 Safari 上播放媒体内容

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

pages:
  stage: deploy
  variables:
    FF_USE_FASTZIP: "true"
    ARTIFACT_COMPRESSION_LEVEL: "fastest"
  script:
    - echo "Deploying pages"
  artifacts:
    paths:
      - public
  environment: production

FF_USE_FASTZIP 变量启用了 ARTIFACT_COMPRESSION_LEVEL。