Apex 도메인#

1
example.com  ← Apex (루트 도메인)

Apex는 도메인의 루트입니다. www가 없는 깔끔한 형태입니다.

장점:

• URL이 짧고 기억하기 쉬움
• 브랜드 정체성을 대표하는 주소로 사용하기 적합

단점:

• 일반적인 DNS에서는 Apex에 CNAME 사용 불가
• Cloudflare DNS 같은 Flattening 지원 환경이 필요할 수 있음

Subdomain#

1
www.example.com     ← Subdomain (www)
2
blog.example.com    ← Subdomain (blog)
3
api.example.com     ← Subdomain (api)

Subdomain은 도메인 앞에 접두사가 붙은 형태입니다.

장점:

• CNAME 레코드 사용 가능
• 외부 DNS 환경에서도 설정이 단순함
• 서비스별 분리에 유리 (blog, api 등)

단점:

• URL이 길어짐
• 쿠키, 인증, 분석 도구 설정이 분리될 수 있음 (서브도메인마다 설정해야 함)

실무에서는 보통 Apex를 메인 도메인으로 사용하고,
www는 Apex로 리다이렉트하는 방식을 많이 사용합니다.

Cloudflare Pages Dashboard에서 설정#

1. Build > Compute & AI > Workers & Pages > 커스텀도메인 적용할 프로젝트 선택
2. Custom domains 탭 클릭
3. Set up a custom domain 버튼 클릭

도메인 입력#

도메인을 입력하는 화면이 나옵니다. 여기서 example.com처럼 Apex 도메인을 입력하세요.

1
domain:
2
example.com

Continue 클릭.

DNS 레코드 확인#

Cloudflare가 자동으로 DNS 설정을 제안합니다.

1
# Cloudflare가 제안하는 설정
2
Type: CNAME (Cloudflare DNS에서 Flattened)
3
Name: example.com (또는 @)
4
Target: your-project.pages.dev
5
Proxy status: Proxied

중요: Apex 도메인에서는 RFC상 CNAME을 사용할 수 없지만, Cloudflare DNS는 CNAME Flattening을 통해 Apex에서도 CNAME처럼 설정할 수 있도록 지원합니다.

DNS 설정 방법#

두 가지 방법이 있습니다:

1
✓ DNS record added
2
✓ SSL certificate requested
3
✓ Custom domain active
4

5
Your site is now available at:
6
https://example.com

1
# Subdomain (www)
2
Type: CNAME Record
3
Host: www
4
Value: your-project.pages.dev
5
TTL: Automatic
6

7
# Apex는 외부 DNS에서 제한적
8
# Cloudflare DNS 사용을 권장

SSL 인증서 발급#

DNS 설정이 완료되면 Cloudflare가 자동으로 SSL 인증서를 발급합니다.

1
Provisioning SSL certificate...
2
⏳ Validating domain ownership
3
⏳ Requesting Let's Encrypt certificate
4
✓ SSL certificate issued
5

6
Your site is now accessible via HTTPS

보통 1-5분 이내에 완료되지만, DNS 전파 시간에 따라 최대 24시간까지 걸릴 수 있습니다.

선택지#

두 가지 방식 중 하나를 선택하면 됩니다:

1
옵션 A: www → Apex
2
www.example.com → example.com
3

4
옵션 B: Apex → www
5
example.com → www.example.com

옵션 A (Apex를 메인으로)는 URL이 짧고 깔끔해서 신규 서비스에서 자주 선택되는 방식입니다.

Redirect Rules로 리다이렉트 설정#

Cloudflare의 Rules 엔진에서 Redirect 타입 규칙을 사용해서 www ↔ Apex 리다이렉트를 설정합니다.

설정 순서:

1. Cloudflare Dashboard → Websites 선택
2. 도메인 선택 (example.com)
3. 왼쪽 메뉴에서 Rules → Overview 이동
4. Create rule 클릭 후, Rule type에서 Redirect Rules 선택
5. Redirect from WWW to root에서 Preview template 클릭

www → Apex 리다이렉트 규칙#

1
Rule name: Redirect from WWW to root (your-site)
2

3
If incoming requests match:
4
  Type: Wildcard pattern
5
  Request URL: https://www.your-site.com/*
6

7
Then:
8
  Redirect to:
9
    Target URL: https://your-site.com/${1}
10
    Status code: 301
11
    Preserve query string: ✓
12

13
Place at:
14
  Order: Last

설명:

• https://www.your-site.com/*
  • www.your-site.com으로 들어오는 모든 요청을 매칭합니다.
• ${1}
  • / 이후의 경로 전체를 그대로 캡처합니다.
• 결과 예시:
  • https://www.example.com/blog/post
  • → https://example.com/blog/post
• 301 (Permanent Redirect)
  • 검색 엔진에 영구적인 주소 변경임을 명확히 알립니다.
• Preserve query string
  • 쿼리 파라미터를 유지합니다.
  • 예:
    • https://www.example.com/search?q=test
    • → https://example.com/search?q=test

Apex → www 리다이렉트 규칙 (대안)#

만약 www를 메인으로 사용하고 싶다면:

1
Rule name: Redirect from root to WWW (your-site)
2

3
If incoming requests match:
4
  Type: Wildcard pattern
5
  Request URL: https://your-site.com/*
6

7
Then:
8
  Redirect to:
9
    Target URL: https://www.your-site.com/${1}
10
    Status code: 301
11
    Preserve query string: ✓
12

13
Place at:
14
  Order: Last

리다이렉트 테스트#

설정이 완료되면 반드시 테스트해야 합니다:

1
# curl로 리다이렉트 확인
2
curl -I https://www.example.com
3

4
# 응답 예시
5
HTTP/2 301
6
location: https://example.com/

브라우저에서도 확인해보세요:

1. www.example.com 접속
2. 주소창이 example.com으로 변경되는지 확인
3. /blog 같은 하위 경로도 테스트

Google Search Console에 등록#

리다이렉트를 설정했으면 Google Search Console에도 반영해야 합니다.

1. Google Search Console 접속
2. 속성 추가
3. Domain Property로 등록하면 apex와 www를 함께 관리할 수 있습니다.

이렇게 하면 검색 엔진이 단일 기준 도메인을 명확히 인식할 수 있습니다.

Production vs Preview 환경 분리#

Cloudflare Pages는 Production과 Preview 환경을 분리해서 관리할 수 있습니다.

1
Production 환경:
2
  - main 브랜치 배포
3
  - 실제 사용자가 접속
4
  - 프로덕션 API 서버 사용
5
  - 실제 결제 시스템 연동
6

7
Preview 환경:
8
  - PR 배포
9
  - 테스트 용도
10
  - 스테이징 API 서버 사용
11
  - 테스트 결제 시스템 연동

환경변수 추가하기#

1. Cloudflare Pages 프로젝트 → Settings 탭
2. Variables and Secrets 섹션
3. +Add 클릭
4. Type, Variable name, Value 입력 후, Save 클릭
5. 변경 사항은 다음 배포부터 적용됩니다

Production 환경변수 설정#

Production과 Preview는 각각 별도의 Variables and Secrets를 가질 수 있습니다.
먼저 상단의 환경 선택에서 Production 또는 Preview를 선택한 뒤, 같은 방식으로 변수를 각각 추가합니다.
이렇게 하면 Production과 Preview가 각각 다른 API 서버를 사용합니다.

프레임워크별 환경변수 사용법#

Vite (React, Vue, Svelte):

1
// vite.config.js - 설정 불필요, 자동으로 주입됨
2

3
// 코드에서 사용
4
const apiUrl = import.meta.env.VITE_API_URL;
5

6
console.log(apiUrl);
7
// Production: https://api.example.com
8
// Preview: https://staging-api.example.com

Next.js:

1
Next.js에서는 `NEXT_PUBLIC_` 접두사가 붙은 환경변수는
2
별도 설정 없이 자동으로 주입됩니다.

Astro:

1
// astro.config.mjs - 설정 불필요
2

3
// 코드에서 사용
4
const apiUrl = import.meta.env.PUBLIC_API_URL;

SvelteKit:

1
// 코드에서 사용
2
import { PUBLIC_API_URL } from "$env/static/public";
3

4
const apiUrl = PUBLIC_API_URL;

환경변수 명명 규칙#

프레임워크마다 환경변수 접두사가 다릅니다:

1
Vite: VITE_
2
Next.js: NEXT_PUBLIC_
3
Astro: PUBLIC_
4
SvelteKit: PUBLIC_
5
Nuxt: NUXT_PUBLIC_

접두사가 없는 환경변수는 클라이언트 코드에서는 접근할 수 없으며, Pages Functions 또는 서버 측 코드에서만 사용해야 합니다.
보안상 민감한 정보(서버 전용 API 키 등)는 클라이언트로 노출되지 않도록 접두사 없이 설정하고, 반드시 Pages Functions에서만 사용해야 합니다.

환경변수 적용 확인#

환경변수를 추가한 후에는 반드시 재배포가 필요합니다.

1
# 코드 변경 없이 재배포 트리거
2
git commit --allow-empty -m "Trigger rebuild for env vars"
3
git push origin main

빌드 로그에서 환경변수가 주입되는지 확인할 수 있습니다:

1
[Build] Environment variables:
2
VITE_API_URL=https://api.example.com (masked)
3
NODE_VERSION=18

민감한 값은 마스킹되어 표시됩니다.

의존성 캐싱#

Cloudflare Pages는 의존성 설치 결과를 캐싱하며, lock 파일이 변경되지 않으면 설치 단계를 건너뜁니다.

1
# 첫 번째 빌드
2
[Build] Installing dependencies...
3
npm install (34.2초)
4

5
# 두 번째 빌드 (package.json 변경 없음)
6
[Build] Using cached node_modules
7
Skipped npm install (0.5초)

최적화 팁:

• Lock 파일을 커밋하세요 (package-lock.json, pnpm-lock.yaml, yarn.lock)
• 불필요한 devDependencies 제거
• 정확한 버전 명시 (^1.0.0 대신 1.0.0)

Vite 빌드 최적화#

1
export default {
2
  build: {
3
    // 청크 크기 경고 임계값 조정
4
    chunkSizeWarningLimit: 1000,
5

6
    // 롤업 옵션
7
    rollupOptions: {
8
      output: {
9
        // 청크 분할 최적화
10
        manualChunks: {
11
          vendor: ["react", "react-dom"],
12
          ui: ["@mui/material"],
13
        },
14
      },
15
    },
16

17
    // 소스맵 비활성화 (프로덕션)
18
    sourcemap: false,
19
  },
20
};

Next.js 빌드 최적화#

1
module.exports = {
2
  // Static Export 설정
3
  output: "export",
4

5
  // 이미지 최적화 비활성화 (Static Export 필수)
6
  images: {
7
    unoptimized: true,
8
  },
9

10
  // 불필요한 파일 제외
11
  pageExtensions: ["tsx", "ts"],
12

13
  // 기본값 (명시적 설정)
14
  swcMinify: true,
15
};

Astro 빌드 최적화#

1
export default defineConfig({
2
  // 빌드 최적화
3
  build: {
4
    inlineStylesheets: "auto",
5
  },
6

7
  // Vite 설정
8
  vite: {
9
    build: {
10
      cssCodeSplit: true,
11
    },
12
  },
13
});

방법 1: Dashboard에서 초기화#

1. Deployments 탭
2. 최근 배포 선택
3. Retry deployment → Clear cache and retry

방법 2: 강제 재빌드#

이 방법은 의존성 설치 단계를 다시 실행하게 만들어 대부분의 캐시 문제를 해결할 수 있지만,
모든 캐시를 완전히 초기화하는 공식 방법은 아닙니다.

1
# package.json에 더미 필드 추가
2
{
3
  "cache-buster": "v2"  # 값을 변경해서 재빌드 트리거
4
}
5

6
git add package.json
7
git commit -m "Clear build cache"
8
git push origin main

공식 문서#

• Custom domains - 커스텀 도메인 상세
• Redirect Rules - 리다이렉트 설정
• Build configuration - 빌드 및 환경변수
• Environment variables - 환경변수 상세

프레임워크별 가이드#

• Vite on Pages
• Next.js on Pages
• Astro on Pages
• SvelteKit on Pages