Wrangler CLI

Wrangler는 Cloudflare Workers와 Pages를 빌드, 배포, 관리하기 위한 공식 CLI 도구입니다.

시스템 요구사항

요구사항	버전
Node.js	Current, Active, Maintenance 버전
macOS	13.5 이상
Windows	11 이상
Linux	glibc 2.35 이상

Node.js 설치 시 Volta 또는 nvm을 사용하면 권한 문제를 피할 수 있습니다.

설치

프로젝트의 개발 의존성으로 Wrangler를 설치합니다:

# npm
npm i -D wrangler@latest

# yarn
yarn add -D wrangler@latest

# pnpm
pnpm add -D wrangler@latest

로컬 설치의 장점:

팀 전체가 동일한 버전 사용
필요시 이전 버전으로 롤백 가능
프로젝트별 버전 관리

npx wrangler를 실행할 때 Wrangler가 설치되어 있지 않으면 자동으로 최신 버전을 사용합니다. 이는 팀 환경에서 불일치를 유발할 수 있으므로 명시적 설치를 권장합니다.

버전 확인

npx wrangler --version
# 또는
npx wrangler -v

인증

OAuth 로그인 (권장)

# 브라우저에서 Cloudflare 계정으로 로그인
npx wrangler login

# 로그아웃
npx wrangler logout

# 현재 인증된 사용자 확인
npx wrangler whoami

API 토큰 사용

CI/CD 환경에서는 환경 변수로 API 토큰을 설정합니다:

export CLOUDFLARE_API_TOKEN="your_api_token"

주요 명령어

프로젝트 초기화

# 새 프로젝트 생성
npx wrangler init my-worker

# 기존 디렉토리에서 초기화
npx wrangler init

개발 서버

# 로컬 개발 서버 시작
npx wrangler dev

# 특정 환경으로 개발
npx wrangler dev --env staging

로컬 서버가 시작되면 http://localhost:8787에서 Worker를 테스트할 수 있습니다.

배포

# 기본 환경에 배포
npx wrangler deploy

# 특정 환경에 배포
npx wrangler deploy --env staging
npx wrangler deploy --env production

wrangler publish는 deprecated되었습니다. wrangler deploy를 사용하세요.

로그 확인

# 실시간 로그 스트리밍
npx wrangler tail

# 특정 Worker의 로그
npx wrangler tail my-worker

Secret 관리

# Secret 생성/업데이트
npx wrangler secret put API_KEY

# Secret 목록 조회
npx wrangler secret list

# Secret 삭제
npx wrangler secret delete API_KEY

package.json 스크립트 설정

자주 사용하는 명령어를 npm 스크립트로 등록합니다:

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

wrangler.toml 설정

프로젝트 루트에 wrangler.toml 파일을 생성하여 Worker를 설정합니다:

기본 설정

name = "my-worker"
main = "./src/index.js"
compatibility_date = "2024-01-01"

# Workers.dev 서브도메인 사용
workers_dev = true

# 또는 커스텀 도메인/라우트 사용
# route = "example.com/*"

환경별 설정

name = "my-worker"
main = "./src/index.js"

# 기본 환경 (개발)
workers_dev = true

# 스테이징 환경
[env.staging]
route = "staging.example.com/*"
workers_dev = false

# 프로덕션 환경
[env.production]
route = "example.com/*"
workers_dev = false

KV Namespace 바인딩

main = "./src/index.js"

kv_namespaces = [
  { binding = "MY_KV", id = "06779da6940b431db6e566b4846d64db" }
]

[env.production]
kv_namespaces = [
  { binding = "MY_KV", id = "07bc1f3d1f2a4fd8a45a7e026e2681c6" }
]

R2 Bucket 바인딩

main = "./src/index.js"

r2_buckets = [
  { binding = "MY_BUCKET", bucket_name = "my-bucket-name" }
]

D1 Database 바인딩

main = "./src/index.js"

[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Durable Objects 바인딩

main = "./src/index.js"

[[durable_objects.bindings]]
name = "MY_DURABLE_OBJECT"
class_name = "MyDurableObject"

Service 바인딩

main = "./src/index.js"

services = [
  { binding = "AUTH_SERVICE", service = "auth-worker" }
]

명령어 레퍼런스

명령어	설명
`wrangler init`	새 프로젝트 초기화
`wrangler dev`	로컬 개발 서버 시작
`wrangler deploy`	Worker 배포
`wrangler tail`	실시간 로그 확인
`wrangler secret`	Secret 관리
`wrangler kv`	KV 관리
`wrangler r2`	R2 스토리지 관리
`wrangler d1`	D1 데이터베이스 관리
`wrangler pages`	Pages 프로젝트 관리
`wrangler login`	OAuth 로그인
`wrangler logout`	로그아웃
`wrangler whoami`	현재 사용자 확인

Deprecated 명령어

v1 명령어	대체 방법
`wrangler publish`	`wrangler deploy` 사용
`wrangler preview`	`wrangler dev` 사용
`wrangler generate`	`git clone` 사용
`wrangler build`	직접 빌드 스크립트 실행
`wrangler config`	`wrangler login` 또는 환경 변수 사용

출처: Cloudflare Workers - Wrangler