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
스플랫 예 /news/* /blog/:splat
플레이스홀더 예 /news/:year/:month/:date /blog-:year-:month-:date.html
리라이트 (200 이외) 아니요 /en/* /en/404.html 404
쿼리 매개변수 아니요 /store id=:id /blog/:id 301
강제 (shadowing) 아니요 /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 파일에는 파일 크기 제한과 프로젝트 당 최대 규칙 수가 있으며, 인스턴스 수준에서 구성됩니다. 구성된 최대 규칙 내에서 첫 번째 일치하는 규칙만 처리됩니다. 기본 파일 크기 제한은 64KB이고, 기본 최대 규칙 수는 1,000입니다.
  • GitLab Pages 사이트가 기본 도메인 이름을 사용하는 경우(예: namespace.gitlab.io/project-slug) 매 규칙에 경로를 접두어로 지정해야 합니다: plaintext /project-slug/wardrobe.html /project-slug/narnia.html 302
  • GitLab Pages 사이트가 사용자 정의 도메인을 사용하는 경우, 프로젝트 경로 접두어가 필요하지 않습니다. 예를들어 사용자 정의 도메인이 example.com인 경우, _redirects 파일은 다음과 같아야 합니다: plaintext /wardrobe.html /narnia.html 302

파일이 리다이렉트를 재정의합니다

파일은 리다이렉트보다 우선시됩니다. 디스크에 파일이 있는 경우 GitLab Pages는 리다이렉트 대신 파일을 제공합니다. 예를들어, hello.html과 world.html 파일이 존재하는데, _redirects 파일에 다음 줄이 포함되어 있는 경우 hello.html이 있기 때문에 리다이렉트는 무시됩니다: plaintext /project-slug/hello.html /project-slug/world.html 302 GitLab에서는 파일이 존재할 경우 이 동작을 변경하기 위해 Netlify 강제 옵션을 지원하지 않습니다.

HTTP 상태 코드

제공된 상태 코드가 없는 경우 기본 상태 코드 301이 적용되지만, 직접 상태 코드를 설정할 수 있습니다. 다음 HTTP 코드가 지원됩니다:

  • 301: 영구적 리다이렉트
  • 302: 일시적 리다이렉트
  • 200: 성공적인 HTTP 요청에 대한 기본 응답. 페이지는 주소 표시줄의 URL을 변경하지 않고 to 규칙에 콘텐츠를 제공합니다.

리다이렉트

리다이렉트를 생성하려면 from 경로, to 경로 및 HTTP 상태 코드를 포함하는 규칙을 추가하세요: ```plaintext # 301 영구 리다이렉트 /old/file.html /new/file.html 301

302 일시적 리다이렉트

/old/another_file.html /new/another_file.html 302 ```

리라이트

  • GitLab 15.2에서 GitLab.com 및 Self-managed에서 활성화됨.

요청이 from과 일치하는 경우 to 경로의 콘텐츠를 제공하기 위해 200 상태 코드를 제공하세요: plaintext /old/file.html /new/file.html 200

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

도메인 레벨 리다이렉트

  • GitLab 16.8에서 사용되었습니다. 기본적으로 비활성화되어 있으며 FF_ENABLE_DOMAIN_REDIRECT라는 플래그로 제어됩니다.
  • GitLab 16.9에서 GitLab.com에서 활성화됨.
Self-managed GitLab의 경우, 기본적으로 이 기능은 사용할 수 없습니다. 사용하려면 관리자가 FF_ENABLE_DOMAIN_REDIRECT라는 플래그를 활성화할 수 있습니다. GitLab.com에서는 이 기능을 사용할 수 있습니다. GitLab Dedicated에서는 이 기능을 사용할 수 없습니다.

도메인 레벨 리다이렉트를 생성하려면 도메인 수준 경로(http:// 또는 https://로 시작)를 to 경로 또는 from 및 to 경로에 추가하세요.

지원되는 HTTP 상태 코드는 301 및 302입니다: ```plaintext # 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 path에 별표(*)가 포함된 규칙은 splat이라고하며, 요청된 경로의 시작, 중간 또는 끝에 있는 모든 것과 일치합니다. 이 예제는 /old/ 이후의 모든 내용과 일치하고 이를 /new/file.html로 다시 쓰여집니다: 

/old/* /new/file.html 200

Splat 플레이스홀더

규칙의 from 경로에서 *에 의해 일치하는 내용은 :splat 플레이스홀더를 사용하여 to 경로로 주입될 수 있습니다: 

/old/* /new/:splat 200

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

하나의 규칙 from 경로에 복수의 splat이 포함되어 있는 경우, 첫 번째 splat의 값이 to 경로의 모든 :splat을 대체합니다.

Splat 일치 동작

Splats는 “greedy”하며 가능한 많은 문자와 일치합니다: 

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

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

Splats는 빈 문자열에도 일치하므로 이전 규칙은 /old/file을 /new/file로 리디렉션합니다.

모든 요청을 루트의 index.html로 리다이렉트

참고: GitLab Pages integration with Let’s Encrypt을 사용하는 경우, 리디렉션이 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

이 규칙은 /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/로 리디렉션합니다.