Cloudflare로 커스텀 도메인을 연결할 때 어려운 이유는, 겉으로 드러나는 증상이 비슷하기 때문입니다. 브라우저에서는 전부 “안 뜬다”로 보이지만, 실제 원인은 DNS일 수도 있고, Pages 대시보드에서 도메인 연결이 끝나지 않은 것일 수도 있고, 인증서 발급 제한일 수도 있고, 심지어는 배포 결과물 루트에 index.html이 없는 문제일 수도 있습니다.

특히 Cloudflare Pages를 쓰는 경우에는 도메인 연결과 사이트 배포가 서로 다른 층에 있기 때문에 더 헷갈립니다. my-project.pages.dev는 열리는데 커스텀 도메인만 안 뜨는 경우도 있고, 반대로 도메인 설정은 맞는데 실제 사이트 루트가 비어 있어서 404가 뜨는 경우도 있습니다. 그래서 저는 Cloudflare 도메인 문제를 볼 때 항상 “DNS인지, Pages 연결인지, 인증서인지, 리다이렉트인지, 결과물인지”를 분리해서 봅니다.

Cloudflare 공식 문서를 기준으로 정리하면, 커스텀 도메인 연결에서 반복적으로 막히는 지점은 몇 가지로 압축됩니다. 아래 7가지는 처음 연결할 때뿐 아니라, 이미 연결해 둔 뒤 구조를 바꾸거나 도메인을 재정리할 때도 계속 다시 등장합니다.

기반 설계도메인 배포

Cloudflare로 커스텀 도메인 연결할 때 자주 나는 실수 7가지

Cloudflare Pages에 커스텀 도메인을 붙일 때 자주 막히는 지점을 DNS, 검증, 인증서, 리다이렉트, 빌드 결과물 기준으로 정리합니다. 어디부터 확인해야 하는지 진단 순서도 함께 적었습니다.

핵심 1

먼저 확인하는 가장 짧은 진단 순서

핵심 2

실수 1. 루트 도메인과 서브도메인 연결 방식을 같은 것으로 생각한다

핵심 3

실수 2. Pages 대시보드에서 도메인을 연결하기 전에 DNS 레코드부터 수동으로 만든다

도메인 배포기반 설계cloudflare domain connection mistakes
Pages 기준으로 DNS, 도메인 연결, 인증서, 리다이렉트, 배포 결과물을 순서대로 확인하는 흐름

먼저 확인하는 가장 짧은 진단 순서

문제를 빨리 좁히려면 아래 순서대로 확인하는 편이 좋습니다.

  1. *.pages.dev 주소가 정상적으로 열리는가
  2. Pages 대시보드의 Custom domains에서 상태가 활성화되었는가
  3. DNS가 내가 기대한 레코드로 실제 응답하는가
  4. https://example.com 요청이 어떤 상태 코드와 location 헤더를 돌려주는가
  5. 루트 경로에 실제 배포 파일이 있는가

윈도우 PowerShell에서는 이 정도만으로도 초반 진단이 꽤 됩니다.

Resolve-DnsName example.com
Resolve-DnsName www.example.com
curl.exe -I https://example.com
curl.exe -I https://www.example.com

핵심은 “커스텀 도메인이 안 뜬다”를 한 문장으로 뭉개지 않는 것입니다. DNS 응답이 없는지, 다른 대상으로 향하는지, 리다이렉트가 꼬였는지, 아니면 사이트 루트가 비어 있는지 먼저 분리해야 합니다.

실수 1. 루트 도메인과 서브도메인 연결 방식을 같은 것으로 생각한다

Cloudflare Pages 공식 문서는 루트 도메인과 서브도메인 연결 방식을 분명히 구분합니다. example.com 같은 apex domain을 Pages에 붙이려면 해당 도메인을 Cloudflare zone으로 추가하고 nameserver를 Cloudflare로 향하게 해야 합니다. 반면 blog.example.com 같은 서브도메인은 외부 DNS 제공자를 유지한 채 CNAME으로 연결할 수 있습니다.

이 차이를 놓치면 처음부터 방향이 틀어집니다. 예를 들어 루트 도메인인데 “그냥 CNAME 하나 넣으면 되겠지”라고 접근하면, 아예 요구 조건이 맞지 않습니다. 반대로 단순한 서브도메인 연결인데 전체 nameserver 이전이 꼭 필요하다고 생각하면 작업이 불필요하게 커집니다.

정리하면 이렇습니다.

  • 루트 도메인: Cloudflare zone + nameserver 설정 필요
  • 서브도메인: 외부 DNS 유지 가능, CNAME으로 연결 가능

이 구조를 먼저 이해하고 들어가야 이후 단계가 자연스럽습니다.

실수 2. Pages 대시보드에서 도메인을 연결하기 전에 DNS 레코드부터 수동으로 만든다

이건 정말 자주 나오는 실수입니다. Cloudflare Pages 문서는 원하는 도메인을 먼저 Pages 프로젝트의 Custom domains에서 연결해야 한다고 안내합니다. 그리고 문서에는 수동으로 CNAME만 먼저 만들어 버리면, Pages에 도메인이 정식으로 연결되지 않은 상태에서 522가 날 수 있다고 적혀 있습니다.

즉 순서는 보통 이렇게 가야 합니다.

  1. Workers & Pages에서 프로젝트 선택
  2. Custom domains에서 도메인 추가
  3. 필요한 방식에 따라 Cloudflare가 레코드를 만들게 하거나, 외부 DNS에 정확한 CNAME 추가

실제로는 이 순서를 반대로 하는 경우가 많습니다. DNS 레코드는 이미 맞아 보이는데 Pages 쪽에서는 도메인이 아직 연결되지 않은 상태라, 사용자는 “왜 DNS도 맞고 주소도 맞는데 안 되지?”라고 느끼게 됩니다. 이런 상황에서는 DNS만 보지 말고, 대시보드에서 해당 도메인이 프로젝트에 연결된 상태인지부터 봐야 합니다.

실수 3. CNAME이 보이지 않는 이유가 Pages 문제가 아니라 DNS 위임 구조 때문이라는 걸 놓친다

서브도메인을 외부 DNS나 복잡한 사내 DNS 구조에서 운영할 때 특히 자주 생기는 문제입니다. Cloudflare DNS 문서에서 CNAME 기반 도메인 검증이 실패하는 대표 원인으로 드는 것 중 하나가, 해당 이름이 다른 NS 레코드로 위임되어 있거나 CNAME flattening 설정 때문에 기대한 형태로 응답하지 않는 경우입니다.

실무에서는 이런 식으로 보입니다.

  • blog.example.com을 Cloudflare Pages로 붙이고 싶다
  • 그런데 example.com 아래 특정 서브도메인은 이미 다른 DNS 제공자에게 위임되어 있다
  • 그래서 Cloudflare에서 본 레코드와 실제 권한 DNS가 다르다

혹은 검증용 CNAME, 연결용 CNAME을 만들어 놓고도 응답 결과에서 CNAME이 보이지 않아 당황하기도 합니다. 이런 경우에는 “Cloudflare가 고장났다”보다 “이 호스트 이름의 권한 DNS가 어디인지, NS가 중간에 끼어 있는지”를 먼저 의심하는 편이 더 정확합니다.

최소한 아래 두 가지는 꼭 확인하는 게 좋습니다.

Resolve-DnsName blog.example.com
Resolve-DnsName -Type NS example.com

Cloudflare Pages 문제가 아니라, 서브도메인 위임 구조 때문에 내가 수정한 곳과 실제 응답하는 곳이 다른 경우가 생각보다 많습니다.

실수 4. 인증서 발급 실패를 DNS 전파 지연으로만 생각한다

Cloudflare Pages의 커스텀 도메인 설정 문서에는 CAA 레코드가 인증서 발급을 막을 수 있다는 내용이 따로 나옵니다. CAA는 어떤 인증기관이 내 도메인에 대해 인증서를 발급할 수 있는지를 제한하는 레코드인데, 여기에 Cloudflare가 사용하는 발급 경로가 허용되지 않으면 도메인 연결이 오래 멈춘 것처럼 보일 수 있습니다.

이럴 때 흔한 반응은 “DNS가 아직 안 퍼졌나 보다”입니다. 물론 실제 전파 시간도 변수지만, 한참이 지나도 SSL이 활성화되지 않는다면 CAA를 확인해야 합니다. Cloudflare 문서도 필요한 CAA 레코드를 추가해서 Cloudflare가 인증서를 발급할 수 있게 해야 한다고 안내합니다.

이 문제는 특히 도메인을 오래 운영해 온 경우 더 잘 생깁니다. 예전에 다른 인증기관 기준으로 CAA를 엄격하게 제한해 둔 상태라면, 새 프로젝트를 붙일 때 갑자기 막히기 쉽습니다. 그래서 도메인이 pending 상태에 오래 머문다면 DNS만 새로고침하지 말고 CAA부터 보는 편이 빠릅니다.

실수 5. 잠깐 다른 원본으로 돌리려고 DNS를 Pages 밖으로 뺐다가 다시 넣는다

Cloudflare Pages 문서는 한번 연결된 커스텀 도메인의 DNS 엔트리를 다른 대상으로 바꾸면 해당 커스텀 도메인이 비활성화될 수 있고, 다시 Pages로 돌린 뒤에도 다시 활성화되기 전까지 오류가 날 수 있다고 설명합니다. 즉 “잠깐 원본 서버로 돌렸다가 다시 Pages로 복귀”가 생각보다 안전한 작업이 아닐 수 있다는 뜻입니다.

이 부분이 중요한 이유는, 운영 중에 임시 대응을 DNS로 처리하려는 습관이 생기기 쉽기 때문입니다. 예를 들어 점검 페이지를 띄우고 싶어서 Pages 연결을 빼버리거나, 기존 서버로 급히 되돌렸다가 다시 Pages로 복귀하는 식입니다. 하지만 공식 문서도 이런 경우에는 DNS 대상을 바꾸는 것보다 redirect rule이나 origin rule을 쓰는 편이 낫다고 안내합니다.

즉 임시 전환이 필요할수록 DNS를 흔들기보다 규칙 계층에서 우회하는 편이 훨씬 안전합니다.

실수 6. pages.dev, www, apex를 동시에 열어두고 기준 주소를 정하지 않는다

Cloudflare는 *.pages.dev 기본 주소를 계속 유지할 수 있고, 공식 문서에는 필요하면 이 주소를 커스텀 도메인으로 리다이렉트하는 방법도 따로 설명되어 있습니다. 또 www와 apex 사이를 Bulk Redirects로 정리하는 가이드도 제공합니다.

이건 단순히 보기 좋은 URL을 고르는 문제만은 아닙니다. 공개 주소가 여러 개 열려 있으면 사용자는 어느 주소가 기준인지 헷갈리고, 운영자도 내부 링크, canonical, 공유 URL이 흐트러지기 쉽습니다. 이 부분은 Cloudflare 문서의 직접 표현은 아니고, 문서를 바탕으로 한 제 추론입니다. 하지만 공개용 사이트를 운영한다면 실제로 반드시 정리해야 하는 부분입니다.

제 추천은 단순합니다.

  • 기준 주소를 하나 고른다
  • pages.dev는 커스텀 도메인으로 보낸다
  • www와 apex 중 하나를 대표 주소로 정한다
  • 나머지는 전부 301로 보낸다

예를 들어 apex를 기준으로 잡는다면 이런 식입니다.

myblog.pages.dev -> https://example.com
https://www.example.com -> https://example.com

이렇게 해두면 이후에 slug와 URL 구조를 정리한 글에서 말한 기준 주소 원칙도 함께 지키기 쉬워집니다.

실수 7. 도메인이 안 뜨는 원인을 전부 DNS 탓으로 돌리고, 실제 배포 결과물을 보지 않는다

Cloudflare Pages 디버깅 문서에는 pages.dev 루트 주소에서 404가 뜨면 프로젝트에 index.html이 없을 가능성이 높다고 적혀 있습니다. 이건 아주 중요한 힌트입니다. 많은 사용자가 커스텀 도메인 연결 문제처럼 느끼는 상황이 사실은 “도메인은 붙었지만, 루트에 보여줄 파일이 없음”인 경우가 있기 때문입니다.

특히 정적 사이트를 배포할 때 이 문제가 잘 생깁니다.

  • 빌드 출력 디렉터리를 잘못 지정했다
  • 정적 export 결과물이 루트에 배치되지 않았다
  • 홈 페이지 파일이 빠졌다

Next.js 정적 export를 쓰는 경우라면 빌드 산출물 루트에 index.html이 생기는지부터 봐야 합니다. 폴더 구조를 잡을 때부터 이런 정적 결과물 흐름이 자연스럽게 나오도록 만드는 편이 좋고, 그 점에서는 이전에 정리한 Next.js App Router 폴더 구조 글도 같이 보면 도움이 됩니다.

즉 my-project.pages.dev 자체가 404라면, 커스텀 도메인을 만지기 전에 배포 산출물부터 확인해야 합니다. 이 단계가 빠지면 엉뚱한 곳만 계속 수정하게 됩니다.

실제 점검 순서를 다시 정리하면

제가 Cloudflare 커스텀 도메인을 점검할 때는 보통 아래 순서로 갑니다.

  1. pages.dev 기본 주소가 열리는지 본다
  2. Pages 프로젝트의 Custom domains에 도메인이 실제로 연결되어 있는지 본다
  3. 루트 도메인인지, 서브도메인인지 구분한다
  4. DNS 응답이 기대한 대상과 일치하는지 본다
  5. NS 위임이나 CNAME 응답 문제를 본다
  6. SSL이 오래 pending이면 CAA를 본다
  7. 마지막으로 pages.dev, www, apex 리다이렉트 전략을 정리한다

간단한 헤더 확인도 꽤 도움이 됩니다.

curl.exe -I https://example.com
curl.exe -I https://www.example.com
curl.exe -I https://my-project.pages.dev

여기서 상태 코드와 location 헤더만 봐도, 리다이렉트 전략이 빠졌는지 대충 감이 옵니다.

마무리

Cloudflare 커스텀 도메인 연결은 한 번에 끝나는 단일 작업처럼 보이지만, 실제로는 DNS, 프로젝트 연결, 인증서, 리다이렉트, 배포 결과물이라는 다섯 층이 겹쳐 있는 작업입니다. 그래서 “왜 안 뜨지?”라는 질문 하나로는 원인을 좁히기 어렵고, 각 층을 따로 봐야 빠르게 해결됩니다.

공식 문서를 기준으로 보면 특히 많이 틀리는 부분은 루트 도메인과 서브도메인을 같은 방식으로 다루는 것, Pages 등록보다 DNS를 먼저 만지는 것, CAA나 NS 위임 같은 보이지 않는 DNS 조건을 놓치는 것, 그리고 실제로는 사이트 루트가 비어 있는데 도메인 문제라고 생각하는 것입니다.

처음 연결할 때 이 순서를 한 번만 제대로 익혀두면, 나중에 www 정리나 canonical 정리, 사이트 이전 같은 작업도 훨씬 덜 흔들립니다. 다음 단계에서는 보통 www, non-www, canonical을 한 번에 정리하는 문제가 이어지는데, 이건 도메인이 실제로 열리기 시작한 뒤 바로 손대는 편이 좋습니다.

참고 문서