• 创建重定向
• 文件覆盖重定向
• HTTP 状态码
• 重定向
• 重写
• 域名级别重定向
• Splats
  • Splat 占位符
  • Splat 匹配特征
  • 将所有请求重写为根 index.html
• 占位符
  • 占位符匹配特征
• 重定向规则排查
• 与 Netlify 实现的差异

极狐GitLab Pages 重定向

在 Pages 中，您可以配置规则，使用 Netlify 样式 HTTP 重定向，将一个 URL 转发到另一个。

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

创建重定向

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

• 所有路径必须以正斜杠 / 开头。
• 如果未提供状态码，则应用默认状态代码 301。
• _redirects 文件具有文件大小限制和每个项目的最大规则数，在实例级别配置。仅处理配置第一个匹配规则的最大值。默认文件大小限制为 64KB，默认最大规则数为 1,000。

• 如果您的 Pages 站点使用默认域名（例如 namespace.gitlab.io/projectname），您必须在每个规则前面加上项目名称：

  /projectname/wardrobe.html /projectname/narnia.html 302
  

• 如果您的 Pages 站点使用自定义域名，则不需要项目名称前缀。例如，您的自定义域名是 example.com，您的 _redirects 文件将如下所示：

  /wardrobe.html /narnia.html 302
  

文件覆盖重定向

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

/projectname/hello.html /projectname/world.html 302

系统不支持 Netlify 的强制选项来更改此行为。

HTTP 状态码

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

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

重定向

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

# 301 permanent redirect
/old/file.html /new/file.html 301

# 302 temporary redirect
/old/another_file.html /new/another_file.html 302

重写

历史记录：

• 在极狐GitLab 15.2版本 私有化部署上启用。

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

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

该状态码可以与 SPLAT 规则结合使用，动态重写 URL。

域名级别重定向

历史记录：

• 在极狐GitLab 16.8 版本里通过标志 FF_ENABLE_DOMAIN_REDIRECT 引入，默认禁用。
• 在极狐GitLab 16.9 版本 在Jihulab.com上启用

要创建域名级别的重定向，添加一个域名级别的路径（以 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

域名级别重定向可以和 splat 规则 （包括 splat 占位符）组合使用来动态重写 URL 路径。

Splats

在 from 路径（称为 splat）中带有星号（*）的规则，在请求路径的开头，中部或结尾处匹配任何内容。此示例匹配 /old/ 之后的任何内容，然后将其重写为 /new/file.html：

/old/* /new/file.html 200

Splat 占位符

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

/old/* /new/:splat 200

在此例中，对 /old/file.html 的请求，响应 /new/file.html，状态码为 200。

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

Splat 匹配特征

Splats是“贪婪”的，匹配尽可能多的字符：

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

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

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

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

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

/* /index.html 200

占位符

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

在 from and to 路径中，占位符的格式为 : 字符跟在字母 ([a-zA-Z]+) 字符串的后面：

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

本规则指示 Pages 对于 /news/2021/08/12/file.html 的请求，重定向到 /blog/2021-08-12-file.html，状态码为 200。

占位符匹配特征

与 splats 相比，占位符在匹配的内容上更加有限，占位符匹配斜杠 / 之间的文本，因此请使用占位符匹配单路径。

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

/old/:path /new/:path

重定向规则排查

如果重定向无法正常工作，或者您想检查重定向语法，请访问 [your pages url]/_redirects。_redirect 文件不是直接提供的，您的浏览器显示您的重定向规则的编号列表，以及该规则是有效的还是无效的：

11 rules
rule 1: valid
rule 2: valid
rule 3: error: splats are not supported
rule 4: valid
rule 5: error: placeholders are not supported
rule 6: valid
rule 7: error: no domain-level redirects to outside sites
rule 8: error: url path must start with forward slash /
rule 9: error: no domain-level redirects to outside sites
rule 10: valid
rule 11: valid

与 Netlify 实现的差异

大多数支持的 _redirect 规则的行为相同。但是，有一些较小的差异：

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

  Netlify 不需要 URL 以斜线开头：

  # Valid in Netlify, invalid in GitLab
  */path /new/path 200
  

  极狐GitLab 需要 URL 以斜线开头，与以上规则等效：

  # Valid in both Netlify and GitLab
  /old/path /new/path 200
  

• 所有 placeholder 值都被填充：

  Netlify 仅填入 to 路径中出现的 placeholder 值：

  /old /new/:placeholder
  

  向 /old 发送请求：

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