R2 物件儲存:S3 相容、零 egress,存大檔不再被流量費坑 | Cloudflare 完整教學

# 建立 bucket(location 可選:apac 亞太、wnam 西北美、weur 西歐 等)
wrangler r2 bucket create my-app-files --location=apac

# 列出所有 bucket、查看詳情
wrangler r2 bucket list
wrangler r2 bucket info my-app-files

{
  "name": "my-app",
  "main": "src/index.ts",
  "compatibility_date": "2024-09-23",
  "r2_buckets": [
    {
      "binding": "MY_BUCKET",       // 程式中用 env.MY_BUCKET 存取
      "bucket_name": "my-app-files" // 對應剛剛建立的 bucket 名稱
    }
  ]
}

// env.d.ts
interface Env {
  MY_BUCKET: R2Bucket;
}

// 上傳:一定要設 content-type,否則瀏覽器不知道怎麼處理這個檔案
await env.MY_BUCKET.put("photos/avatar.jpg", imageBuffer, {
  httpMetadata: {
    contentType: "image/jpeg",
    cacheControl: "public, max-age=31536000, immutable", // 讓 CDN/瀏覽器長快取
  },
  customMetadata: {
    userId: "user123",               // 自訂標籤,可存業務資料
    uploadedAt: new Date().toISOString(),
  },
});

// 刪除單一物件(即使 key 不存在也不報錯)
await env.MY_BUCKET.delete("photos/old-avatar.jpg");

// 批次刪除(一次最多 1,000 個)
await env.MY_BUCKET.delete(["cache/a.html", "cache/b.html"]);

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const object = await env.MY_BUCKET.get("photos/avatar.jpg");

    // get 找不到物件會回傳 null,一定要處理
    if (object === null) {
      return new Response("找不到物件", { status: 404 });
    }

    const headers = new Headers();
    object.writeHttpMetadata(headers);        // 自動寫回 content-type、cache-control 等
    headers.set("etag", object.httpEtag);     // 注意:用 httpEtag(帶引號),不是 etag

    // object.body 是可串流的 ReadableStream,直接當回應 body,不緩衝進記憶體
    return new Response(object.body, { headers });
  },
} satisfies ExportedHandler<Env>;

// 分頁列出某前綴下的所有物件(正確做法:用 truncated 判斷是否還有下一頁)
async function listAll(env: Env, prefix: string): Promise<R2Object[]> {
  const all: R2Object[] = [];
  let cursor: string | undefined;

  while (true) {
    const page = await env.MY_BUCKET.list({ prefix, limit: 1000, cursor });
    all.push(...page.objects);
    if (!page.truncated) break;   // 沒有下一頁就結束
    cursor = page.cursor;         // 帶著 cursor 抓下一頁
  }
  return all;
}

// 用 delimiter 模擬「資料夾」:列出 photos/ 底下的「子資料夾」
const result = await env.MY_BUCKET.list({ prefix: "photos/", delimiter: "/" });
console.log(result.delimitedPrefixes); // 例如 ["photos/2025/", "photos/2026/"]

async function uploadLargeFile(env: Env, key: string, file: ArrayBuffer) {
  const PART_SIZE = 5 * 1024 * 1024; // 每段 5 MB(最小值,最後一段除外)

  // 1. 建立 multipart 上傳工作
  const upload = await env.MY_BUCKET.createMultipartUpload(key, {
    httpMetadata: { contentType: "video/mp4" },
  });

  const parts: R2UploadedPart[] = [];
  const partCount = Math.ceil(file.byteLength / PART_SIZE);

  try {
    // 2. 逐段上傳(part number 從 1 開始,不是 0)
    for (let i = 0; i < partCount; i++) {
      const start = i * PART_SIZE;
      const chunk = file.slice(start, start + PART_SIZE);
      const part = await upload.uploadPart(i + 1, chunk);
      parts.push(part);
    }

    // 3. 全部上傳完,呼叫 complete 合併成一個物件
    const object = await upload.complete(parts);
    return object;
  } catch (error) {
    // 4. 中途失敗一定要 abort,否則未完成的分段會佔空間、產生費用
    await upload.abort();
    throw error;
  }
}

npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    if (request.method !== "POST") {
      return new Response("Method Not Allowed", { status: 405 });
    }

    const { filename, contentType } = await request.json<{
      filename: string;
      contentType: string;
    }>();

    // 安全驗證:只允許特定檔案類型,避免被濫用
    const allowed = ["image/jpeg", "image/png", "image/webp", "application/pdf"];
    if (!allowed.includes(contentType)) {
      return new Response("不支援的檔案類型", { status: 400 });
    }

    // R2 的 S3 用戶端:region 必填 "auto",endpoint 指向你的帳號
    const s3 = new S3Client({
      region: "auto", // R2 必填,固定填 "auto"
      endpoint: `https://${env.ACCOUNT_ID}.r2.cloudflarestorage.com`,
      credentials: {
        accessKeyId: env.R2_ACCESS_KEY_ID,
        secretAccessKey: env.R2_SECRET_ACCESS_KEY,
      },
    });

    // 用隨機 key 避免覆蓋、避免路徑穿越
    const key = `uploads/${crypto.randomUUID()}/${filename}`;

    // 產生上傳 presigned URL(效期 1 小時,最長可到 7 天)
    const uploadUrl = await getSignedUrl(
      s3,
      new PutObjectCommand({ Bucket: "my-app-files", Key: key, ContentType: contentType }),
      { expiresIn: 3600 },
    );

    return Response.json({ uploadUrl, key });
  },
} satisfies ExportedHandler<Env>;

// 前端:先跟 Worker 換取上傳 URL,再直接 PUT 到 R2
async function uploadFile(file: File) {
  const { uploadUrl, key } = await fetch("/api/upload-url", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ filename: file.name, contentType: file.type }),
  }).then((r) => r.json());

  // 這一步的大流量直接在瀏覽器與 R2 之間,不佔用 Worker 資源
  const res = await fetch(uploadUrl, {
    method: "PUT",
    headers: { "content-type": file.type },
    body: file,
  });

  if (!res.ok) throw new Error(`上傳失敗:${res.status}`);
  console.log(`上傳成功,key:${key}`);
}

# 方式二:自訂網域(生產環境推薦)——把 files.example.com 綁到 bucket
wrangler r2 bucket domain add my-app-files --domain=files.example.com

// ❌ 錯誤:沒設 content-type,瀏覽器可能把圖片當成純文字下載
await env.MY_BUCKET.put("photos/a.jpg", buffer);

// ✅ 正確:一定要在 httpMetadata 設 contentType
await env.MY_BUCKET.put("photos/a.jpg", buffer, {
  httpMetadata: { contentType: "image/jpeg" },
});

// ❌ 危險:直接拿使用者輸入當 key,可能被 "../../../secrets" 攻擊
const key = new URL(request.url).pathname.slice(1);
await env.MY_BUCKET.get(key);

// ✅ 安全:驗證 key 格式,擋掉路徑穿越
function isValidKey(key: string): boolean {
  return Boolean(key) && !key.includes("..") && !key.startsWith("/") && !key.includes("\0");
}