cloudflare workers 배포 기초 정리

cloudflare workers 배포는 Wrangler CLI로 프로젝트를 준비하고 wrangler deploy를 실행하는 흐름으로 정리됩니다. 다만 설정 파일의 호환성 날짜, 환경 분리, 시크릿 주입, 롤백 절차를 미리 알아 두어야 운영 중 장애를 줄일 수 있어요. 이 글은 Cloudflare 공식 문서에서 확인한 범위만 가지고 배포 준비부터 검증과 되돌리기까지 순서대로 설명합니다.

한눈에 보기

Cloudflare Workers는 사용자와 가까운 엣지 네트워크에서 요청을 처리하는 서버리스 런타임입니다. 서버를 직접 띄우지 않고 코드 번들을 업로드하면, Cloudflare가 전 세계 위치에서 그 코드를 실행합니다. 백엔드 개발자 입장에서 중요한 변화는 “인스턴스를 배포한다”가 아니라 “번들을 업로드하고 라우팅을 연결한다”는 점입니다.

배포를 구성하는 요소는 크게 다음과 같습니다.

• 실행 코드: fetch 핸들러를 내보내는 진입점 파일입니다. 요청을 받아 응답을 반환하는 형태가 기본입니다.
• 배포 도구: Wrangler CLI가 표준 도구입니다. 프로젝트 생성, 로컬 실행, 배포, 로그 확인, 롤백을 모두 이 도구로 처리합니다.
• 설정 파일: wrangler.jsonc 또는 wrangler.toml에 Worker 이름, 진입점, 호환성 날짜, 라우팅, 바인딩을 기록합니다.
• 연결 자원: KV, R2, D1, Durable Objects 같은 저장소나 큐를 바인딩으로 붙입니다.
• 검증 수단: 대시보드의 배포 이력, wrangler tail의 실시간 로그, 실제 엔드포인트 호출이 기본 조합입니다.

즉 배포 자체는 명령 한 줄이지만, 안정적으로 운영하려면 설정 파일과 검증 절차를 함께 관리해야 합니다.

배포 방식 비교

Cloudflare는 같은 Worker를 여러 경로로 배포할 수 있습니다. 아래 표는 공식 문서에서 안내하는 방식들을 운영 관점에서 비교한 것입니다.

정리하면, 실제 운영 배포는 Wrangler CLI를 기준으로 잡고 Git 연동을 얹는 구성이 가장 흔합니다. 대시보드 편집기는 즉시 확인이 필요할 때 유용하지만, 설정 파일과 화면 상태가 어긋날 수 있으므로 상시 운영 경로로 두지는 않는 편이 좋습니다.

단계별 배포 방법

사전 준비

Cloudflare 계정과 Node.js 실행 환경을 준비합니다. Wrangler는 npm 패키지로 배포되므로 npx wrangler 형태로 바로 실행할 수 있습니다. 로컬과 CI에서 같은 버전을 쓰려면 개발 의존성으로 설치해 두는 편이 안전합니다.

로그인은 npx wrangler login으로 진행합니다. 브라우저가 열리고 OAuth 승인을 마치면 로컬에 인증 정보가 저장됩니다. 서버나 CI처럼 브라우저를 쓸 수 없는 환경에서는 API 토큰을 환경 변수로 주입하는 방식을 사용합니다.

프로젝트 생성

새 프로젝트는 npm create cloudflare@latest로 시작합니다. 대화형 안내를 따라 템플릿과 언어를 고르면 진입점 파일과 설정 파일이 함께 생성됩니다. 이미 운영 중인 Node 프로젝트가 있다면 Wrangler를 개발 의존성으로 추가하고 설정 파일만 직접 작성해도 됩니다.

이때 진입점 파일의 기본 형태를 확인해 두세요. export default { async fetch(request, env, ctx) { ... } } 구조로 요청을 받고 응답을 반환합니다. env에는 설정 파일에 선언한 바인딩과 변수가 들어오므로, 자원 접근은 이 객체를 통해 이루어집니다.

로컬 실행과 확인

배포 전에는 npx wrangler dev로 로컬에서 동작을 확인합니다. 로컬 런타임은 실제 Worker 환경과 유사하게 동작하므로, 라우팅과 응답 형식을 먼저 검증할 수 있습니다. 원격 자원과 붙여서 확인해야 하는 경우에는 원격 모드로 실행해 실제 바인딩 동작을 확인합니다.

로컬 확인 단계에서 자주 놓치는 것이 환경 변수입니다. .dev.vars 파일에 로컬용 값을 넣어 두면 배포용 시크릿과 분리해서 관리할 수 있습니다. 이 파일은 저장소에 커밋하지 않도록 무시 설정을 함께 넣어야 합니다.

설정 파일 점검

배포 전에 설정 파일을 반드시 확인합니다. 핵심 항목은 다음과 같습니다.

• name: Worker 이름이며 대시보드와 명령에서 이 이름으로 식별됩니다.
• main: 번들의 진입점 파일 경로입니다.
• compatibility_date: 런타임 호환성 기준 날짜입니다. 배포마다 임의로 바뀌지 않도록 고정합니다.
• compatibility_flags: 필요한 런타임 플래그를 명시합니다.
• vars: 일반 환경 변수입니다. 민감한 값은 여기에 넣지 않습니다.
• routes 또는 도메인 설정: 어떤 호스트와 경로로 이 Worker를 호출할지 정합니다.
• observability: 로그 수집 여부를 정합니다. 운영에서는 켜 두는 편이 좋습니다.

설정 파일은 JSONC 형식과 TOML 형식을 모두 지원합니다. 팀에서 이미 쓰는 형식이 있다면 하나로 통일해 혼선을 줄이세요.

배포 실행

준비가 끝났으면 npx wrangler deploy를 실행합니다. Wrangler가 코드를 번들로 묶고 Cloudflare로 업로드한 뒤, 설정된 라우팅에 연결합니다. 처음 배포하는 프로젝트라면 workers.dev 서브도메인이 함께 발급되어 바로 호출해 볼 수 있습니다.

번들 결과만 먼저 확인하고 싶다면 드라이런 옵션으로 배포 없이 검사할 수 있습니다. 크기가 커졌거나 의존성이 예상과 다르게 포함되었다면 이 단계에서 잡는 것이 좋습니다. 배포 명령은 실행 환경과 무관하게 동일하므로, 로컬과 CI 스크립트를 같은 형태로 유지할 수 있습니다.

배포 검증

배포 후에는 세 가지를 확인합니다. 첫째, 대시보드의 Workers & Pages 화면에서 배포가 완료로 표시되는지 봅니다. 둘째, npx wrangler deployments list로 배포 이력과 버전을 확인합니다. 셋째, npx wrangler tail로 실시간 로그를 열어 두고 실제 요청을 보내 응답과 예외를 확인합니다.

검증은 정상 응답만 보는 것으로 끝내지 마세요. 오류 응답 경로, 인증 실패 경로, 존재하지 않는 경로까지 함께 호출해 보면 라우팅 설정 실수를 초기에 발견할 수 있습니다.

롤백과 버전 관리

문제가 발견되면 이전 배포로 되돌립니다. npx wrangler rollback으로 직전 버전으로 복구할 수 있고, 대시보드의 배포 이력에서 특정 버전을 선택해 되돌릴 수도 있습니다. 버전 관리를 사용하면 배포본을 명시적으로 남기고 필요한 시점에 지정해 배포할 수 있습니다.

롤백이 빠르게 되는 것과 원인 파악이 빠른 것은 다릅니다. 롤백 직후에는 반드시 로그와 배포 이력을 함께 확인해 어떤 변경이 문제였는지 기록해 두세요.

상황별 선택

배포 구성은 서비스 형태에 따라 달라집니다.

• API만 제공하는 경우: Worker 하나에 라우팅을 두고, 데이터 저장소는 바인딩으로 연결합니다. 별도 서버가 필요 없어 구성이 단순합니다.
• 정적 자산과 API를 함께 제공하는 경우: 정적 자산 제공 기능을 설정에 함께 선언하고, 나머지 경로를 Worker가 처리하도록 구성합니다.
• 페이지 중심 사이트인 경우: Cloudflare Pages로 시작할 수도 있지만, 최근에는 Workers 쪽으로 기능이 모이는 흐름이므로 공식 문서의 안내를 확인하고 선택하세요.
• 스테이징과 프로덕션이 필요한 경우: 설정 파일의 환경 섹션으로 분리하고, 배포 명령에 환경 이름을 붙여 실행합니다. 환경마다 바인딩과 시크릿을 따로 지정해야 합니다.
• 시크릿이 필요한 경우: npx wrangler secret put으로 값을 등록합니다. 값은 저장소에 남지 않고 Cloudflare에 저장됩니다.
• CI에서 배포하는 경우: 공식 GitHub Action을 쓰거나 CI 스크립트에서 Wrangler를 실행합니다. 이때 인증은 API 토큰을 비밀 값으로 주입하는 방식을 사용합니다.

선택 기준은 “얼마나 자주 배포하는가”와 “환경을 몇 개나 두는가”입니다. 배포가 잦고 환경이 나뉜다면 자동화를 전제로 설계하는 편이 유지보수에 유리합니다.

주의할 점

• 호환성 날짜를 고정하세요. 이 값을 올리면 런타임 동작이 달라질 수 있으므로, 올릴 때는 별도 배포로 분리해 검증합니다.
• 시크릿을 설정 파일이나 코드에 넣지 마세요. 저장소에 남는 순간 교체 대상이 됩니다.
• workers.dev 주소를 외부에 공개할지 결정하세요. 커스텀 도메인만 쓰려면 접근 정책을 함께 검토합니다.
• 바인딩 이름을 코드와 설정에서 동일하게 유지하세요. 이름이 어긋나면 배포는 성공해도 런타임에서 실패합니다.
• 플랜에 따라 사용할 수 있는 기능과 한도가 다릅니다. 요청량이나 실행 시간이 큰 워크로드라면 공식 문서의 플랜별 안내를 먼저 확인하세요.
• 로그와 알림을 켜 두세요. 엣지에서 실행되는 코드는 로컬 재현이 어려운 경우가 많아 관측 수단이 사실상 유일한 단서입니다.
• 배포 후에는 반드시 실제 엔드포인트를 호출해 검증하세요. 배포 성공 표시와 서비스 정상은 다른 문제입니다.

자주 묻는 질문

로컬에서 잘 되던 코드가 배포 후 실패하는 이유는 무엇인가요?

가장 흔한 원인은 바인딩과 환경 변수 차이입니다. 로컬의 .dev.vars에만 있던 값이 배포 환경에는 없거나, 설정 파일의 바인딩 이름과 코드에서 참조하는 이름이 다를 수 있습니다. 배포 후 wrangler tail로 예외 메시지를 먼저 확인하세요.

배포한 Worker를 이전 버전으로 되돌릴 수 있나요?

가능합니다. Wrangler의 롤백 명령으로 직전 배포로 되돌리거나, 대시보드의 배포 이력에서 원하는 버전을 선택해 복구할 수 있습니다. 버전 관리를 사용하면 배포본을 명시적으로 관리하면서 특정 버전을 지정해 배포할 수 있습니다.

커스텀 도메인은 어떻게 연결하나요?

Cloudflare에서 관리하는 도메인이라면 설정 파일의 라우팅 항목이나 대시보드의 도메인 설정에서 호스트와 경로를 지정합니다. 도메인이 다른 등록기관에 있다면 네임서버 위임이 먼저 필요합니다. 연결 후에는 DNS 전파와 인증서 발급 상태를 함께 확인하세요.

시크릿과 일반 환경 변수는 어떻게 나눠 관리하나요?

민감하지 않은 값은 설정 파일의 변수 항목에, 민감한 값은 시크릿 등록 명령으로 관리합니다. 로컬 개발용 값은 별도 파일에 두고 저장소에는 포함하지 않습니다. 환경이 여러 개라면 환경별로 시크릿을 각각 등록해야 합니다.

배포 자동화는 어디서부터 시작하면 좋나요?

먼저 저장소에 설정 파일을 커밋하고, 로컬에서 쓰던 배포 명령을 그대로 CI 스크립트로 옮깁니다. 인증은 API 토큰을 비밀 값으로 주입하고, 배포 전에 드라이런으로 번들을 검사하는 단계를 넣으면 안전합니다. 이후 브랜치 전략과 환경을 연결해 자동 배포 범위를 정하세요.

출처

• Cloudflare Workers 시작 가이드: https://developers.cloudflare.com/workers/get-started/guide/
• Wrangler 명령 참조: https://developers.cloudflare.com/workers/wrangler/
• Wrangler 설정 파일 레퍼런스: https://developers.cloudflare.com/workers/configuration/wrangler-configuration/
• Workers CI/CD 안내: https://developers.cloudflare.com/workers/ci-cd/
• Workers 개요: https://developers.cloudflare.com/workers/

배포 이후 운영 단계에서 자주 부딪히는 문제는 대개 설정과 관측의 부재에서 나옵니다. 환경 변수와 시크릿을 분리하는 방법, 로그를 남기는 습관, 롤백 절차를 팀 규칙으로 정리해 두고 싶다면 함께 보면 좋은 글로 Cloudflare Workers 환경 변수와 시크릿 관리를 준비해 두었습니다.