Cloudflare R2 Workers API

원문 보기 위키 갱신 2026.10.07

Workers는 에지에서 코드를 실행하게 해줘요. R2 버킷을 Worker에 바인딩하면 Workers API로 객체를 직접 읽고 쓸 수 있어요.

출처: 문서

본문

1. 버킷 생성하기

버킷은 R2에서 객체를 저장하는 곳이에요. 새 R2 버킷을 만들려면:

Cloudflare 계정에 로그인해요:
```
npx wrangler login
```
my-bucket이라는 이름의 버킷을 만들어요:
```
npx wrangler r2 bucket create my-bucket
```
요청이 나오면 버킷을 만들 계정을 선택해요.
버킷이 생성됐는지 확인해요:
```
npx wrangler r2 bucket list
```

또는 Cloudflare Dashboard에서 만들 수도 있어요.

Cloudflare Dashboard의 R2 object storage로 이동해요. Overview로 이동
Create bucket을 선택해요.
버킷 이름을 입력해요.
버킷의 location과 default storage class를 선택해요.
Create bucket을 선택해요.

2. R2 바인딩이 있는 Worker 만들기

새 Worker 프로젝트를 만들어요:
```
npm create cloudflare@latest -- r2-worker
```
```
yarn create cloudflare r2-worker
```
```
pnpm create cloudflare@latest r2-worker
```
요청이 나오면 템플릿으로 Hello World example과 JavaScript(또는 TypeScript)를 선택해요.
프로젝트 디렉터리로 이동해요:
```
cd r2-worker
```

Wrangler 구성 파일에 R2 바인딩을 추가해요. my-bucket을 버킷 이름으로 바꿔요:

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

[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "my-bucket"

(선택 사항) TypeScript를 사용한다면 타입을 다시 생성해요:
```
npx wrangler types
```

3. 객체 읽고 쓰기

바인딩으로 버킷과 상호작용해요. 아래 예시는 URL 경로를 기준으로 객체를 저장하고 검색해요:

src/index.js

export default {
	async fetch(request, env) {
		// Get the object key from the URL path
		// For example: /images/cat.png → images/cat.png
		const url = new URL(request.url);
		const key = url.pathname.slice(1);

		// PUT: Store the request body in R2
		if (request.method === "PUT") {
			await env.MY_BUCKET.put(key, request.body);
			return new Response(`Put ${key} successfully!`);
		}

		// GET: Retrieve the object from R2
		const object = await env.MY_BUCKET.get(key);
		if (object === null) {
			return new Response("Object not found", { status: 404 });
		}
		return new Response(object.body);
	},
};

src/index.ts

export default {
	async fetch(request, env): Promise<Response> {
		// Get the object key from the URL path
		// For example: /images/cat.png → images/cat.png
		const url = new URL(request.url);
		const key = url.pathname.slice(1);

		// PUT: Store the request body in R2
		if (request.method === "PUT") {
			await env.MY_BUCKET.put(key, request.body);
			return new Response(`Put ${key} successfully!`);
		}

		// GET: Retrieve the object from R2
		const object = await env.MY_BUCKET.get(key);
		if (object === null) {
			return new Response("Object not found", { status: 404 });
		}
		return new Response(object.body);
	},
} satisfies ExportedHandler<Env>;

4. 테스트하고 배포하기

Worker를 로컬에서 테스트해요:
```
npx wrangler dev
```
로컬 개발

기본적으로 wrangler dev는 로컬 R2 시뮬레이션을 사용해요. 개발 중 저장한 객체는 .wrangler/state 폴더에만 존재하며 프로덕션 버킷에는 영향을 주지 않아요.

개발 중 실제 R2 버킷에 연결하려면 Wrangler 구성 파일의 R2 바인딩에 "remote": true를 추가해요. 자세한 내용은 remote bindings를 참고해요.

dev 서버가 실행 중이면 객체 저장·검색을 테스트해요:

# Store an object
curl -X PUT http://localhost:8787/my-file.txt -d 'Hello, R2!'

# Retrieve the object
curl http://localhost:8787/my-file.txt

프로덕션에 배포해요:
```
npx wrangler deploy
```

배포 후 Wrangler가 Worker의 URL을 출력해요(예: https://r2-worker.<YOUR_SUBDOMAIN>.workers.dev). 객체 저장·검색을 테스트해요:

# Store an object
curl -X PUT https://r2-worker.<YOUR_SUBDOMAIN>.workers.dev/my-file.txt -d 'Hello, R2!'

# Retrieve the object
curl https://r2-worker.<YOUR_SUBDOMAIN>.workers.dev/my-file.txt

전체 API 참조는 Workers R2 API documentation을 참고해요.

다음 단계

Presigned URLs — 비공개 객체 접근을 위한 임시 URL 생성하기
Public buckets — 공개 버킷으로 파일을 HTTP로 직접 제공하기
CORS — 브라우저 기반 업로드를 위한 CORS 구성하기
Object lifecycles — 오래된 객체를 자동 삭제하는 수명주기 규칙 설정하기

더 알아보기 (Learn more)

Workers API로 시작한 뒤에는 Presigned URLs, Public buckets, CORS, Object lifecycles 문서로 넘어가 보세요.