Cloudflare R2 S3 시작하기

원문 보기 위키 갱신 2026.10.07

R2는 S3 호환 API를 지원해요. 그래서 어떤 S3 SDK·라이브러리·도구든 사용해 버킷과 상호작용할 수 있어요. S3에서 동작하던 기존 코드가 있다면 엔드포인트 URL만 바꿔서 R2에 그대로 쓸 수 있어요.

출처: 문서

본문

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. API 자격 증명 생성하기

S3 API를 사용하려면 자격 증명을 생성해 Access Key ID와 Secret Access Key를 받아야 해요:

Cloudflare Dashboard로 이동해요.
Storage & databases > R2 > Overview를 선택해요.
API Tokens에서 Manage를 선택해요.
Create Account API token 또는 Create User API token을 선택해요.
Object Read & Write 권한을 선택하고, Apply to specific buckets only를 선택해 접근할 버킷을 골라요.
Create API Token을 선택해요.
Access Key ID와 Secret Access Key를 복사해요. 시크릿 키는 다시 볼 수 없으니 안전하게 보관해요.

S3 API 엔드포인트 URL도 필요해요. 토큰을 생성한 뒤 Create API Token 확인 페이지 하단이나 R2 Overview 페이지에서 찾을 수 있어요:

https://<ACCOUNT_ID>.r2.cloudflarestorage.com

3. AWS SDK 사용하기

아래 예시는 Python과 JavaScript SDK를 보여줘요. 다른 언어는 S3 호환 SDK 예시에서 Go, Java, PHP, Ruby, Rust 문서를 참고해요.

boto3를 설치해요:
```
pip install boto3
```
업로드할 테스트 파일을 만들어요:
```
echo 'Hello, R2!' > myfile.txt
```

자격 증명으로 S3 클라이언트를 만들어 버킷과 상호작용해요:

import boto3

s3 = boto3.client(
    service_name='s3',
    # Provide your R2 endpoint: https://<ACCOUNT_ID>.r2.cloudflarestorage.com
    endpoint_url='https://<ACCOUNT_ID>.r2.cloudflarestorage.com',
    # Provide your R2 Access Key ID and Secret Access Key
    aws_access_key_id='<ACCESS_KEY_ID>',
    aws_secret_access_key='<SECRET_ACCESS_KEY>',
    region_name='auto',  # Required by boto3, not used by R2
)

# Upload a file
s3.upload_file('myfile.txt', 'my-bucket', 'myfile.txt')
print('Uploaded myfile.txt')

# Download a file
s3.download_file('my-bucket', 'myfile.txt', 'downloaded.txt')
print('Downloaded to downloaded.txt')

# List objects
response = s3.list_objects_v2(Bucket='my-bucket')
for obj in response.get('Contents', []):
    print(f"Object: {obj['Key']}")

이 내용을 example.py로 저장하고 실행해요:

python example.py

Uploaded myfile.txt
Downloaded to downloaded.txt
Object: myfile.txt

더 많은 작업은 boto3 예시를 참고해요.

@aws-sdk/client-s3 패키지를 설치해요:
```
npm install @aws-sdk/client-s3
```

자격 증명으로 S3 클라이언트를 만들어 버킷과 상호작용해요:

import {
	S3Client,
	PutObjectCommand,
	GetObjectCommand,
	ListObjectsV2Command,
} from "@aws-sdk/client-s3";

const s3 = new S3Client({
	region: "auto", // Required by AWS SDK, not used by R2
	// Provide your R2 endpoint: https://<ACCOUNT_ID>.r2.cloudflarestorage.com
	endpoint: "https://<ACCOUNT_ID>.r2.cloudflarestorage.com",
	credentials: {
		// Provide your R2 Access Key ID and Secret Access Key
		accessKeyId: "<ACCESS_KEY_ID>",
		secretAccessKey: "<SECRET_ACCESS_KEY>",
	},
});

// Upload a file
await s3.send(
	new PutObjectCommand({
		Bucket: "my-bucket",
		Key: "myfile.txt",
		Body: "Hello, R2!",
	}),
);
console.log("Uploaded myfile.txt");

// Download a file
const response = await s3.send(
	new GetObjectCommand({
		Bucket: "my-bucket",
		Key: "myfile.txt",
	}),
);
const content = await response.Body.transformToString();
console.log("Downloaded:", content);

// List objects
const list = await s3.send(
	new ListObjectsV2Command({
		Bucket: "my-bucket",
	}),
);
console.log(
	"Objects:",
	list.Contents.map((obj) => obj.Key),
);

이 내용을 example.mjs로 저장하고 실행해요:

node example.mjs

Uploaded myfile.txt
Downloaded: Hello, R2!
Objects: [ 'myfile.txt' ]

더 많은 작업은 AWS SDK for JavaScript 예시를 참고해요.

다음 단계

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

더 알아보기 (Learn more)

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