Tech Notes

Cloudflare Pages로 정적 사이트 쉽게 배포하기 (Vite 기반 프로젝트)

miracle-tech 2025. 6. 29. 19:25
728x90
반응형

웹 개발자라면 한 번쯤은 내가 만든 프론트엔드 프로젝트를 인터넷에 바로 배포하고 싶다!는 생각을 해봤을 거예요. 오늘은 요즘 뜨고 있는 Cloudflare Pages(https://pages.cloudflare.com/)라는 플랫폼을 소개하면서,
Vite로 만든 프론트엔드 프로젝트를 어떻게 배포하는지 간단하게 알려드릴게요. 🚀

 

https://pages.cloudflare.com/

 

Cloudflare Pages란?

Cloudflare Pages는 정적 사이트를 배포하는 플랫폼입니다.
쉽게 말해, 여러분이 만든 HTML, CSS, JS 파일 같은 정적 파일들을 전 세계에 빠르게 배포할 수 있는 서비스예요.

  • 무료 플랜 지원
  • GitHub/GitLab 연동으로 자동 빌드 & 배포 가능
  • Cloudflare의 강력한 CDN 덕분에 빠른 로딩 속도
  • 서버리스 함수(Functions)도 지원해 동적 기능도 가능

Vite 프로젝트와 정적 사이트 배포

Vite는 빠르고 간단한 프론트엔드 개발 빌드 도구입니다.
React, Vue, Svelte 같은 프레임워크와 함께 자주 쓰여요.

  1. 로컬에서 개발 완료 후
  2. npm run build 명령을 실행하면
  3. dist라는 폴더 안에 최종 빌드된 정적 파일들(HTML, JS, CSS 등)이 생성됩니다.

Cloudflare Pages에 올리기

Cloudflare Pages는 이 dist 폴더 안의 정적 파일들을 서버에 올려서 인터넷에 서비스할 수 있게 해줘요.

  1. GitHub에 프로젝트를 올립니다.
  2. Cloudflare Pages에 GitHub 저장소를 연결합니다.
  3. 배포 설정에서 빌드 명령어(npm run build)와 빌드 결과물 경로(dist)를 지정합니다.
  4. Cloudflare가 자동으로 빌드를 수행하고, dist 안의 파일들을 전 세계에 배포합니다.
  5. 고유한 도메인 또는 커스텀 도메인으로 서비스 시작!

 

Example

Cloudflare Pages를 이용해서 Vite 기반 FrontEnd 정적 사이트를 배포해보았습니다.

 

Pages 를 선택하고 Git Repository에서 참조한다.

 

Deploy 하려는 repository를 선택한다.

 

배포 전에 ouput folder 위치 및 환경변수 설정을 한다.

 

위에서 Build output directory 의 위치는 vite.config.ts 내의 outDir 위치와 동일하게 해야한다.

vite.config.ts

 

Deploy가 성공했으며, url 이 생성되었다.

 

<참고> cloudflare 는 연결된 git repository에 push 가 되면 자동으로 빌드 & deploy 까지 된다.

 

마무리

Cloudflare Pages는 간단하면서도 강력한 무료 정적 사이트 배포 플랫폼입니다.
특히 Vite 같은 최신 빌드 도구와 조합하면, 빠르고 효율적으로 프론트엔드 프로젝트를 인터넷에 띄울 수 있죠.

여러분도 오늘 소개한 방법으로, 직접 만든 멋진 웹사이트를 손쉽게 전 세계에 공개해보세요!

 

배포 전 체크리스트

✅ vite.config.ts의 outDir와 Cloudflare 설정의 Build output directory가 일치하는지 확인

✅ React Router 등 SPA 라우팅 사용 시 public/_redirects 파일 추가

✅ 환경변수는 VITE_ 접두어 붙여서 등록

 

 

자주 발생하는 오류 & 해결법

1. 배포 후 빈 화면 or 404

: Build output directory 경로가 vite.config.ts의 build.outDir와 다를 때 발생해요.

 

// vite.config.ts
export default defineConfig({
  build: {
    outDir: 'dist'  // 이 값과
  }
})

// Cloudflare Pages 설정
// Build output directory: dist  ← 반드시 동일하게

 

2. /about 같은 경로 직접 접근 시 404

: public 폴더에 _redirects 파일을 만들고 아래 한 줄 추가하세요.

 

/* /index.html 200

 

3. 환경변수가 undefined로 나올 때

: Vite는 VITE_ 접두어가 없는 환경변수는 클라이언트에서 접근 불가해요.

Cloudflare Pages Settings → Environment variables에서도 동일하게 적용해야 합니다. 

// ❌ 안 됨: API_KEY=abc123
// ✅ 됨: VITE_API_KEY=abc123

 

🔗 관련 글

다른 배포 플랫폼이 궁금하다면 → [사이트 배포 플랫폼 총정리]

 

 다음에는 Cloudflare Workers로 서버리스 함수를 추가하는 방법을 다뤄볼게요. 정적 사이트에서도 API 키를 안전하게 처리하고 백엔드 기능을 붙일 수 있어요. 

 

 

 

 

 

 

728x90