名称: cloudflare-images 描述: 当用户询问“上传图像到Cloudflare”、“实现直接创作者上传”、“配置图像变换”、“优化WebP/AVIF”、“创建图像变体”、“生成签名URL”、“添加图像水印”、“与Next.js/Remix集成”、“配置webhooks”、“调试CORS错误”、“排查错误5408/9401-9413”或“使用Cloudflare Images API构建响应式图像”时，应使用此技能。

关键词: cloudflare images, 图像上传 cloudflare, imagedelivery.net, cloudflare 图像变换, /cdn-cgi/image/, 直接创作者上传, 图像变体, cf.image workers, 签名 urls 图像, 灵活变体, webp avif 转换, 响应式图像 cloudflare, 错误 5408, 错误 9401, 错误 9403, CORS 直接上传, multipart/form-data, 图像优化 cloudflare, 图像水印, webhooks 图像, nextjs cloudflare images, remix cloudflare images, 自定义域名图像, 内容凭证, c2pa 许可证: MIT 元数据: 版本: “3.0.0” 最后验证: “2025-12-27” workers_types_version: “4.20250110.0” typescript_version: “5.7.2” wrangler_version: “3.91.0” 生产测试: true 令牌节省: “~65%” 预防错误: 10 包含模板: 16 包含参考资料: 16 包含代理: 3 包含命令: 3 包含示例: 3 包含图表: 3 包含脚本: 5

Cloudflare Images

状态: 生产就绪 ✅ | 版本: 3.0.0 | 最后验证: 2025-12-27

Cloudflare Images 是什么？

两个强大功能：

Images API: 上传、存储、全球服务图像
Image Transformations: 调整大小/优化任何图像

关键优势:

全球CDN交付
自动WebP/AVIF转换
最多100个变体
直接创作者上传（前端无API密钥）
签名URL用于私有图像
通过URL或Workers变换任何图像

快速开始（5分钟）

1. 启用Cloudflare Images

仪表盘 → Images → 启用

获取您的账户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（上传与存储）

上传方法:

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

加载 templates/upload-api-basic.ts 获取文件上传示例。 加载 references/direct-upload-complete-workflow.md 获取用户上传指南。

功能2: Image Transformations

优化任何图像（已上传或外部）。

方法:

URL: /cdn-cgi/image/width=800,quality=85/path/to/image.jpg
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 获取完整指南。

关键规则

始终做 ✅

使用 multipart/form-data 用于上传（非JSON）
为区域启用变换 在使用 /cdn-cgi/image/ 之前
使用直接创作者上传 用于用户上传（不暴露API令牌）
设置CORS头 用于浏览器直接上传
使用签名URL 用于私有图像
配置变体 用于常见尺寸（避免动态变换）
使用 format=auto 用于自动WebP/AVIF
处理错误代码（9401, 9403, 9413, 5408）
设置 quality=85 用于最佳大小/质量平衡
使用 fit=cover 用于一致纵横比

从不做 ❌

永不暴露API令牌 在前端代码中
永不使用JSON编码 用于文件上传
永不跳过CORS配置 用于直接上传
永不超过100个变体（硬限制）
永不在未启用区域时使用变换
永不硬编码账户ID 在公共代码中
永不跳过错误处理（上传可能失败）
永不使用 quality >90（收益递减）
永不跳过图像验证（大小、格式、尺寸）
永不在非代理请求上使用变换

前2个用例

用例1: 用户头像

用户上传图像的直接创作者上传模式：

// 后端: 生成上传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 });

// 前端: 上传文件
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
Webhooks: 加载 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: Multipart Form Data 编码

问题: JSON编码失败用于文件上传（必须使用multipart/form-data）。

解决方案:

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

// ❌ 错误
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 当:

需要完整变换参考
探索所有fit/format/effect选项

加载 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内容凭证用于真实性

加载 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

代理（3个自主代理）

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的CLI工具
validate-variants.sh - 列出所有变体并检查变体数量（最多100）
analyze-usage.sh - 查询API存储使用和估计成本
check-versions.sh - 验证包版本为当前

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

定价

Images API: $5/10万存储, $1/10万交付 Transformations: $0.50/1千（每区域每月10万免费） Direct Upload: 包含在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/