S3 · Cloudflare R2 docs

R2 提供对 S3-compatible API 的支持，这意味着您可以使用任何 S3 SDK、库或工具与存储桶交互。如果您已有适用于 S3 的代码，只需更改 endpoint URL 即可将其用于 R2。

1. 创建存储桶

存储桶用于在 R2 中存储对象。要创建新的 R2 存储桶：

登录您的 Cloudflare 账户：
```
npx wrangler login
```
创建名为 my-bucket 的存储桶：
```
npx wrangler r2 bucket create my-bucket
```
如果提示，请选择要在其中创建存储桶的账户。
验证存储桶是否已创建：
```
npx wrangler r2 bucket list
```

在 Cloudflare 仪表板中，前往 R2 object storage（R2 对象存储）。
Go to Overview ↗
选择 Create bucket（创建存储桶）。
输入存储桶名称。
为存储桶选择位置和默认存储类别。
选择 Create bucket（创建存储桶）。

2. 生成 API 凭据

要使用 S3 API，您需要生成凭据并获取 Access Key ID 和 Secret Access Key：

前往 Cloudflare 仪表板 ↗。
选择 Storage & databases（存储与数据库）> R2 > Overview（概览）。
在 API Tokens 中选择 Manage（管理）。
选择 **Create Account API token（创建账户 API 令牌）**或 Create User API token（创建用户 API 令牌）。
选择 **Object Read & Write（对象读取与写入）**权限和 Apply to specific buckets only（仅应用于特定存储桶），以选择您要访问的存储桶。
选择 Create API Token（创建 API 令牌）。
复制 Access Key ID（访问密钥 ID） 和 Secret Access Key（秘密访问密钥）。请安全存储这些信息，因为您无法再次查看密钥。

您还需要 S3 API endpoint URL，创建令牌后可在 Create API Token（创建 API 令牌） 确认页面底部找到，或在 R2 Overview（概览） 页面上找到：

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

3. 使用 AWS SDK

以下示例展示如何使用 Python 和 JavaScript SDK。对于其他语言，请参阅 S3-compatible 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

设置生命周期规则以自动删除旧对象。