초보자도 따라하는 웹서비스 배포 (1) - Cloudflare Workers(pages), Sveltekit (Svelte5)로 배포하기

🎯 이 가이드로 배울 수 있는 것

  • SvelteKit 5 프로젝트 생성 및 설정
  • Cloudflare 어댑터 설치 및 구성
  • GitHub 저장소 설정 및 코드 푸시
  • Cloudflare Pages를 통한 자동 배포 설정
  • 배포 후 확인 및 디버깅

📋 사전 준비사항

이 가이드를 시작하기 전에 다음이 설치되어 있다고 가정합니다:

  • Node.js (v18 이상 권장)
  • IDE (VS Code, Cursor, Windsurf 등)
  • Git (버전 관리용)
  • GitHub 계정
  • Cloudflare 계정 (무료)

개발 환경은 Windows와 macOS 모두 지원되며, 필요한 곳에서 각 OS별 명령어를 제공합니다.

🚀 1단계: SvelteKit 5 프로젝트 생성

먼저 새로운 SvelteKit 프로젝트를 생성합니다. 2025년 현재 Svelte 5가 정식 출시되어 최신 기능들을 사용할 수 있습니다.

개발 에디터(IDE) 열기

  1. VS Code나 Cursor, Windsurf를 엽니다.
  2. Open project 버튼을 눌러 탐색기를 열고
  3. 원하는 프로젝트의 이름으로 폴더를 하나 만드세요 (ex. my-service)
  4. 만든 폴더를 선택하고 열어줍니다.
  5. 열린 개발 에디터의 하단에 터미널이 열려 있는지 확인
    1. 열려있지 않다면 최상단 Terminal → New Terminal
    2. 그래도 안보인다면 View에서 터미널 패널을 켜주세요

프로젝트 생성

터미널을 열고 다음 명령어를 실행합니다:

npx sv create ./

여기서 ./는 현재 폴더(디렉토리)를 뜻합니다. ./ 부분을 다른 텍스트로 변경시 새 디렉토리가 생성되고 해당 폴더 내에 Sveltekit 프로젝트가 설치됩니다.

그리고 설치도우미가 여러가지를 물어봅니다.
아래의 상황을 따라주세요. 최소한의 선택지만 선택합니다.

  • Template: SvelteKit minimal로 선택
  • TypeScript: TypeScript를 선택
  • Add-ons: prettier, tailwindcss, sveltekit-adapter를 스페이스바로 체크해 선택
  • Typography: typography를 체크해서 선택
  • Adapter: cloudflare로 선택
  • Package manager: npm을 선택

모두 선택했으면 npm install을 자동으로 실행이 되어
스벨트킷 프로젝트가 설치됩니다.

어댑터(Adapter)는 무엇인가요?

어댑터는 SvelteKit 앱을 배포 대상에 맞게 적응시키는 작은 플러그인입니다. 빌드된 앱을 입력으로 받아서 배포용 출력물을 생성합니다.

쉽게 말해서, SvelteKit으로 만든 웹앱을 다양한 플랫폼(Cloudflare, Vercel, Netlify 등)에 배포할 수 있도록 변환해주는 도구입니다.

  • @sveltejs/adapter-cloudflare: Cloudflare Workers와 Cloudflare Pages용
  • @sveltejs/adapter-vercel: Vercel용 (Vercel이라는 서비스용입니다.)
  • @sveltejs/adapter-static: 정적 사이트용 (다용도로 쓸 수 있습니다. Capacitor나 Tauri를 통해 앱 만들 때 사용하기도 합니다.)

Tailwind CSS는 무엇인가요?

Tailwind CSS는 유틸리티 우선(utility-first) CSS 프레임워크입니다. 미리 정의된 클래스들을 HTML에서 직접 사용하여 빠르게 스타일링할 수 있게 해줍니다.

전통적인 CSS 방식:

.button {
  background-color: blue;
  color: white;
  padding: 8px 16px;
  border-radius: 4px;
}

Tailwind CSS 방식:

<button class="bg-blue-500 text-white px-4 py-2 rounded">
  클릭하세요
</button>

🔧 2단계: Cloudflare 어댑터 확인 및 설정

프로젝트 생성 시 Cloudflare 어댑터를 선택했다면 이미 설치되어 있습니다. 확인해보겠습니다.

어댑터 설치 확인

package.json 파일을 열어서 다음이 있는지 확인하세요:

{
  "devDependencies": {
    "@sveltejs/adapter-cloudflare": "^7.0.3"
  }
}

svelte.config.js 설정 확인

프로젝트 루트의 svelte.config.js 파일을 확인하세요:

import adapter from '@sveltejs/adapter-cloudflare';

/** @type {import('@sveltejs/kit').Config} */
const config = {
  kit: {
    adapter: adapter()
  }
};

export default config;

만약 어댑터가 설치되지 않았다면

터미널에서 수동으로 설치하세요:

# Windows/macOS 공통
npm install -D @sveltejs/adapter-cloudflare

🏗️ 3단계: 개발 서버 실행 및 테스트

개발 서버 시작

# Windows/macOS 공통
npm run dev

또는 포트를 지정하여 실행 (선택사항입니다) :

# Windows/macOS 공통  
npm run dev -- --port 3000

브라우저에서 http://localhost:5173 (또는 지정한 포트)로 접속하여 사이트가 정상 작동하는지 확인하세요.

📁 4단계: GitHub 저장소 설정

새 GitHub 저장소 생성

  1. New 버튼을 눌러 새 저장소를 생성합니다
  2. Repository name 저장소 이름을 입력하고
    1. 앞서 사용한 폴더 이름과 동일하면 좋습니다.
  4. (중요) Public이 아닌 Private로 해야합니다!
  5. Create repository 클릭
  6. 저장소 URL을 복사해 둡니다

내 프로젝트를 GitHub에 업로드

VS Code나 IDE에서 SOURCE CONTROL 패널을 이용하거나,
터미널을 사용할 수 있습니다.

방법 1: VS Code SOURCE CONTROL 사용 (쉬움)

  1. 복사한 저장소 URL을 준비해 둡니다
  2. VS Code 좌측 SOURCE CONTROL 패널 클릭 (Git 아이콘)
  3. Initialize Repository 버튼 클릭
  4. 모든 파일이 변경사항으로 나타나면 + 버튼으로 모든 파일 스테이징
  5. 커밋 메시지 입력 (예: "Initial commit")
  6. Commit 버튼 클릭
  7. Publish to GitHub (Publish Branch) 버튼 클릭
  8. GitHub 계정 연동 후 저장소 선택

근데 가끔 꼬여서 안먹힐 경우가 있습니다. 아래에 터미널을 사용해서 해결해도 되지만 GUI를 사용해 해결할 수도 있습니다.

만약 Publish to GitHub가 안 될 경우:

  • SOURCE CONTROL 패널에서 ... (더보기) 메뉴 클릭
  • Remote > Add Remote... 선택
  • 복사해둔 GitHub 저장소 URL 입력
  • Remote 이름을 origin으로 설정
  • 다시 Push 또는 Sync Changes 버튼 클릭

방법 2: 터미널 명령어 사용 (귀찮음)

프로젝트 루트 디렉토리에서 다음 명령어를 실행하세요:

# Windows/macOS 공통
git init
git add .
git commit -m "Initial commit"

# 원격 저장소 연결 (YOUR_USERNAME과 YOUR_REPO_NAME을 실제 값으로 변경)
git remote add origin https://github.com/YOUR_USERNAME/YOUR_REPO_NAME.git

# main 브랜치로 푸시
git branch -M main
git push -u origin main

☁️ 5단계: Cloudflare Pages 프로젝트 설정

Cloudflare Pages에서 프로젝트 생성

  1. Cloudflare 대시보드에 로그인
  2. Workers & Pages 섹션으로 이동
  3. Create 버튼 클릭
  4. Pages 탭 선택
  5. Connect to Git 선택

GitHub 연동 설정

  1. Connect to Git 선택
  2. GitHub 계정 인증 (처음 연동 시)
  3. 앞서 생성한 저장소 선택
  4. Begin setup 클릭

빌드 설정 구성

Cloudflare Pages에서 SvelteKit 프로젝트의 빌드 설정을 다음과 같이 구성하세요:

  • Framework preset: SvelteKit
  • Build command: npm run build
  • Build output directory: .svelte-kit/cloudflare
  • Root directory: / (루트)
  • Node.js version: 18

배포 시작

모든 설정을 완료한 후 Save and Deploy 버튼을 클릭합니다.

🚀 6단계: 배포 확인 및 자동 배포 설정

첫 배포 모니터링

  1. 배포 로그를 실시간으로 확인할 수 있습니다
  2. 빌드가 완료되면 고유한 URL을 받게 됩니다 (예: your-project.pages.dev)
  3. 배포 완료 후 URL로 접속하여 사이트 확인

자동 배포 확인

Cloudflare Pages는 연결된 GitHub 저장소에 변경사항을 푸시할 때마다 자동으로 배포합니다.

🔧 7단계: 커스텀 도메인 설정 (선택사항)

도메인 추가

  1. Cloudflare Pages 프로젝트 설정에서 Custom domains 탭
  2. Set up a custom domain 클릭
  3. 도메인 입력 후 Activate domain 클릭
  4. DNS 설정이 자동으로 구성됩니다

🐛 문제 해결

빌드 실패 시

  1. 로그 확인: Cloudflare Pages 대시보드에서 빌드 로그 확인
  2. 로컬 빌드: npm run build로 로컬에서 빌드 테스트
  3. Node.js 버전: Cloudflare에서 Node.js 버전 확인

어댑터 관련 문제

2025년 5월 업데이트로 Cloudflare 어댑터가
Workers, Pages 두개 있었는데, 하나로 통합됐습니다.

환경 변수 문제

SvelteKit에서 환경 변수 사용법

SvelteKit은 환경 변수를 두 가지 타입으로 구분합니다:

  1. Public 환경 변수: PUBLIC_ 접두사가 붙고, 클라이언트에서도 접근 가능
  2. Private 환경 변수: 서버에서만 접근 가능

보안이 필요한 여부에 따라 나눠서 사용하면됩니다.

SvelteKit의 내장 $env 모듈을 사용하는 것이 권장됩니다:

// src/lib/config.js
import { PUBLIC_API_URL } from '$env/static/public';
import { PRIVATE_API_KEY } from '$env/static/private';

// 사용 예시
export const config = {
  apiUrl: PUBLIC_API_URL || 'http://localhost:3000',
  // PRIVATE_API_KEY는 서버에서만 사용 가능
};

환경 변수 파일 설정 (.env)

# .env 파일 (로컬 개발용)
PUBLIC_API_URL=https://api.example.com
PRIVATE_DATABASE_URL=postgresql://user:pass@localhost:5432/db

🎉 완료!

축하합니다! 이제 다음이 모두 설정되었습니다:

  • ✅ SvelteKit 5 프로젝트 생성
  • ✅ Cloudflare 어댑터 설정
  • ✅ GitHub 저장소 연동
  • ✅ Cloudflare Pages 자동 배포
  • ✅ 커스텀 도메인 (선택사항)

🔗 유용한 링크

오소리
오소리
꿀통을 찾아다니는 오소리입니다.
작성자 글 모아보기
©YozmBlog
koenjaesfr