GitLab Pages 리디렉션

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

GitLab Pages에서 HTTP 리디렉션을 사용하여 한 URL을 다른 URL로 전환하는 규칙을 구성할 수 있습니다. Netlify 스타일의 HTTP 리디렉션을 지원합니다.

모든 Netlify에서 제공하는 특별한 옵션 을 지원하지는 않습니다.

기능 지원 여부 예시
리디렉션(301, 302) Yes /wardrobe.html /narnia.html 302
리라이트(200) Yes /* / 200
스플랫 Yes /news/* /blog/:splat
플레이스홀더 Yes /news/:year/:month/:date /blog-:year-:month-:date.html
기타 리라이트(200 이외) No /en/* /en/404.html 404
쿼리 매개변수 No /store id=:id /blog/:id 301
강제 (shadowing) No /app/ /app/index.html 200!
도메인 수준 리디렉션 Yes http://blog.example.com/* https://www.example.com/blog/:splat 301
국가 또는 언어별 리디렉션 No / /anz 302 Country=au,nz
역할별 리디렉션 No /admin/* 200! Role=admin
note
일치 동작 테스트 케이스는 GitLab이 규칙 일치를 어떻게 구현하는지에 대한 이해에 좋은 자료입니다. 이 테스트 스위트에 포함되지 않은 경우를 위해 커뮤니티 기여가 환영됩니다!

리디렉션 생성

리디렉션을 생성하려면 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 요청에 대한 표준 응답. 페이지는 주소 표시줄의 URL을 변경하지 않고 to 규칙의 내용을 제공합니다.

리디렉션

GitLab 14.3에 도입되었습니다. GitLab.com에서 활성화되었습니다. Self-managed에서 GitLab 14.6에서 활성화되었습니다.

리디렉션을 생성하려면 from 경로, to 경로 및 HTTP 상태 코드를 포함하는 규칙을 추가하십시오: 

# 301 영구적 리디렉션
/old/file.html /new/file.html 301

# 302 일시적 리디렉션
/old/another_file.html /new/another_file.html 302

리라이트

GitLab 14.3에 도입되었으며 기본적으로 비활성화된 환경 변수 사용를 위한 FF_ENABLE_PLACEHOLDERS라는 플래그로 제공됩니다. GitLab 15.2에서 GitLab.com 및 Self-managed에서 활성화되었습니다.

요청이 from과 일치하는 경우 to 경로의 내용을 제공하기 위해 상태 코드 200을 제공합니다: 

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

이 상태 코드는 splat 규칙과 함께 사용하여 URL을 동적으로 다시 작성하는 데 사용될 수 있습니다.

도메인 수준 리디렉션

플래그: Self-managed GitLab에서는 기본적으로 이 기능을 사용할 수 없습니다. 관리자는 피처 플래그를 활성화하여 사용할 수 있습니다. GitLab.com에서는 이 기능을 사용할 수 있습니다. GitLab Dedicated에서는 이 기능을 사용할 수 없습니다.

도메인 수준 리디렉션을 생성하려면 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 경로에서 *로 일치한 내용은 to 경로의 :splat 플레이스홀더를 사용하여 삽입할 수 있습니다: 

/old/* /new/:splat 200

이 예에서 /old/file.html에 대한 요청은 200 상태 코드로 /new/file.html의 내용을 제공합니다.

from 경로에 여러 개의 스플랫이 포함된 경우, 첫 번째 스플랫 일치값이 :splat을 to 경로에 대치합니다.

스플랫 일치 동작

스플랫은 가능한 많은 문자와 일치하는 “탐욕스러운(greedy)” 특성을 가지고 있습니다: 

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

이 예에서 규칙은 /old/a/b/c/file를 /new/a/b/c/file로 리디렉션합니다.

또한 스플랫은 빈 문자열과도 일치하므로 이전 규칙은 /old/file를 /new/file로 리디렉션합니다.

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

note
GitLab Pages에서 Let’s Encrypt와 통합을 사용 중이라면 이 규칙을 추가하기 전에 먼저 활성화해야 합니다. 그렇지 않으면 리디렉션이 Let’s Encrypt 통합을 깨뜨릴 수 있습니다. 자세한 내용은 GitLab Pages 이슈 649을 참조하세요.

단일 페이지 응용 프로그램(SPA)은 종종 클라이언트 측 경로를 사용하여 자체 라우팅을 수행합니다. 이러한 응용 프로그램에서는 루팅 로직이 JavaScript 애플리케이션에서 처리되도록 모든 요청이 루트 index.html로 재작성되어야 합니다. 이를 _redirects 규칙으로 다음과 같이 처리할 수 있습니다: 

/* /index.html 200

플레이스홀더

규칙에서 플레이스홀더를 사용하여 요청된 URL의 일부를 일치시키고 새 URL로 재작성하거나 리디렉션하는 데 사용하세요.

플레이스홀더는 [a-zA-Z]+로 구성된 문자열 다음에 : 문자로 형식화됩니다. 

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

이 규칙은 Pages에게 /news/2021/08/12/file.html 요청에 대한 응답으로 200 상태 코드로 /blog/2021-08-12-file.html의 내용을 제공하도록 지시합니다.

플레이스홀더 일치 동작

스플랫과 비교하여 플레이스홀더는 일치하는 내용의 제한이 더 있습니다. 플레이스홀더는 슬래시(/) 사이의 텍스트에 일치하므로 단일 경로 세그먼트를 일치시키기 위해 플레이스홀더를 사용하세요.

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

/old/:path /new/:path

리디렉트 규칙 디버그

리디렉션이 예상대로 작동하지 않거나 리디렉트 구문을 검사하려는 경우 [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이 슬래시로 시작하는 것을 요구하지 않습니다: 

    # 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/로 리디렉션합니다.