GitLab Pages 리디렉션

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

GitLab Pages에서 Netlify 스타일 HTTP 리디렉션을 사용하여 한 URL을 다른 URL로 전달할 수 있습니다.

Netlify에서 제공하는 특별 옵션 중 일부만 지원됩니다.

기능 지원 여부 예시
리디렉션 (301, 302) 예 /wardrobe.html /narnia.html 302
재작성 (200) 예 /* / 200
Splats 예 /news/* /blog/:splat
플레이스홀더 예 /news/:year/:month/:date /blog-:year-:month-:date.html
재작성(단, 200이 아닌 다른 코드) 아니오 /en/* /en/404.html 404
쿼리 매개변수 아니오 /store id=:id /blog/:id 301
강제 (쉐도잉) 아니오 /app/ /app/index.html 200!
도메인 수준 리디렉션 예 http://blog.example.com/* https://www.example.com/blog/:splat 301
국가 또는 언어별 리디렉션 아니오 / /anz 302 Country=au,nz
역할별 리디렉션 아니오 /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의 강제 옵션을 지원하지 않아 이 동작을 변경할 수 없습니다.

HTTP 상태 코드

상태 코드를 제공하지 않으면 기본 상태 코드 301이 적용되지만 직접 설정할 수 있습니다. 다음 HTTP 상태 코드가 지원됩니다:

  • 301: 영구적 리디렉션.
  • 302: 임시 리디렉션.
  • 200: 성공적인 HTTP 요청에 대한 표준 응답. 페이지가 to 규칙에 내용이 있는 경우 주소 표시줄의 URL을 변경하지 않고 내용을 제공합니다.

리다이렉트

리디렉트를 생성하려면 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.com 및 self-managed에서 GitLab 15.2에서 활성화되었습니다.

요청이 from에 일치하는 경우 to 경로의 내용을 제공하려면 200 상태 코드를 제공하십시오: 

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

이 상태 코드는 스플래트 규칙과 결합하여 URL을 동적으로 리라이트하는 데 사용할 수 있습니다.

도메인 레벨 리디렉트

  • GitLab 16.8에서 FF_ENABLE_DOMAIN_REDIRECT라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
  • GitLab.com에서 GitLab 16.9에서 활성화되었습니다.

플래그: 자체 관리형 GitLab에서는 기본적으로 이 기능을 사용할 수 없습니다. 이를 사용하려면 관리자가 FF_ENABLE_DOMAIN_REDIRECT라는 플래그를 활성화할 수 있습니다. 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 경로에 여러 스플래트가 포함된 경우 첫 번째 스플래트 일치 값은 to 경로의 모든 :splat을 대체합니다.

스플래트 일치 동작

스플래트는 가능한 많은 문자와 일치하여 “탐욕적”입니다: 

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

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

스플래트는 빈 문자열도 일치시키므로 이전 규칙은 /old/file을 /new/file로 리디렉트합니다.

모든 요청을 루트 index.html로 리라이트

참고: GitLab Pages의 Let’s Encrypt 통합을 사용 중이라면, 이 규칙을 추가하기 전에 활성화해야 합니다. 그렇지 않으면 리디렉션이 Let’s Encrypt 통합을 망가뜨립니다. 자세한 내용은 GitLab Pages issue 649을 참조하세요.

싱글 페이지 애플리케이션(SPA)은 자체적인 라우팅을 사용하여 클라이언트 측 경로를 수행합니다. 이러한 응용 프로그램에서는 모든 요청을 루트 index.html로 다시 작성하여 JavaScript 애플리케이션에서 라우팅 로직을 처리할 수 있어야 합니다. 이를 위해 _redirects 규칙을 사용할 수 있습니다: 

/* /index.html 200

자리 표시자

규칙에서 URL의 일부를 매치하고, 새 URL로 리다이렉팅하거나 재작성할 때 이러한 일치 항목을 사용합니다.

자리 표시자는 : 문자 다음에 문자열([a-zA-Z]+)로 구성되며, from 및 to 경로 모두에 사용됩니다. 

/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의 콘텐츠를 제공하도록 지시합니다.

자리 표시자 매칭 동작

splats와 비교했을 때, 자리 표시자는 매치하는 콘텐츠의 양에서 더 제한적입니다. 자리 표시자는 슬래시(/) 사이의 텍스트에 매치되므로 단일 경로 세그먼트에 자리 표시자를 사용하세요.

또한, 자리 표시자는 빈 문자열을 매치하지 않습니다. 다음과 같은 규칙은 /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이 슬래시로 시작되는 것을 요구하지 않습니다. 

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