cloudflare-images

Cloudflare Images

状态：已准备好用于生产环境 ✅ | 版本：3.0.0 | 上次验证时间：2025-12-27

---

什么是 Cloudflare Images？

两项强大的功能：

1. Images API：上传、存储并在全球范围内提供图片
2. 图片转换：调整任意图片的大小并优化

主要优势：

• 通过全球 CDN 交付
• 自动转换为 WebP/AVIF
• 最多支持 100 个变体
• 创作者可直接上传（前端无需 API 密钥）
• 为私有图片提供签名 URL
• 通过 URL 或 Workers 转换任意图片

---

快速入门（5 分钟）

1. 启用 Cloudflare Images

控制面板 → Images → 启用

获取你的 Account ID 并创建 API 令牌（需要 Cloudflare Images：编辑权限）

2. 上传图片

curl --request POST \
  --url https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/images/v1 \
  --header 'Authorization: Bearer <API_TOKEN>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=@./image.jpg'

**重要：**使用 multipart/form-data，不要使用 JSON

3. 提供图片

<img src="https://imagedelivery.net/<ACCOUNT_HASH>/<IMAGE_ID>/public" />

4. 启用图片转换

控制面板 → Images → Transformations → 为区域启用

转换任意图片：

<img src="/cdn-cgi/image/width=800,quality=85/uploads/photo.jpg" />

5. 通过 Workers 转换

export default {
  async fetch(request: Request): Promise<Response> {
    return fetch("https://example.com/image.jpg", {
      cf: {
        image: {
          width: 800,
          quality: 85,
          format: "auto"  // WebP/AVIF
        }
      }
    });
  }
};

加载 references/setup-guide.md 查看完整操作指南。

---

3 项核心功能

功能 1：Images API（上传和存储）

上传方式：

1. 文件上传（服务端）
2. 通过 URL 上传（从外部获取）
3. 创作者直接上传（用户上传，无需 API 密钥）

加载 templates/upload-api-basic.ts 查看文件上传示例。 加载 references/direct-upload-complete-workflow.md 查看用户上传流程。

功能 2：图片转换

优化任意图片（已上传或外部图片）。

方式：

1. URL：/cdn-cgi/image/width=800,quality=85/path/to/image.jpg
2. Workers：cf.image 获取选项

加载 references/transformation-options.md 查看所有选项。 加载 templates/transform-via-workers.ts 查看 Workers 示例。

功能 3：变体

预定义的转换（最多 100 个）。

示例：

• thumbnail：200x200，fit=cover
• hero：1920x1080，quality=90
• mobile：640，quality=75

加载 references/variants-guide.md 查看完整指南。

---

关键规则

务必做到 ✅

1. 上传时使用 multipart/form-data（不要使用 JSON）
2. 使用 /cdn-cgi/image/ 前，为区域启用图片转换
3. 用户上传时使用创作者直接上传（不要暴露 API 令牌）
4. 设置 CORS 标头，以支持从浏览器直接上传
5. 对私有图片使用签名 URL
6. 为常用尺寸配置变体（避免动态转换）
7. 使用 format=auto 自动转换为 WebP/AVIF
8. 处理错误代码（9401、9403、9413、5408）
9. 设置 quality=85，以获得最佳大小和质量平衡
10. 使用 fit=cover，保持纵横比一致

切勿这样做 ❌

1. 切勿在前端代码中暴露 API 令牌
2. 切勿使用 JSON 编码上传文件
3. 直接上传时切勿跳过 CORS 配置
4. 切勿超过 100 个变体（硬性上限）
5. 未为区域启用图片转换时，切勿使用转换功能
6. 切勿在公开代码中硬编码 Account ID
7. 切勿跳过错误处理（上传可能失败）
8. 切勿使用大于 90 的 quality（收益递减）
9. 切勿跳过图片验证（大小、格式、尺寸）
10. 切勿对非代理请求使用图片转换

---

两大应用场景

应用场景 1：用户个人资料图片

用户上传图片时采用创作者直接上传模式：

// Backend: Generate upload URL
const response = await fetch(
  `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/images/v2/direct_upload`,
  { method: 'POST', headers: { 'Authorization': `Bearer ${API_TOKEN}` } }
);
const { result } = await response.json();
return Response.json({ uploadURL: result.uploadURL });

// Frontend: Upload file
const formData = new FormData();
formData.append('file', file);
await fetch(uploadURL, { method: 'POST', body: formData });

加载 templates/direct-creator-upload-backend.ts 查看完整示例。 参见 examples/basic-upload/ 查看完整的可运行项目。

用例 2：响应式图像

使用 srcset 实现响应式图像，获得最佳性能：

<img
  srcset="
    https://imagedelivery.net/abc/xyz/width=400 400w,
    https://imagedelivery.net/abc/xyz/width=800 800w,
    https://imagedelivery.net/abc/xyz/width=1200 1200w
  "
  sizes="(max-width: 600px) 400px, (max-width: 1000px) 800px, 1200px"
  src="https://imagedelivery.net/abc/xyz/width=800"
/>

加载 templates/responsive-images-srcset.html 查看完整示例。 查看 examples/responsive-gallery/ 了解完整的可运行项目。

其他用例：

• 转换现有图像：加载 references/transformation-options.md
• 私有图像：加载 references/signed-urls-guide.md，或查看 examples/private-images/
• 批量上传：加载 templates/batch-upload.ts
• 框架集成：加载 references/framework-integration.md，适用于 Next.js、Remix、Astro
• 添加水印：加载 references/overlays-watermarks.md 和 templates/overlay-watermark.ts
• 自定义域名：加载 references/custom-domains.md
• Webhook：加载 references/webhooks-guide.md 和 templates/webhook-handler.ts

---

可避免的 2 个常见错误

错误 1：直接上传时出现 CORS 问题

问题： 浏览器会阻止从你的域名直接上传。

解决方案： 生成上传 URL 时配置 CORS 标头：

const response = await fetch(
  `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/images/v2/direct_upload`,
  {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${API_TOKEN}` },
    body: JSON.stringify({
      requireSignedURLs: false,
      metadata: { source: 'user-upload' }
    })
  }
);

错误 2：多部分表单数据编码

问题： JSON 编码无法用于文件上传（必须使用 multipart/form-data）。

解决方案：

// ✅ CORRECT
const formData = new FormData();
formData.append('file', file);
await fetch(uploadURL, { method: 'POST', body: formData });

// ❌ WRONG
const json = JSON.stringify({ file: base64File });

其他常见错误：

• 错误 9401（未启用转换）：加载 references/top-errors.md
• 错误 9403（转换无效）：加载 references/top-errors.md
• 错误 9413（超出变体数量限制）：加载 references/top-errors.md
• 错误 5408（上传超时）：加载 references/top-errors.md
• 缺少 requireSignedURLs：加载 references/signed-urls-guide.md

加载 references/top-errors.md，查看全部 10 种错误及其完整解决方案。

---

何时加载参考资料

核心参考资料

遇到以下情况时，加载 references/setup-guide.md：

• 首次设置 Cloudflare Images
• 需要分步指南

遇到以下情况时，加载 references/api-reference.md：

• 需要完整的 API 文档
• 需要了解所有端点和参数

遇到以下情况时，加载 references/top-errors.md：

• 遇到任何错误代码（5408、9401-9413）
• 排查上传或转换问题

上传参考资料

遇到以下情况时，加载 references/direct-upload-complete-workflow.md：

• 实现用户上传
• 需要前端和后端示例
• 配置 CORS

遇到以下情况时，加载 references/signed-urls-guide.md：

• 实现带访问控制的私有图像
• 需要生成 HMAC-SHA256 签名

遇到以下情况时，加载 references/webhooks-guide.md：

• 处理上传完成事件
• 实现带签名验证的 webhook 处理程序

转换参考资料

遇到以下情况时，加载 references/transformation-options.md：

• 需要完整的转换参考资料
• 探索所有适配、格式和效果选项

遇到以下情况时，加载 references/format-optimization.md：

• 优化格式选择（WebP/AVIF）
• 权衡质量与大小

遇到以下情况时，加载 references/polish-compression.md：

• 需要了解无损、有损和 WebP 压缩模式的详情
• 处理元数据（移除 EXIF）

遇到以下情况时，加载 references/overlays-watermarks.md：

• 添加文字或 Logo 水印
• 实现品牌标识或版权保护

高级功能

遇到以下情况时，加载 references/variants-guide.md：

• 创建或管理变体（最多 100 个）
• 需要灵活变体与命名变体

遇到以下情况时，加载 references/responsive-images-patterns.md：

• 使用 srcset 构建响应式图像
• 使用 picture 元素实现艺术指导

遇到以下情况时，加载 references/framework-integration.md：

• 与 Next.js、Remix、Astro、SvelteKit 集成
• 需要特定框架的模式和加载器

遇到以下情况时，加载 references/custom-domains.md：

• 从品牌域名提供图像
• 配置 CNAME 和 SSL

遇到以下情况时，加载 references/content-credentials.md：

• 保留 EXIF/IPTC 元数据
• 实现 C2PA Content Credentials，确保真实性

遇到以下情况时，加载 references/sourcing-kit.md：

• 从 Cloudinary、Imgix 或 S3 迁移
• 从外部 CDN 批量导入

---

使用捆绑资源

参考资料（16 个参考文件）

核心：setup-guide.md、api-reference.md、top-errors.md

上传：direct-upload-complete-workflow.md、signed-urls-guide.md、webhooks-guide.md

转换：transformation-options.md、format-optimization.md、polish-compression.md、overlays-watermarks.md

高级：variants-guide.md、responsive-images-patterns.md、framework-integration.md、custom-domains.md、content-credentials.md、sourcing-kit.md

模板（16 个模板文件）

上传：upload-api-basic.ts、upload-via-url.ts、direct-creator-upload-backend.ts、direct-creator-upload-frontend.html、batch-upload.ts

转换：transform-via-url.ts、transform-via-workers.ts、overlay-watermark.ts

变体：variants-management.ts、signed-urls-generation.ts、responsive-images-srcset.html

集成：nextjs-integration.tsx、remix-integration.tsx、webhook-handler.ts

配置：wrangler-images-binding.jsonc、package.json

Agent（3 个自主 Agent）

• troubleshooting-agent - 诊断上传／转换错误（5408、9401-9413）
• upload-workflow-agent - 指导完成整个上传实现（前端 + 后端）
• optimization-agent - 推荐图像优化策略

使用：/agent <agent-name>，或在相关场景下让 Claude 自动检测

命令（3 个斜杠命令）

• /check-images - 快速检查 API 健康状态并验证配置
• /validate-config - 验证 wrangler.jsonc 绑定和配置
• /generate-variant - 交互式变体生成器

使用：/<command-name>

示例（3 个完整的可运行项目）

• basic-upload/ - 使用 Hono + Workers 的最小化上传实现
• responsive-gallery/ - 支持 srcset 和延迟加载的响应式图像图库
• private-images/ - 具有基于时间的过期机制和访问控制的签名 URL

克隆并运行：cd examples/<example-name> && npm install && npm run dev

架构图（3 张图）

• direct-upload-workflow.md - 直接创建者上传流程的时序图
• transformation-pipeline.md - 展示转换处理过程的流程图
• variants-structure.md - 命名变体与灵活变体对比

查看位置：assets/diagrams/

实用脚本（5 个脚本）

• test-upload.sh - 使用示例图像上传测试 API 连通性
• generate-signed-url.sh - 生成带过期时间的签名 URL 的命令行工具
• validate-variants.sh - 列出所有变体并检查变体数量（最多 100 个）
• analyze-usage.sh - 查询 API，获取存储用量和预估费用
• check-versions.sh - 检查软件包版本是否为最新

运行：./scripts/<script-name>.sh（需要在 .env 中设置 CF_ACCOUNT_ID 和 CF_API_TOKEN）

---

定价

Images API：每存储 10 万张收费 $5，每交付 10 万张收费 $1 转换：每 1 千次收费 $0.50（每个区域每月免费 10 万次） 直接上传：包含在 API 定价中

---

官方文档

• Images 概览：https://developers.cloudflare.com/images/
• 上传 API：https://developers.cloudflare.com/images/upload-images/
• 转换：https://developers.cloudflare.com/images/transform-images/
• 直接创建者上传：https://developers.cloudflare.com/images/upload-images/direct-creator-upload/
• 变体：https://developers.cloudflare.com/images/manage-images/create-variants/