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 force 옵션을 지원하지 않습니다.

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

리라이트#

요청이 from과 일치할 때 to 경로의 콘텐츠를 제공하려면 상태 코드 200을 지정합니다:

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

이 상태 코드는 스플랫 규칙과 함께 사용하여 URL을 동적으로 재작성할 수 있습니다.

도메인 수준 리다이렉트#

도메인 수준 리다이렉트를 만들려면 다음 중 하나에 도메인 수준 경로(http:// 또는 https://로 시작)를 추가합니다:

• to 경로에만 추가합니다.
• from과 to 경로 모두에 추가합니다.

지원되는 HTTP 상태 코드는 301과 302 입니다:

# 301 permanent redirect
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 temporary redirect
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 요청은 /new/file.html의 콘텐츠를 상태 코드 200으로 제공합니다.

규칙의 from 경로에 스플랫이 여러 개 있으면 첫 번째 스플랫에 일치한 값이 to 경로의 모든 :splat을 대체합니다.

스플랫 매칭 동작#

스플랫은 "탐욕적"이어서 가능한 한 많은 문자와 일치합니다:

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

이 예시에서 규칙은 /old/a/b/c/file을 /new/a/b/c/file로 리다이렉트합니다.

스플랫은 빈 문자열과도 일치하므로, 앞의 규칙은 /old/file을 /new/file로 리다이렉트합니다.

스플랫으로 파일 확장자 일치#

from 경로에서 스플랫은 파일 확장자 바로 앞에 올 수 있습니다. 예를 들어 다음 규칙은 모든 .html 요청과 일치하고, 확장자 없이 끝에 슬래시를 붙인 같은 경로로 리다이렉트합니다:

/*.html /:splat/ 301

이 예시에서 /page.html 요청은 /page/로, /docs/page.html 요청은 /docs/page/로 리다이렉트됩니다.

모든 요청을 루트 index.html로 재작성#

단일 페이지 애플리케이션(SPA)은 클라이언트 측 라우트를 사용하여 자체 라우팅을 수행하는 경우가 많습니다. 이러한 애플리케이션에서는 라우팅 로직을 JavaScript 애플리케이션이 처리할 수 있도록 모든 요청을 루트 index.html로 재작성합니다.

요청을 index.html로 재작성하려면:

1. 다음 _redirects 규칙을 추가합니다:

   /* /index.html 200
   

2. 단일 페이지 애플리케이션이 병렬 배포에서 동작하도록 하려면 리다이렉트 규칙을 수정하여 경로 접두사를 포함합니다:

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

   <prefix>를 사용 중인 경로 접두사 값으로 바꿉니다.

플레이스홀더#

규칙에 플레이스홀더를 사용하면 요청 URL의 일부와 일치시키고, 새 URL로 재작성하거나 리다이렉트할 때 그 일치 값을 사용할 수 있습니다.

플레이스홀더는 from과 to 경로 모두에서 : 문자 뒤에 문자열 ([a-zA-Z]+)이 오는 형식입니다:

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

이 규칙은 /news/2021/08/12/file.html 요청에 대해 Pages가 /blog/2021-08-12-file.html의 콘텐츠를 200으로 제공하도록 지시합니다.

플레이스홀더 매칭 동작#

스플랫과 비교하면 플레이스홀더는 일치시키는 콘텐츠의 범위가 더 제한적입니다. 플레이스홀더는 슬래시(/) 사이의 텍스트와 일치하므로, 단일 경로 세그먼트를 일치시킬 때 사용합니다.

또한 플레이스홀더는 빈 문자열과 일치하지 않습니다. 다음과 같은 규칙은 /old/file 같은 요청 URL과 일치하지 않습니다:

/old/:path /new/:path

리다이렉트 규칙 디버그#

리다이렉트가 예상대로 동작하지 않거나 리다이렉트 구문을 확인하려면 [your pages url]/_redirects에 접속합니다. _redirects 파일은 직접 제공되지 않지만, 브라우저에 리다이렉트 규칙이 번호가 매겨진 목록으로 표시되고 각 규칙의 유효 여부도 함께 표시됩니다:

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 구현과의 차이점#

지원되는 대부분의 _redirects 규칙은 GitLab과 Netlify에서 동일하게 동작합니다. 다만 몇 가지 사소한 차이가 있습니다:

• 모든 규칙 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
  

• 모든 플레이스홀더 값이 채워집니다:

  Netlify는 to 경로에 나타나는 플레이스홀더 값만 채웁니다:

  /old /new/:placeholder
  

  /old 요청이 들어오면:

  • Netlify는 /new/:placeholder로 리다이렉트합니다(문자 그대로의 :placeholder).
  • GitLab은 /new/로 리다이렉트합니다.