cloudflare-images

Cloudflare Images 是运行在 Cloudflare 全球网络上的端到端图像存储、转换与交付解决方案。

用途

该技能用于在 Cloudflare 平台上存储、转换和交付优化后的图片，覆盖从上传、变体管理到实时转换与安全交付的完整流程。

两种使用模式

存储于 Images：将图片上传到 Cloudflare，通过变体交付。计费依据为 Images Stored + Images Delivered。
转换远程图片：优化来自任意源（如 R2、S3 等）的图片。计费依据为 Images Transformed（唯一图片/30天）。

主要能力

上传方式：API 上传、Worker 内上传、Direct Creator Upload（一次性上传 URL）。
转换方式：通过 URL 前缀 /cdn-cgi/image/ 转换，或通过 Workers 的 cf.image 选项转换。
变体（Variants）：每个账户最多 100 个变体，用于存储图片的交付。
转换选项：width、height、fit、format、quality、gravity、blur、sharpen、rotate、trim 等。
Fit 模式：scale-down、contain、cover、crop、pad。
格式自动选择：format=auto 根据浏览器支持返回 WebP 或 AVIF。
支持格式：输入支持 JPEG、PNG、GIF（动图）、WebP（动图）、SVG、HEIC；输出支持 JPEG、PNG、GIF、WebP、AVIF、SVG（直通）。
Workers 集成：通过 Images 绑定进行转换、绘制水印、获取图片信息。
安全：支持签名 URL 保护图片。
Polish：与图像优化相关的功能（详见 references/polish.md）。

使用方式

快速开始

上传图片（API）：

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

通过 URL 转换：

<img src="/cdn-cgi/image/width=400,quality=80,format=auto/uploads/hero.jpg" />

通过 Workers 转换：

fetch(imageURL, {
  cf: {
    image: {
      width: 800,
      height: 600,
      fit: "cover",
      format: "auto",
    },
  },
});

URL 格式

https://<ZONE>/cdn-cgi/image/<OPTIONS>/<SOURCE-IMAGE>

<ZONE>：你的 Cloudflare 域名
/cdn-cgi/image/：图像转换的固定前缀
<OPTIONS>：逗号分隔，如 width=400,quality=80,format=auto
<SOURCE-IMAGE>：绝对路径或完整 URL

存储图片交付

https://imagedelivery.net/<ACCOUNT_HASH>/<IMAGE_ID>/<VARIANT_NAME>

Workers 绑定设置

# wrangler.toml
[images]
binding = "IMAGES"

使用绑定转换：

const response = (await env.IMAGES.input(stream).transform({ width: 800 }).transform({ blur: 20 }).output({ format: "image/avif" })).response();

绘制水印：

const watermark = await fetch("https://example.com/watermark.png");
const image = await fetch("https://example.com/photo.jpg");

const response = (
  await env.IMAGES.input(image.body)
    .draw(env.IMAGES.input(watermark.body).transform({ width: 100 }), { bottom: 10, right: 10, opacity: 0.75 })
    .output({ format: "image/avif" })
).response();

获取图片信息：

const info = await env.IMAGES.info(stream);
// { format, fileSize, width, height }

常用配方

响应式图片 srcset：

<img srcset="/cdn-cgi/image/width=320/photo.jpg 320w, /cdn-cgi/image/width=640/photo.jpg 640w, /cdn-cgi/image/width=1280/photo.jpg 1280w" sizes="(max-width: 640px) 100vw, 640px" src="/cdn-cgi/image/width=640/photo.jpg" alt="Responsive image" />

人脸感知裁剪：

fetch(imageURL, {
  cf: {
    image: {
      width: 200,
      height: 200,
      fit: "cover",
      gravity: "face",
      zoom: 0.5, // 0 = more background, 1 = tight crop
    },
  },
});

Direct Creator Upload：

# Get one-time upload URL
curl --request POST \
  https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v2/direct_upload \
  --header "Authorization: Bearer <API_TOKEN>"

# Response: { "uploadURL": "https://upload.imagedelivery.net/..." }

从 Worker 上传：

const image = await fetch("https://example.com/image.png");
const bytes = await image.bytes();

const formData = new FormData();
formData.append("file", new File([bytes], "image.png"));

await fetch(`https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/images/v1`, {
  method: "POST",
  headers: { Authorization: `Bearer ${TOKEN}` },
  body: formData,
});

适用场景

大规模存储和交付优化图片
实时转换远程图片
调整尺寸、裁剪、转换图片格式
为图片添加水印
使用 srcset 提供响应式图片
使用签名 URL 保护图片
优化来自 R2 存储的图片

限制

最大图片尺寸：12,000 像素
最大图片面积：100 百万像素
最大文件大小（转换）：70 MB
最大文件大小（存储）：10 MB
GIF/WebP 动画：总计 50 百万像素
AVIF 输出硬限制：1,200 px（显式指定 1,600）
每账户变体数：100

关键禁止事项

切勿为整个 zone（/*）设置 Image Resizing Worker——会拦截非图片请求
切勿同时启用 Polish 和图像转换——压缩冗余
切勿将灵活变体与签名 URL 令牌一起使用——不兼容
切勿在 requireSignedURLs=true 时使用自定义 ID 路径——不支持
切勿期望 SVG 被调整尺寸——SVG 按原样直通
切勿在 cacheKey 中包含调整尺寸选项——会碎片化缓存

故障排查

无 Cf-Resized 响应头：

该 zone 未启用转换
另一个 Worker 拦截了请求
使用仪表板预览（不模拟转换）

常见错误码：

9401：无效的转换选项
9402：图片过大
9403：检测到请求循环
9422：超出免费层限制（5,000/月）
9520：不支持的格式

技能介绍

用途