Cloudflare Workers Wrangler 설정 파일 가이드

wrangler.jsonc 파일은 Cloudflare Workers를 배포하고 관리하기 위한 구성 파일입니다. 이 파일은 Cloudflare의 CDN 네트워크에서 실행되는 서버리스 함수를 설정하고 배포하는 데 필요한 모든 정보를 포함합니다.

 

 

주요 구성 요소

속성설명

main	Worker의 진입점이 되는 TypeScript 파일 경로
name	Cloudflare에 배포될 때 사용될 Worker의 고유 이름
compatibility_date	Worker가 작동할 때 사용할 Cloudflare API의 호환성 날짜
assets.not_found_handling	존재하지 않는 경로 요청 시 SPA(Single Page Application) 방식으로 처리
observability.enabled	성능 및 요청 로그 수집 기능 활성화

 

 

주요 기능

SPA 라우팅 지원: 사용자가 앱 내 다른 경로로 직접 접근하더라도 앱이 정상적으로 로드됨
모니터링 활성화: 요청, 성능, 오류 등에 대한 로그 수집
정적 에셋 서비스: HTML/CSS/JS 파일들을 Cloudflare CDN을 통해 제공

 

1. 필수 설치
bash
npm install -g wrangler

2. Cloudflare 계정 설정
bash
wrangler login
배포 방법
개발 환경에서 테스트
bash
# 로컬에서 개발 서버 시작
wrangler dev

# 로컬에서 assets만 제공하는 경우
wrangler pages dev ./dist
실제 배포
bash
# Cloudflare에 배포
wrangler deploy
자주 사용하는 명령어
명령어 설명
wrangler dev 로컬 개발 환경에서 Worker 실행
wrangler deploy Cloudflare에 Worker 배포
wrangler tail 실시간 로그 스트리밍
wrangler whoami 현재 로그인된 계정 확인

 

설정 변경 시 유의사항
compatibility_date: Cloudflare가 새로운 기능을 출시할 때마다 업데이트해야 합니다
name: 이미 사용 중인 이름이라면 배포가 실패할 수 있으므로 고유한 이름을 사용하세요
assets.not_found_handling: 일반 웹사이트가 아닌 SPA 앱에만 적합합니다

 

유지보수 팁
버전 관리: wrangler.jsonc 파일은 Git에 함께 커밋하세요
환경 변수: 민감한 정보는 .dev.vars 파일이나 Cloudflare 대시보드에서 관리하세요
성능 모니터링: observability 기능을 통해 앱 성능을 지속적으로 확인하세요
이 설정은 Vite + Material UI 기반의 관리자 대시보드를 Cloudflare Workers에서 실행하기 위한 최적화된 구성입니다.