GitLab Pages 重定向

在 GitLab Pages 中，你可以配置规则，使用 Netlify 风格 的 HTTP 重定向将一个 URL 转发到另一个 URL。

并非所有 Netlify 提供的特殊选项 都受支持。

创建重定向规则

要创建重定向规则，请在 GitLab Pages 站点的 public/ 目录中创建一个名为 _redirects 的配置文件。

• 所有路径必须以正斜杠 / 开头。

• 如果未提供 状态码，则默认应用 301 状态码。

• _redirects 文件有文件大小限制和每个项目的最大规则数，在实例级别配置。只处理配置的最大值内的第一个匹配规则。 默认文件大小限制为 64 KB，默认最大规则数为 1,000。

• 如果你的 GitLab Pages 站点使用默认域名（如 namespace.gitlab.io/project-slug），你必须为每条规则添加路径前缀：

  /project-slug/wardrobe.html /project-slug/narnia.html 302

• 如果你的 GitLab Pages 站点使用 自定义域名， 则不需要项目路径前缀。例如，如果你的自定义域名是 example.com， 你的 _redirects 文件看起来像这样：

  /wardrobe.html /narnia.html 302

文件优先于重定向

文件的优先级高于重定向。如果磁盘上存在文件，GitLab Pages 会 直接提供该文件，而不是执行重定向。例如，如果存在 hello.html 和 world.html 文件，并且 _redirects 文件包含以下行，则重定向 会被忽略，因为 hello.html 存在：

/project-slug/hello.html /project-slug/world.html 302

GitLab 不支持 Netlify 的 强制选项 来改变此行为。

HTTP 状态码

如果未提供状态码，则默认应用 301 状态码，但 你可以明确设置自己的状态码。支持以下 HTTP 状态码：

• 301: 永久重定向。
• 302: 临时重定向。
• 200: 成功 HTTP 请求的标准响应。如果 to 规则中的内容存在， Pages 会提供该内容，且不更改地址栏中的 URL。

重定向

要创建重定向，添加一个包含 from 路径、to 路径和 HTTP 状态码 的规则：

# 301 永久重定向
/old/file.html /new/file.html 301

# 302 临时重定向
/old/another_file.html /new/another_file.html 302

重写

当请求匹配 from 时，提供 200 状态码来提供 to 路径的内容：

/old/file.html /new/file.html 200

此状态码可以与 通配符规则 结合使用，动态重写 URL。

域名级重定向

要创建域名级重定向，将域名级路径（以 http:// 或 https:// 开头）添加到以下任一位置：

• 仅 to 路径。
• from 和 to 路径。

支持的 HTTP 状态码 是 301 和 302：

# 301 永久重定向
http://blog.example.com/file_1.html https://www.example.com/blog/file_1.html 301
/file_2.html https://www.example.com/blog/file_2.html 301

# 302 临时重定向
http://blog.example.com/file_3.html https://www.example.com/blog/file_3.html 302
/file_4.html https://www.example.com/blog/file_4.html 302

域名级重定向可以与 通配符规则（包括通配符占位符）结合使用，动态重写 URL 路径。

通配符

在 from 路径中包含星号（*）的规则称为通配符，它匹配 请求路径的开头、中间或结尾的任何内容。此示例 匹配 /old/ 之后的所有内容，并将其重写为 /new/file.html：

/old/* /new/file.html 200

通配符占位符

规则 from 路径中的 * 匹配的内容可以使用 :splat 占位符注入到 to 路径中：

/old/* /new/:splat 200

在此示例中，对 /old/file.html 的请求会以 200 状态码提供 /new/file.html 的内容。

如果规则的 from 路径包含多个通配符，第一个通配符匹配的值会替换 to 路径中的任何 :splat。

通配符匹配行为

通配符是"贪婪的"，尽可能多地匹配字符：

/old/*/file /new/:splat/file 301

在此示例中，规则将 /old/a/b/c/file 重定向到 /new/a/b/c/file。

通配符也匹配空字符串，因此前面的规则会将 /old/file 重定向到 /new/file。

将所有请求重写到根 index.html

单页应用程序 (SPAs) 通常使用客户端路由执行自己的路由。 对于这些应用程序，将所有请求重写到根 index.html，以便路由逻辑可以由 JavaScript 应用程序处理。

先决条件：

• 如果你使用 GitLab Pages 与 Let’s Encrypt 的集成， 在添加此规则之前必须启用它。否则，重定向会破坏 Let’s Encrypt 集成。更多详细信息，请参阅 GitLab Pages 问题 649。

要将请求重写到 index.html：

1. 添加此 _redirects 规则：

   /* /index.html 200

2. 要使你的单页应用程序与并行部署一起工作，请编辑重定向规则以 包含路径前缀：

   /project/base/<prefix>/* /project/base/<prefix>/index.html 200

   将 <prefix> 替换为你的路径前缀值。

占位符

在规则中使用占位符来匹配请求 URL 的部分，并在重写或 重定向到新 URL 时使用这些匹配项。

占位符的格式为 : 字符后跟一串字母 （[a-zA-Z]+），在 from 和 to 路径中：

/news/:year/:month/:date/:slug /blog/:year-:month-:date-:slug 200

此规则指示 Pages 通过提供 /blog/2021-08-12-file.html 的内容 来响应 /news/2021/08/12/file.html 的请求，状态码为 200。

占位符匹配行为

与 通配符 相比，占位符在匹配内容方面更加有限。占位符匹配正斜杠 （/）之间的文本，因此使用占位符来匹配单个路径段。

此外，占位符不匹配空字符串。像这样的规则 不会 匹配 /old/file 这样的请求 URL：

/old/:path /new/:path

调试重定向规则

如果重定向未按预期工作，或者你想检查重定向语法，请访问 [你的页面 URL]/_redirects。_redirects 文件不会直接提供，但你的浏览器 会显示你的重定向规则的编号列表，以及规则是否有效或无效：

11 条规则
规则 1: 有效
规则 2: 有效
规则 3: 错误：不支持通配符
规则 4: 有效
规则 5: 错误：不支持占位符
规则 6: 有效
规则 7: 错误：不支持到外部网站的域名级重定向
规则 8: 错误：URL 路径必须以正斜杠 / 开头
规则 9: 错误：不支持到外部网站的域名级重定向
规则 10: 有效
规则 11: 有效

与 Netlify 实现的差异

大多数受支持的 _redirects 规则在 GitLab 和 Netlify 中的行为相同。 但是，存在一些细微差异：

• 所有规则 URL 必须以斜杠开头：

  Netlify 不要求 URL 以正斜杠开头：

  # 在 Netlify 中有效，在 GitLab 中无效
  */path /new/path 200

  GitLab 验证所有 URL 以正斜杠开头。前面示例的有效 等价形式：

  # 在 Netlify 和 GitLab 中都有效
  /old/path /new/path 200

• 所有占位符值都会被填充：

  Netlify 只填充出现在 to 路径中的占位符值：

  /old /new/:placeholder

  给定对 /old 的请求：

  • Netlify 重定向到 /new/:placeholder（带有字面 :placeholder）。
  • GitLab 重定向到 /new/。