테마
Cloudflare 환경변수와 배포
학습 목표
- 환경변수가 왜 필요한지, 없으면 어떤 문제가 생기는지 설명할 수 있다.
- Cloudflare 대시보드에서 환경변수를 설정할 수 있다.
- Github push부터 자동 배포까지의 CI/CD 파이프라인을 이해한다.
- 배포 상태를 확인하고 문제를 진단할 수 있다.
왜 환경변수가 필요한가?
이전 챕터에서 API KEY를 코드에 직접 넣으면 위험하다고 배웠다. 그렇다면 API KEY는 어디에 저장해야 할까? 바로 **환경변수(Environment Variables)**이다.
환경변수 = 코드 바깥에 저장하는 설정값
환경변수는 서버 환경에 별도로 저장되며, 코드에서는 이름만 참조하여 값을 가져온다. 코드를 공개해도 환경변수의 실제 값은 노출되지 않는다.
코드에서의 차이
| 방식 | 코드 예시 | 보안 |
|---|---|---|
| 직접 삽입 (위험) | const key = "abc123xyz" | 코드를 보면 KEY 노출 |
| 환경변수 (안전) | const key = process.env.SUPABASE_KEY | 코드에는 이름만 표시 |
핵심: 환경변수의 이름은 임의로 설정 가능하다. 단, 코드에서 참조하는 이름과 반드시 동일해야 한다. 또한 모든 값이 비밀값은 아니다. 예를 들어 Supabase anon/publishable 키는 공개 가능한 키지만, 외부 API KEY나
service_role키는 반드시 비공개로 관리해야 한다.
Cloudflare 환경변수 설정 방법
설정 과정
- Cloudflare 대시보드 접속 (dash.cloudflare.com)
- 좌측 메뉴에서 Workers 및 Pages 클릭
- 배포된 프로젝트 이름 클릭
- 상단 설정(Settings) 탭 클릭
- 환경 변수(Environment Variables) 섹션 찾기
- 변수 추가 클릭
- 이름과 값 입력 후 저장
공개 가능한 값과 비밀값 구분
| 변수 예시 | 공개 가능 여부 | 저장 위치 예시 | 용도 |
|---|---|---|---|
NEXT_PUBLIC_SUPABASE_URL | 공개 가능 | .env.local, 배포용 공개 env | 브라우저에서 Supabase 프로젝트 URL 참조 |
NEXT_PUBLIC_SUPABASE_ANON_KEY | 공개 가능 | .env.local, 배포용 공개 env | 브라우저에서 Edge Function invoke 또는 Supabase client 구성 |
WEATHER_API_KEY | 비공개 | Supabase secrets, Cloudflare 서버 env | 외부 API 호출 |
SUPABASE_SERVICE_ROLE_KEY | 비공개 | 서버 환경변수만 사용 | 관리자 권한 작업 |
팁: 브라우저에서 직접 읽는 값은 프레임워크의 공개 env 규칙을 따라야 한다. Next.js에서는 일반적으로
NEXT_PUBLIC_접두사를 사용하고, 비밀값은 절대 그 접두사를 붙이지 않는다.
자동 배포 파이프라인
개발 환경 세팅 챕터에서 Cloudflare와 Github을 연결했다. 이 연결 덕분에 **자동 배포 파이프라인(CI/CD)**이 동작한다.
파이프라인 단계별 설명
| 단계 | 수행자 | 내용 | 소요 시간 |
|---|---|---|---|
| 1 | 개발자 | Cursor에서 코드 수정 | - |
| 2 | 개발자 | Github Desktop에서 commit 작성 | 1분 |
| 3 | 개발자 | Push 클릭 | 수 초 |
| 4 | Cloudflare | 변경 감지 → 빌드 시작 | 자동 |
| 5 | Cloudflare | npm run build 실행 | 1~3분 |
| 6 | Cloudflare | 전 세계 서버에 배포 | 수 초 |
| 7 | 사용자 | 최신 버전 사이트 접속 | 즉시 |
핵심: 개발자가 하는 일은 코드 수정 → commit → push 3단계뿐이다. 나머지는 전부 Cloudflare가 자동으로 처리한다.
배포 상태 확인
대시보드에서 확인
- Cloudflare 대시보드 → Workers 및 Pages → 프로젝트 선택
- 배포(Deployments) 탭 클릭
- 최신 배포의 상태 확인
배포 상태 종류
| 상태 | 의미 | 대응 |
|---|---|---|
| Success | 빌드 및 배포 성공 | 사이트 정상 동작 확인 |
| Failed | 빌드 실패 | 에러 로그 확인 후 코드 수정 |
| In Progress | 빌드 진행 중 | 잠시 대기 |
빌드 실패 시 대처법
빌드가 실패하면 당황하지 않아도 된다. 이전 성공 배포가 유지되기 때문에 사이트는 계속 정상 동작한다.
- Cloudflare 배포 로그에서 에러 메시지 확인
- 에러 메시지를 Cursor AI에게 전달
- AI가 수정한 코드를 다시 commit → push
- Cloudflare가 다시 자동 빌드/배포
팁: 빌드 에러의 대부분은 오타, 누락된 의존성, 환경변수 미설정 중 하나이다. 에러 메시지를 읽고 원인을 파악하거나, 그대로 Cursor AI에게 붙여넣으면 해결 방법을 알려준다.
로컬 개발과 환경변수
로컬 개발에서 어떤 파일을 쓰는지는 실행 방식에 따라 달라진다. Next.js 개발 서버와 Wrangler 기반 Cloudflare 미리보기는 환경변수를 읽는 방식이 서로 다를 수 있다.
.env.local 예시 (일반적인 npm run dev)
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=sb_publishable_xxxxxxxxx.dev.vars 예시 (Wrangler/Cloudflare 바인딩 테스트)
WEATHER_API_KEY=your-secret-key
SUPABASE_SERVICE_ROLE_KEY=your-server-only-key| 환경 | 환경변수 위치 | 적용 시점 |
|---|---|---|
| 일반 로컬 개발 | .env.local | npm run dev 같은 Next.js 개발 서버 실행 시 |
| Cloudflare 바인딩 로컬 테스트 | .dev.vars | wrangler dev 또는 Cloudflare 런타임 미리보기 시 |
| 배포(프로덕션) | Cloudflare 대시보드 / Supabase secrets | push 후 빌드 및 런타임 적용 시 |
중요:
.env.local과.dev.vars는 모두 절대 Github에 올리지 않는다..gitignore에 반드시 포함되어 있어야 한다.
전체 배포 체크리스트
배포 전 아래 항목을 하나씩 확인한다.
| 순서 | 확인 항목 | 확인 방법 |
|---|---|---|
| 1 | 로컬에서 정상 동작 | npm run dev 실행 후 브라우저 확인 |
| 2 | 빌드 성공 | npm run build 에러 없이 완료 |
| 3 | 환경변수 등록 | Cloudflare 대시보드에서 확인 |
| 4 | Github push | Github Desktop에서 commit → push |
| 5 | 배포 성공 | Cloudflare 대시보드에서 Success 확인 |
| 6 | 사이트 정상 접속 | 프로젝트.pages.dev 주소로 접속 |
핵심 정리
| 순서 | 할 일 | 결과 |
|---|---|---|
| 1 | 공개 가능한 값과 비밀값을 먼저 구분 | 키 보안 모델이 명확해짐 |
| 2 | 로컬 실행 방식에 맞게 .env.local 또는 .dev.vars 설정 | 로컬 개발과 미리보기 환경이 일관됨 |
| 3 | 코드 수정 → commit → push | 자동 배포 트리거 |
| 4 | Cloudflare 대시보드와 Supabase secrets에서 런타임 설정 확인 | 사이트 정상 공개 |
축하: 여기까지 완료했다면, AI로 만든 웹사이트가 실제로 세상에 공개된 것이다! 이제 이 사이트에 구글 애드센스를 연동하여 수익을 창출하는 단계로 넘어갈 준비가 되었다.