Redirects
Cloudflare Pages에서 _redirects 파일을 사용하여 URL 리다이렉트를 설정하는 방법을 설명합니다.
_redirects 파일 생성
파일 위치
_redirects 파일(확장자 없음)을 프로젝트의 정적 에셋 디렉토리에 생성합니다:
| 프레임워크 | 위치 |
|---|---|
| Astro | public/_redirects |
| Next.js | public/_redirects |
| Vue/Nuxt | public/_redirects 또는 static/_redirects |
| 정적 사이트 | 빌드 출력 디렉토리 |
구문
기본 형식
[소스] [목적지] [상태코드]- 소스: 리다이렉트할 원본 경로 (와일드카드, 플레이스홀더 지원)
- 목적지: 이동할 경로 또는 외부 URL
- 상태코드: HTTP 상태 코드 (선택사항, 기본값 302)
예시
# 기본 리다이렉트 (302)/home /
# 영구 리다이렉트 (301)/old-page /new-page 301
# 외부 URL로 리다이렉트/twitter https://twitter.com/myaccount 301
# 주석은 #으로 시작# 이 줄은 무시됩니다상태 코드
지원되는 상태 코드
| 코드 | 유형 | 설명 |
|---|---|---|
| 301 | Permanent | 영구 리다이렉트 (SEO에 권장) |
| 302 | Found | 임시 리다이렉트 (기본값) |
| 303 | See Other | POST 후 GET으로 리다이렉트 |
| 307 | Temporary | 임시 리다이렉트 (메서드 유지) |
| 308 | Permanent | 영구 리다이렉트 (메서드 유지) |
| 200 | Proxy | URL 변경 없이 콘텐츠 제공 |
상태 코드 선택 가이드
# 페이지가 영구적으로 이동한 경우/old-url /new-url 301
# 일시적으로 다른 페이지로 보내는 경우/maintenance /temp-page 302
# URL은 유지하면서 다른 콘텐츠 제공 (프록시)/api/* /functions/api/:splat 200와일드카드 (Splats)
와일드카드 *는 모든 문자와 매칭됩니다. 목적지에서 :splat으로 매칭된 값을 참조할 수 있습니다.
기본 사용
# /blog/anything → https://blog.example.com/anything/blog/* https://blog.example.com/:splat
# /docs/guides/setup → /documentation/guides/setup/docs/* /documentation/:splat 301다중 와일드카드
# /old/a/b/c → /new/a/b/c/old/* /new/:splat 301실전 예시
# 블로그 이전/blog/* https://blog.mysite.com/:splat 301
# 이미지 CDN으로 프록시/images/* /cdn/images/:splat 200
# API 버전 리다이렉트/api/v1/* /api/v2/:splat 301플레이스홀더
플레이스홀더 :name은 경로 세그먼트를 캡처하여 목적지에서 재사용할 수 있습니다.
기본 사용
# /movies/inception → /media/inception/movies/:title /media/:title
# /users/123/profile → /profile/123/users/:id/profile /profile/:id 301다중 플레이스홀더
# /blog/2024/01/hello → /posts/2024/01/hello/blog/:year/:month/:slug /posts/:year/:month/:slug 301
# /products/electronics/phone → /shop/electronics/phone/products/:category/:item /shop/:category/:item플레이스홀더 규칙
- 호스트명에서는 마침표(
.)를 제외한 모든 문자 매칭 - 경로에서는 슬래시(
/)를 제외한 모든 문자 매칭
프록시 (상태 코드 200)
상태 코드 200을 사용하면 URL을 변경하지 않고 다른 위치의 콘텐츠를 제공합니다.
사용 예시
# /app/* 요청을 SPA의 index.html로 프록시/app/* /app/index.html 200
# 특정 경로를 다른 페이지로 프록시/dashboard /app/dashboard.html 200제한 사항
- 상대 URL만 지원: 프록시는 같은 사이트 내의 경로만 가능
- 외부 URL 불가:
https://other-site.com으로 프록시 불가
# ✅ 올바른 사용/api/* /functions/api/:splat 200
# ❌ 동작하지 않음 (외부 URL)/api/* https://api.example.com/:splat 200정적 vs 동적 리다이렉트
정적 리다이렉트
와일드카드나 플레이스홀더가 없는 리다이렉트:
/about /about-us 301/contact /contact-us 301/home / 301동적 리다이렉트
와일드카드나 플레이스홀더를 포함한 리다이렉트:
/blog/* /posts/:splat 301/users/:id /profile/:id 301우선순위
리다이렉트는 파일에 정의된 순서대로 평가됩니다. 첫 번째로 매칭되는 규칙이 적용됩니다.
# 구체적인 규칙을 먼저 정의/blog/featured /featured-posts 301/blog/* /posts/:splat 301
# 위 순서에서 /blog/featured는 첫 번째 규칙에 매칭# /blog/other는 두 번째 규칙에 매칭실전 예시
완전한 _redirects 파일
# 홈페이지 리다이렉트/home / 301/index.html / 301
# 페이지 이름 변경/about-us /about 301/contact-us /contact 301
# 삭제된 페이지/old-feature /new-feature 301/deprecated/* / 301
# 블로그 URL 구조 변경/blog/:year/:month/:day/:slug /blog/:slug 301
# 외부 서비스 리다이렉트/twitter https://twitter.com/myaccount 301/github https://github.com/myrepo 301/linkedin https://linkedin.com/in/myprofile 301
# 단축 URL/go/docs https://docs.example.com 302/go/support https://support.example.com 302
# SPA 라우팅 (프록시)/app/* /app/index.html 200
# API 버전 마이그레이션/api/v1/* /api/v2/:splat 301
# 언어별 리다이렉트/en/* /:splat 301/ko /도메인 이전
# 이전 도메인에서 새 도메인으로/* https://new-domain.com/:splat 301SPA (Single Page Application)
# 모든 경로를 index.html로 프록시/* /index.html 200주의: 이 규칙은 정적 에셋도 index.html로 프록시하므로, 에셋 경로는 별도로 처리해야 합니다.
다국어 사이트
# 언어 코드 리다이렉트/en/about /about 301/ko/about /ko/about 301/ja/* /ja/:splat 200제한 사항
수량 제한
| 유형 | 제한 |
|---|---|
| 정적 리다이렉트 | 최대 2,000개 |
| 동적 리다이렉트 | 최대 100개 |
| 총합 | 최대 2,100개 |
| 각 줄 길이 | 최대 1,000자 |
지원하지 않는 기능
- 쿼리 파라미터 매칭:
?param=value기반 리다이렉트 불가 - 도메인 레벨 리다이렉트:
_redirects로는 불가 (Bulk Redirects 사용) - 조건부 리다이렉트: 국가, 언어, 쿠키 기반 리다이렉트 불가
- Pages Functions 응답: Functions 응답에는 적용되지 않음
대안: Bulk Redirects
제한을 초과하는 경우 Cloudflare의 Bulk Redirects를 사용하세요:
- 수만 개의 리다이렉트 지원
- 도메인 레벨 리다이렉트 가능
- 조건부 리다이렉트 지원
디버깅
리다이렉트 테스트
# curl로 리다이렉트 확인curl -I https://your-site.pages.dev/old-page
# 리다이렉트 체인 따라가기curl -IL https://your-site.pages.dev/old-page일반적인 문제
-
리다이렉트가 적용되지 않음
_redirects파일이 빌드 출력에 포함되었는지 확인- 구문 오류 확인 (공백, 줄바꿈)
-
무한 리다이렉트 루프
- 소스와 목적지가 서로를 가리키지 않는지 확인
- 와일드카드 규칙이 너무 광범위하지 않은지 확인
-
정적 에셋이 리다이렉트됨
- SPA 프록시 규칙보다 에셋 경로 규칙을 먼저 정의
# 올바른 순서/assets/* /assets/:splat 200/* /index.html 200Headers와의 관계
리다이렉트는 헤더보다 먼저 적용됩니다. 요청이 리다이렉트와 헤더 규칙 모두에 매칭되면, 리다이렉트가 우선합니다.
# _redirects/old /new 301
# _headers/old X-Custom: value # 이 헤더는 적용되지 않음 (리다이렉트됨)