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

참고:
매칭 동작 테스트 케이스는 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 option을 지원하지 않습니다.

HTTP 상태 코드

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

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

리디렉션

리디렉션을 만들려면 from 경로, to 경로, 및 HTTP 상태 코드를 포함하는 규칙을 추가합니다:

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

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

재작성

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

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

이 상태 코드는 splat rules와 조합하여 URL을 동적으로 재작성하는 데 사용할 수 있습니다.

도메인 수준 리디렉션

플래그: self-managed 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

도메인 수준 리디렉션은 splat rules (splat 자리 표시자를 포함)와 조합하여 URL 경로를 동적으로 재작성하는 데 사용할 수 있습니다.

Splats

from 경로에 별표(*)가 있는 규칙은 스플랫(splat)이라고 하며, 요청된 경로의 시작, 중간 또는 끝에 있는 모든 것과 일치합니다. 이 예제는 /old/ 이후의 모든 것에 일치하고 /new/file.html로 재작성합니다:

/old/* /new/file.html 200

Splat placeholders

규칙의 from 경로에 있는 *와 일치하는 콘텐츠는 :splat 자리 표시자를 사용하여 to 경로에 주입될 수 있습니다:

/old/* /new/:splat 200

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

규칙의 from 경로에 여러 개의 스플랫이 포함되어 있는 경우, 첫 번째 스플랫 일치의 값이 to 경로의 모든 :splat를 대체합니다.

Splat matching behavior

스플랫은 “탐욕적”이며 가능한 많은 문자를 일치시킵니다:

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

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

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

Rewrite all requests to a root index.html

note
GitLab Pages integration with Let’s Encrypt를 사용하는 경우, 이 규칙을 추가하기 전에 이를 활성화해야 합니다. 그렇지 않으면 리디렉션이 Let’s Encrypt 통합을 중단시킵니다. 더 자세한 내용은 GitLab Pages issue 649를 참조하세요.

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

/* /index.html 200

Placeholders

규칙에서 자리 표시자를 사용하여 요청된 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에 대한 요청에 대해 /blog/2021-08-12-file.html의 콘텐츠를 200 상태 코드와 함께 제공하도록 지시합니다.

Placeholder matching behavior

splats와 비교할 때 자리 표시자는 일치시키는 콘텐츠의 양이 더 제한적입니다. 자리 표시자는 슬래시(/) 사이의 텍스트와 일치하므로 단일 경로 세그먼트를 일치시키는 데 사용합니다.

또한 자리 표시자는 빈 문자열과 일치하지 않습니다. 다음과 같은 규칙은 /old/file과 같은 요청 URL과 일치하지 않습니다:

/old/:path /new/:path

Debug redirect rules

리디렉션이 예상대로 작동하지 않거나 리디렉션 구문을 확인하려면 [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/로 리다이렉트합니다.