Wrangler로 Cloudflare 개발하기

Cloudflare Workers로 서버리스 애플리케이션을 개발해보신 분이라면 Wrangler라는 CLI 도구를 한 번쯤 써보셨을 거예요. 프로젝트 생성부터 로컬 개발 서버, 배포까지 터미널 하나로 해결할 수 있거든요.

그런데 Wrangler는 단순히 Workers를 배포하는 도구가 아닙니다. KV, R2, D1 같은 Cloudflare 서비스도 관리할 수 있고 환경별 설정 분리나 시크릿 관리 기능까지 갖추고 있어요.

이번 글에서는 Wrangler CLI를 실무에서 제대로 활용하는 방법을 살펴보겠습니다. Cloudflare Workers 자체가 궁금하신 분은 Cloudflare Workers로 서버리스 애플리케이션 만들기를 먼저 읽어보시면 좋습니다.

Wrangler란?

Wrangler는 Cloudflare에서 공식 제공하는 CLI 도구입니다. Workers뿐 아니라 KV, R2, D1, Queues, Vectorize, Hyperdrive 등 Cloudflare의 거의 모든 개발자 제품을 터미널에서 다룰 수 있어요.

어떤 일을 할 수 있는지 간단히 살펴볼게요.

프로젝트 초기화 — 템플릿 기반으로 Worker 프로젝트를 빠르게 생성
로컬 개발 — Miniflare 기반의 로컬 서버로 프로덕션과 동일한 환경에서 테스트
배포 — 명령어 하나로 전 세계 엣지에 코드 배포
리소스 관리 — KV 네임스페이스, R2 버킷, D1 데이터베이스를 CLI에서 직접 생성하고 조작
시크릿 관리 — API 키 같은 민감한 값을 안전하게 설정
타입 생성 — 바인딩 설정에 맞는 TypeScript 타입을 자동 생성

설치

Wrangler는 프로젝트별로 로컬 설치하는 게 좋습니다. 팀원 모두 같은 버전을 쓸 수 있고 프로젝트마다 다른 버전을 관리하기도 편하거든요.

npm을 쓴다면 이렇게 설치합니다.

npm install -D wrangler

Bun을 쓰고 계시다면요.

bun add -D wrangler

설치 후 버전을 확인해봅시다.

npx wrangler --version

결과

 ⛅️ wrangler 4.54.0

이미 설치되어 있다면 최신 버전으로 업데이트해두세요.

npm install -D wrangler@latest

참고로 Wrangler는 Node.js 18 이상이 필요합니다. Volta나 nvm 같은 노드 버전 관리자를 쓰면 버전 충돌을 피할 수 있어요.

인증

Wrangler를 쓰려면 Cloudflare 계정으로 인증해야 합니다. wrangler login을 실행하면 브라우저가 열리면서 OAuth 인증이 진행돼요.

npx wrangler login

인증이 끝나면 wrangler whoami로 현재 로그인 상태를 확인할 수 있습니다.

npx wrangler whoami

결과

 ⛅️ wrangler 4.54.0
───────────────────
Getting User settings...
👋 You are logged in with an OAuth Token, associated with the email dale@example.com.
┌──────────────────────┬──────────────────────────────────┐
│ Account Name         │ Account ID                       │
├──────────────────────┼──────────────────────────────────┤
│ Dale's Account       │ a1b2c3d4e5f6g7h8i9j0...         │
└──────────────────────┴──────────────────────────────────┘

CI/CD 환경처럼 브라우저를 띄울 수 없는 곳에서는 CLOUDFLARE_API_TOKEN 환경 변수로 인증할 수도 있습니다.

설정 파일

Wrangler는 프로젝트 루트의 설정 파일에서 Worker의 이름, 진입점, 바인딩 정보 등을 읽습니다. TOML(wrangler.toml)과 JSON(wrangler.jsonc) 두 가지 포맷을 지원하는데 새 프로젝트에서는 wrangler.jsonc를 권장합니다. 일부 신규 기능이 JSON 설정에서만 지원되기도 하고 JSON Schema 덕분에 에디터 자동 완성도 잘 되거든요.

가장 기본적인 설정 파일을 보겠습니다.

wrangler.jsonc

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-02-01"
}

각 필드가 하는 일을 살펴볼게요.

$schema — JSON Schema를 지정해서 에디터 자동 완성과 유효성 검사를 활성화
name — Worker의 이름이자 기본 배포 URL의 서브도메인 (my-worker.<subdomain>.workers.dev)
main — Worker의 진입점 파일 경로
compatibility_date — Workers 런타임 버전을 결정하는 날짜. 30일 이내로 유지하는 게 좋습니다

여기에 환경 변수나 바인딩, 라우팅 같은 설정을 더 넣을 수 있어요.

wrangler.jsonc

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-02-01",
  "vars": {
    "ENVIRONMENT": "production",
    "API_VERSION": "v2"
  },
  "kv_namespaces": [
    {
      "binding": "MY_KV",
      "id": "abc123..."
    }
  ],
  "r2_buckets": [
    {
      "binding": "MY_BUCKET",
      "bucket_name": "my-files"
    }
  ],
  "d1_databases": [
    {
      "binding": "MY_DB",
      "database_name": "my-database",
      "database_id": "xyz789..."
    }
  ]
}

이렇게 정의한 바인딩은 Worker 코드에서 env 객체를 통해 접근할 수 있습니다.

환경 분리

실제 프로젝트에서는 스테이징과 프로덕션 환경을 분리해야 할 때가 많죠. Wrangler는 설정 파일 안에서 환경별로 다른 값을 지정할 수 있습니다.

wrangler.jsonc

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-02-01",
  "vars": {
    "ENVIRONMENT": "production"
  },
  "env": {
    "staging": {
      "vars": {
        "ENVIRONMENT": "staging"
      },
      "kv_namespaces": [
        {
          "binding": "MY_KV",
          "id": "staging-kv-id..."
        }
      ]
    }
  }
}

스테이징 환경에 배포할 때는 --env 플래그를 씁니다.

npx wrangler deploy --env staging

name이나 main, compatibility_date 같은 기본 설정은 상위에서 상속됩니다. 반면 vars나 kv_namespaces 같은 바인딩은 환경마다 다시 정의해줘야 해요. 프로덕션 KV에 스테이징 데이터가 섞이는 사고를 막기 위한 안전장치라고 보시면 됩니다.

핵심 명령어

Wrangler가 제공하는 명령어는 꽤 많지만 실제로 자주 쓰는 것 위주로 정리해볼게요.

프로젝트 생성

새 Worker 프로젝트를 만들 때는 wrangler init을 씁니다.

npx wrangler init my-worker

대화형 프롬프트가 나타나면서 템플릿 종류, 언어, Git 초기화 여부 등을 선택할 수 있습니다. TypeScript 템플릿을 고르면 wrangler.jsonc, tsconfig.json, src/index.ts가 포함된 프로젝트가 바로 만들어져요.

로컬 개발

wrangler dev는 로컬에서 Worker를 실행하는 명령어입니다.

npx wrangler dev

기본적으로 http://localhost:8787에서 Worker가 구동되고 파일을 수정하면 자동으로 다시 빌드됩니다. 내부적으로 Miniflare라는 로컬 시뮬레이터를 쓰는데 실제 Cloudflare Workers 런타임(workerd)을 그대로 돌리기 때문에 프로덕션과 거의 동일한 환경에서 테스트할 수 있어요.

KV, R2, D1 같은 바인딩도 로컬에서 시뮬레이션됩니다. 로컬 데이터는 프로젝트 내의 .wrangler/state 디렉토리에 저장되는데 이 폴더를 지우면 로컬 상태를 초기화할 수 있어요.

실제 Cloudflare 서비스에 연결해서 테스트하고 싶다면 --remote 플래그를 쓰면 됩니다.

npx wrangler dev --remote

배포

Worker를 Cloudflare 네트워크에 배포하려면 wrangler deploy를 씁니다.

npx wrangler deploy

결과

Total Upload: 0.19 KiB / gzip: 0.16 KiB
Uploaded my-worker (1.52 sec)
Deployed my-worker triggers (0.71 sec)
  https://my-worker.dale.workers.dev
Current Version ID: 8a3b2c1d-...

배포 전에 문제가 없는지 먼저 확인하고 싶다면 --dry-run 플래그가 유용해요. 실제 배포 없이 번들링까지만 수행해서 에러를 미리 잡을 수 있거든요.

npx wrangler deploy --dry-run

배포할 때 태그와 메시지를 남겨두면 나중에 어떤 배포인지 추적하기 편합니다.

npx wrangler deploy --tag "v1.2.0" --message "캐싱 로직 개선"

실시간 로그

배포된 Worker의 로그를 실시간으로 보려면 wrangler tail을 씁니다.

npx wrangler tail

프로덕션에서 발생하는 요청과 응답, 에러 메시지를 터미널에서 바로 볼 수 있어서 디버깅할 때 아주 유용해요. JSON 형식으로 출력하고 싶다면 --format json 플래그를 추가하면 됩니다.

타입 생성

TypeScript를 쓴다면 wrangler types 명령어를 꼭 기억해두세요. 설정 파일에 정의된 바인딩을 기반으로 TypeScript 타입을 자동 생성해줍니다.

npx wrangler types

이 명령어를 실행하면 Env 인터페이스가 포함된 타입 파일이 만들어집니다. KV, R2, D1 바인딩에 대한 타입이 자동으로 잡혀서 코드에서 env.MY_KV처럼 접근할 때 자동 완성과 타입 검사가 제대로 동작해요.

설정 파일을 수정할 때마다 wrangler types를 다시 실행하면 좋고 CI에서는 --check 플래그로 타입이 최신인지 검증할 수 있습니다.

npx wrangler types --check

설정 검증

설정 파일에 오류가 없는지 확인하는 전용 명령어도 있습니다.

npx wrangler check

배포 전에 실행하면 잘못된 설정으로 배포가 실패하는 걸 미리 막을 수 있어요.

시크릿 관리

API 키나 토큰 같은 민감한 값은 설정 파일에 직접 적으면 안 되겠죠. Wrangler는 시크릿을 안전하게 관리하는 전용 명령어를 제공합니다.

npx wrangler secret put API_KEY

결과

 ⛅️ wrangler 4.54.0
───────────────────
✔ Enter a secret value: … ****
🌀 Creating the secret for the Worker "my-worker"
✨ Success! Uploaded secret API_KEY

대화형으로 값을 입력받기 때문에 터미널 히스토리에 시크릿이 남지 않습니다.

현재 설정된 시크릿 목록은 list로 확인할 수 있어요.

npx wrangler secret list

더 이상 필요 없는 시크릿은 delete로 삭제합니다.

npx wrangler secret delete API_KEY

시크릿은 Cloudflare 인프라에 암호화되어 저장되며 Worker 코드에서는 env 객체를 통해 일반 환경 변수처럼 접근합니다.

KV 다루기

Workers KV는 Cloudflare의 전역 키-값 저장소입니다. Wrangler로 네임스페이스를 만들고 데이터를 읽고 쓰는 작업을 터미널에서 바로 할 수 있어요.

네임스페이스를 생성해봅시다.

npx wrangler kv namespace create MY_CACHE

결과

🌀 Creating namespace with title "my-worker-MY_CACHE"
✨ Success!
Add the following to your Wrangler configuration file:

{
  "kv_namespaces": [
    {
      "binding": "MY_CACHE",
      "id": "a1b2c3d4..."
    }
  ]
}

출력된 설정을 wrangler.jsonc에 복사해 넣으면 바인딩이 완료됩니다.

데이터를 직접 넣어보겠습니다.

npx wrangler kv key put --namespace-id=a1b2c3d4 "user:123" '{"name":"Dale","role":"admin"}'

값을 읽어올 때는 get을 씁니다.

npx wrangler kv key get --namespace-id=a1b2c3d4 "user:123"

결과

{"name":"Dale","role":"admin"}

여러 키-값 쌍을 한꺼번에 넣어야 한다면 bulk put이 편합니다.

npx wrangler kv bulk put --namespace-id=a1b2c3d4 data.json

data.json

[
  { "key": "config:theme", "value": "dark" },
  { "key": "config:lang", "value": "ko" },
  { "key": "config:timezone", "value": "Asia/Seoul" }
]

R2 다루기

R2는 Cloudflare의 오브젝트 스토리지입니다. AWS S3와 호환되면서도 이그레스(egress) 비용이 없다는 게 큰 장점이죠.

버킷을 만들어보겠습니다.

npx wrangler r2 bucket create my-files

파일을 업로드하려면 object put을 씁니다.

npx wrangler r2 object put my-files/images/photo.jpg --file ./photo.jpg

다운로드는 object get이에요.

npx wrangler r2 object get my-files/images/photo.jpg --file ./downloaded.jpg

버킷 목록을 확인하려면요.

npx wrangler r2 bucket list

D1 다루기

D1은 Cloudflare의 서버리스 SQL 데이터베이스입니다. SQLite 기반이라 가볍고 Workers와 자연스럽게 연동돼요.

데이터베이스를 생성해봅시다.

npx wrangler d1 create my-database

결과

✅ Successfully created DB 'my-database'

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "my-database",
      "database_id": "xyz789..."
    }
  ]
}

SQL을 직접 실행할 수도 있습니다.

npx wrangler d1 execute my-database --command "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)"

마이그레이션 관리도 됩니다. migrations create로 마이그레이션 파일을 만들고 migrations apply로 적용하는 식이에요.

npx wrangler d1 migrations create my-database add-users-table

이 명령어를 실행하면 migrations 디렉토리에 SQL 파일이 생깁니다. 여기에 DDL을 작성한 뒤 적용하면 돼요.

npx wrangler d1 migrations apply my-database

로컬에서 먼저 테스트하고 싶다면 --local 플래그를 붙여주세요.

npx wrangler d1 execute my-database --local --command "SELECT * FROM users"

자동 리소스 프로비저닝

KV 네임스페이스를 만들고 ID를 복사해서 설정 파일에 넣고 또 R2 버킷을 만들고… 이 과정이 번거롭다면 반가운 소식이 있습니다.

Wrangler 4.45.0부터 자동 리소스 프로비저닝 기능이 추가됐어요. 설정 파일에 바인딩만 선언해두면 리소스 ID 없이도 wrangler dev와 wrangler deploy가 알아서 리소스를 만들어줍니다.

wrangler.jsonc

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-02-01",
  "kv_namespaces": [
    {
      "binding": "CACHE"
    }
  ],
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "my-app-db"
    }
  ]
}

id나 database_id 없이 바인딩 이름만 적어둔 것이 보이시죠? 이 상태에서 wrangler dev를 실행하면 로컬 리소스가 자동으로 생성되고 wrangler deploy를 실행하면 Cloudflare API를 호출해서 실제 리소스를 만든 뒤 Worker에 연결해줍니다.

프로토타이핑이나 새 프로젝트를 시작할 때 설정에 들어가는 수고를 크게 줄여줘요.

멀티 워커 개발

마이크로서비스 아키텍처에서 여러 Worker가 서로 호출하는 구조라면 로컬에서 테스트하기가 어려웠는데요. 이제 wrangler dev에서 여러 설정 파일을 동시에 지정할 수 있습니다.

npx wrangler dev -c ./wrangler.jsonc -c ../auth-worker/wrangler.jsonc -c ../api-worker/wrangler.jsonc

첫 번째 설정 파일의 Worker가 HTTP로 노출되는 주(primary) Worker가 되고 나머지는 서비스 바인딩을 통해서만 접근할 수 있습니다. 여러 Worker 간의 상호작용을 로컬에서 한 번에 테스트할 수 있어서 개발할 때 꽤 편해요.

실전 팁

마지막으로 Wrangler를 쓰면서 알아두면 좋은 팁 몇 가지를 공유합니다.

package.json에 자주 쓰는 명령어를 스크립트로 등록해두면 편해요.

package.json

{
  "scripts": {
    "dev": "wrangler dev",
    "deploy": "wrangler deploy",
    "deploy:staging": "wrangler deploy --env staging",
    "types": "wrangler types",
    "tail": "wrangler tail"
  }
}

이렇게 해두면 npm run dev로 바로 개발 서버를 띄울 수 있고 팀원도 어떤 명령어를 써야 하는지 한눈에 파악할 수 있습니다.

CI/CD 파이프라인에서는 배포 전에 wrangler check와 wrangler types --check를 실행해서 설정 오류와 타입 불일치를 미리 잡는 게 좋습니다.

npx wrangler check && npx wrangler types --check && npx wrangler deploy

.wrangler/ 디렉토리는 로컬 개발 데이터가 저장되는 곳이니 .gitignore에 꼭 추가하세요.

.gitignore

.wrangler/

마치며

Wrangler는 Cloudflare 생태계에서 개발할 때 빠질 수 없는 도구입니다. 프로젝트 생성부터 로컬 개발과 리소스 관리, 배포까지 전부 터미널 안에서 해결되니까요.

자동 리소스 프로비저닝이나 멀티 워커 개발 같은 최신 기능은 실제로 써보면 체감이 큽니다. 개발할 때 느끼던 번거로움을 잘 짚어서 개선한 기능이에요.

이 글에서 다룬 내용만으로도 대부분의 Cloudflare Workers 프로젝트를 진행하는 데 충분할 거예요. 더 궁금한 내용이 있다면 Wrangler 공식 문서와 명령어 레퍼런스를 참고해보세요!

This work is licensed under CC BY 4.0

Wrangler란?

설치

인증

설정 파일

환경 분리

핵심 명령어

프로젝트 생성

로컬 개발

배포

실시간 로그

타입 생성

설정 검증

시크릿 관리

KV 다루기

R2 다루기

D1 다루기

자동 리소스 프로비저닝

멀티 워커 개발

실전 팁

마치며

관련 포스트

Cloudflare Workers로 서버리스 애플리케이션 만들기

skills.sh: 공개 에이전트 스킬 생태계

OpenCode: 오픈소스 AI 코딩 에이전트

ngrok으로 로컬 서버를 인터넷에 공개하기

뉴스레터 구독