cloudflare-images

Cloudflare Images

状态：已投入生产 ✅ 最后更新：2026-01-21 依赖项：已启用 Images 的 Cloudflare 账户 最新版本：Cloudflare Images API v2，@cloudflare/[email protected]

近期更新（2025）：

• 2025 年 2 月：支持 Content Credentials（C2PA 标准）——保留图像来源链，并自动对转换进行加密签名
• 2025 年 8 月：AI 人脸裁剪正式发布（gravity=face 支持 zoom 控制，基于 GPU 的 RetinaFace，精度达 99.4%）
• 2025 年 5 月：Media Transformations 源站限制（默认仅限同域，可通过控制面板配置）
• 即将推出：背景移除、生成式放大（计划中的功能）

弃用通知：Mirage 已于 2025 年 9 月 15 日弃用。请迁移到 Cloudflare Images 进行存储/转换，或使用原生 <img loading="lazy"> 实现延迟加载。

---

概览

两项功能：Images API（上传/存储并使用变体）和 图像转换（通过 URL 或 Workers 调整任意图像的尺寸）。

---

快速开始

1. 启用：控制面板 → Images → 获取账户 ID + API 令牌（Cloudflare Images：Edit 权限）

2. 上传：

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

3. 提供图像：https://imagedelivery.net/<ACCOUNT_HASH>/<IMAGE_ID>/public

4. 转换（可选）：控制面板 → Images → Transformations → 为区域启用

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

---

上传方式

1. 文件上传：向 /images/v1 发送 POST 请求，并附带 file（multipart/form-data），可选参数为 id、requireSignedURLs、metadata

2. 通过 URL 上传：发送 POST 请求，并附带 url=https://example.com/image.jpg（支持 HTTP 基本身份验证）

3. Direct Creator Upload（一次性 URL，不会暴露 API 密钥）：

后端：向 /images/v2/direct_upload 发送 POST 请求 → 返回 uploadURL 前端：使用 FormData 将文件 POST 到 uploadURL

关键 CORS 修复：

• ✅ 使用 multipart/form-data（让浏览器设置标头）
• ✅ 字段名设为 file（而不是 image）
• ✅ 仅从后端调用 /direct_upload
• ❌ 不要设置 Content-Type: application/json
• ❌ 不要从浏览器调用 /direct_upload

---

图像转换

URL：/cdn-cgi/image/<OPTIONS>/<SOURCE>

• 尺寸：width=800,height=600,fit=cover
• 质量：quality=85（1-100）
• 格式：format=auto（自动检测 WebP/AVIF）
• 裁剪：gravity=auto（智能裁剪），gravity=face（AI 人脸检测，2025 年 8 月正式发布），gravity=center，zoom=0.5（范围为 0-1，用于控制人脸裁剪紧密度）
• 效果：blur=10,sharpen=3,brightness=1.2
• 适配方式：scale-down、contain、cover、crop、pad

Workers：在 fetch 中使用 cf.image 对象

fetch(imageURL, {
  cf: {
    image: { width: 800, quality: 85, format: 'auto', gravity: 'face', zoom: 0.8 }
  }
});

---

变体

命名变体（最多 100 个）：预定义的转换（例如 avatar、thumbnail）

• 创建：向 /images/v1/variants 发送 POST 请求，并附带 id、options
• 使用：imagedelivery.net/<HASH>/<ID>/avatar
• 支持签名 URL

灵活变体：URL 中的动态参数（w=400,sharpen=3）

• 启用：向 /images/v1/config 发送 PATCH 请求，并附带 {"flexible_variants": true}
• ❌ 不能与签名 URL 一起使用（请改用命名变体）

---

签名 URL

为私有图像生成 HMAC-SHA256 令牌（URL 格式：?exp=<TIMESTAMP>&sig=<HMAC>）。

算法：HMAC-SHA256(signingKey, imageId + variant + expiry) → 十六进制签名

参见：templates/signed-urls-generation.ts 中的 Workers 实现

---

关键规则

务必做到

✅ 对 Direct Creator Upload 使用 multipart/form-data ✅ 文件字段名设为 file（而不是 image 或其他名称） ✅ 仅从后端调用 /direct_upload API（不要从浏览器调用） ✅ 对转换使用 HTTPS URL（不支持 HTTP） ✅ 对图像路径中的特殊字符进行 URL 编码 ✅ 使用 /cdn-cgi/image/ 前，先为区域启用转换 ✅ 对私有图像使用命名变体（签名 URL） ✅ 检查 Cf-Resized 标头以确认转换是否出错 ✅ 设置 format=auto，自动转换为 WebP/AVIF ✅ 使用 fit=scale-down，防止图像意外放大

切勿执行

❌ 上传文件时使用 application/json Content-Type ❌ 在浏览器中调用 /direct_upload（CORS 会失败） ❌ 在 requireSignedURLs=true 时使用灵活变体 ❌ 调整 SVG 文件的大小（它们本身即可缩放） ❌ 使用 HTTP URL 进行转换（仅支持 HTTPS） ❌ 在 URL 中使用空格或未经转义的 Unicode 字符 ❌ 在 Workers 中多次转换同一张图片（会导致 9403 循环） ❌ 图片大小超过 100 megapixels ❌ 在 Workers 中使用 /cdn-cgi/image/ 端点（请改用 cf.image） ❌ 忘记在使用前为 zone 启用转换

---

已知问题预防

此技能可预防 16 个有记录的问题。

问题 #1：直接创建者上传 CORS 错误

错误：Access to XMLHttpRequest blocked by CORS policy: Request header field content-type is not allowed

来源：Cloudflare 社区 #345739、#368114

原因：服务器 CORS 设置仅允许 Content-Type 标头使用 multipart/form-data

预防：

// ✅ CORRECT
const formData = new FormData();
formData.append('file', fileInput.files[0]);
await fetch(uploadURL, {
  method: 'POST',
  body: formData // Browser sets multipart/form-data automatically
});

// ❌ WRONG
await fetch(uploadURL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' }, // CORS error
  body: JSON.stringify({ file: base64Image })
});

问题 #2：错误 5408 - 上传超时

错误：上传约 15 秒后出现 Error 5408

来源：Cloudflare 社区 #571336

原因：Cloudflare 的请求超时时间为 30 秒；上传速度过慢或文件过大都会超出限制

预防：

• 上传前压缩图片（在客户端使用 Canvas API）
• 设置合理的文件大小限制（例如，最大 10MB）
• 向用户显示上传进度
• 妥善处理超时错误

const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB

if (file.size > MAX_FILE_SIZE) {
  alert('File too large. Please select an image under 10MB.');
  return;
}

问题 #3：错误 400 - 文件参数无效

错误：400 Bad Request，且错误消息没有提供有用信息

来源：Cloudflare 社区 #487629

原因：文件字段必须命名为 file（不能是 image、photo 等）

预防：

// ✅ CORRECT
formData.append('file', imageFile);

// ❌ WRONG
formData.append('image', imageFile); // 400 error
formData.append('photo', imageFile); // 400 error

问题 #4：CORS 预检失败

错误：预检 OPTIONS 请求被阻止

来源：Cloudflare 社区 #306805

原因：直接从浏览器调用 /direct_upload API（此操作应仅由后端执行）

预防：

ARCHITECTURE:
Browser → Backend API → POST /direct_upload → Returns uploadURL → Browser uploads to uploadURL

切勿向浏览器公开 API 令牌。在后端生成上传 URL，并返回给前端。

问题 #5：错误 9401 - 参数无效

错误：Cf-Resized: err=9401 - 缺少必需的 cf.image 选项，或选项无效

来源：Cloudflare Images 文档 - 故障排查

原因：缺少必需的转换参数，或参数值无效

预防：

// ✅ CORRECT
fetch(imageURL, {
  cf: {
    image: {
      width: 800,
      quality: 85,
      format: 'auto'
    }
  }
});

// ❌ WRONG
fetch(imageURL, {
  cf: {
    image: {
      width: 'large', // Must be number
      quality: 150 // Max 100
    }
  }
});

问题 #6：错误 9402 - 图片过大

错误：Cf-Resized: err=9402 - 图片过大或连接中断

来源：Cloudflare Images 文档 - 故障排查

原因：图片超过最大面积（100 megapixels）或下载失败

预防：

• 转换前验证图片尺寸
• 使用大小合理的源图片（最大 10000x10000px）
• 妥善处理网络错误

问题 #7：错误 9403 - 请求循环

错误：Cf-Resized: err=9403 - Worker 正在获取自身 URL 或已调整大小的图片

来源：Cloudflare Images 文档 - 故障排查

原因：对已转换的图片再次应用转换，或 Worker 获取自身内容

预防：

// ✅ CORRECT
if (url.pathname.startsWith('/images/')) {
  const originalPath = url.pathname.replace('/images/', '');
  const originURL = `https://storage.example.com/${originalPath}`;
  return fetch(originURL, { cf: { image: { width: 800 } } });
}

// ❌ WRONG
if (url.pathname.startsWith('/images/')) {
  // Fetches worker's own URL, causes loop
  return fetch(request, { cf: { image: { width: 800 } } });
}

问题 #8：错误 9406/9419 - URL 格式无效

错误：Cf-Resized: err=9406 或 err=9419 - URL 不是 HTTPS，或 URL 中包含空格/未转义的 Unicode 字符

来源：Cloudflare Images 文档 - 故障排除

原因：图片 URL 使用 HTTP（而非 HTTPS），或包含无效字符

预防措施：

// ✅ CORRECT
const imageURL = "https://example.com/images/photo%20name.jpg";

// ❌ WRONG
const imageURL = "http://example.com/images/photo.jpg"; // HTTP not allowed
const imageURL = "https://example.com/images/photo name.jpg"; // Space not encoded

URL 路径始终使用 encodeURIComponent()：

const filename = "photo name.jpg";
const imageURL = `https://example.com/images/${encodeURIComponent(filename)}`;

问题 #9：错误 9412 - 响应内容不是图片

错误：Cf-Resized: err=9412 - 源站返回的是 HTML，而非图片

来源：Cloudflare Images 文档 - 故障排除

原因：源站服务器返回 404 页面或错误页面（HTML），而非图片

预防措施：

// Verify URL before transforming
const originResponse = await fetch(imageURL, { method: 'HEAD' });
const contentType = originResponse.headers.get('content-type');

if (!contentType?.startsWith('image/')) {
  return new Response('Not an image', { status: 400 });
}

return fetch(imageURL, { cf: { image: { width: 800 } } });

问题 #10：错误 9413 - 超出图片最大面积

错误：Cf-Resized: err=9413 - 图片超过 100 百万像素

来源：Cloudflare Images 文档 - 故障排除

原因：源图片尺寸超过 100 百万像素（例如，10000x10000px）

预防措施：

• 上传前验证图片尺寸
• 预处理超大图片
• 拒绝超过阈值的图片

const MAX_MEGAPIXELS = 100;

if (width * height > MAX_MEGAPIXELS * 1_000_000) {
  return new Response('Image too large', { status: 413 });
}

问题 #11：灵活变体与签名 URL 不兼容

错误：灵活变体不能用于私有图片

来源：Cloudflare Images 文档 - 启用灵活变体

原因：requireSignedURLs=true 时不能使用灵活变体

预防措施：

// ✅ CORRECT - Use named variants for private images
await uploadImage({
  file: imageFile,
  requireSignedURLs: true // Use named variants: /public, /avatar, etc.
});

// ❌ WRONG - Flexible variants don't support signed URLs
// Cannot use: /w=400,sharpen=3 with requireSignedURLs=true

问题 #12：SVG 缩放限制

错误：SVG 文件无法通过转换调整大小

来源：Cloudflare Images 文档 - SVG 文件

原因：SVG 本身具有可缩放性（矢量格式），不适用调整大小

预防措施：

// SVGs can be served but not resized
// Use any variant name as placeholder
// https://imagedelivery.net/<HASH>/<SVG_ID>/public

// SVG will be served at original size regardless of variant settings

问题 #13：格式会剥离 EXIF 元数据

错误：上传的图片中 GPS 数据、相机设置等信息被移除

来源：Cloudflare Images 文档 - 通过 URL 转换

原因：默认行为是剥离除版权信息以外的所有元数据。重要：WebP 和 PNG 输出格式始终会丢弃元数据，不受设置影响——只有 JPEG 支持保留元数据。

预防措施：

// ✅ CORRECT - JPEG preserves metadata
fetch(imageURL, {
  cf: {
    image: {
      width: 800,
      format: 'jpeg', // or 'auto' (may become jpeg)
      metadata: 'keep' // Preserves most EXIF including GPS
    }
  }
});

// ❌ WRONG - WebP/PNG ignore metadata setting
fetch(imageURL, {
  cf: {
    image: {
      format: 'webp',
      metadata: 'keep' // NO EFFECT - always stripped for WebP/PNG
    }
  }
});

元数据选项（仅限 JPEG）：

• none：剥离所有元数据
• copyright：仅保留版权标签（JPEG 的默认值）
• keep：保留大部分 EXIF 元数据，包括 GPS 信息

格式支持：

• ✅ JPEG：所有元数据选项均有效
• ❌ WebP：始终剥离元数据（相当于 none）
• ❌ PNG：始终剥离元数据（相当于 none）

问题 #14：AVIF 分辨率限制存在歧义

错误：大型 AVIF 转换失败，或降至较低分辨率

来源：Cloudflare 文档 + 社区报告

原因：官方文档指出，format=avif 的硬性限制为 1,600px，但社区报告表明，截至 2024 年底，最长边的实际限制为 1200px。注意：官方文档（1600px）与报告的行为（1200px）存在差异，需要核实。

预防措施：

// ✅ RECOMMENDED - Use format=auto instead of explicit avif
fetch(imageURL, {
  cf: {
    image: {
      width: 2000,
      format: 'auto' // Cloudflare chooses best format
    }
  }
});

// ⚠️ MAY FAIL - Explicit AVIF with large dimensions
fetch(imageURL, {
  cf: {
    image: {
      width: 2000,
      format: 'avif' // May fail if >1200px
    }
  }
});

// ✅ WORKAROUND - Use WebP for larger images
if (width > 1200) {
  format = 'webp'; // WebP supports larger dimensions
} else {
  format = 'avif'; // AVIF for smaller images
}

问题 #15：按设备类型缓存图像（社区反馈）

错误：桌面设备和移动设备看到的缓存版本不同，出现意外的缓存未命中

来源：Cloudflare 社区

原因：图像会意外地按设备类型缓存，且缓存规则中没有可禁用此行为的配置选项。截至 2024 年 12 月，多位用户确认存在此行为。

预防措施：

• 了解清除缓存时需要针对每种设备类型分别清除
• 通过 Cloudflare 控制面板，按设备类型手动清除缓存
• 在缓存失效策略中考虑按设备类型缓存的情况

解决方案／变通方法： 需要时，通过 Cloudflare 控制面板按设备类型手动清除缓存。

问题 #16：PNG 默认不缓存

错误：其他图像格式可以缓存，但 PNG 图像无法缓存

来源：Cloudflare 社区

原因：Cloudflare 默认缓存的文件扩展名不包含 .png。默认缓存的扩展名：.jpg、.jpeg、.gif、.webp、.bmp、.ico、.svg、.tif、.tiff（缺少 PNG）。

预防措施： 为 PNG 文件创建明确的缓存规则：

1. 控制面板 → 缓存 → 缓存规则
2. 添加规则：URI Path ends with .png → Cache Everything

---

使用捆绑资源

模板（templates/）

可直接复制粘贴的常见模式代码：

1. wrangler-images-binding.jsonc - Wrangler 配置（无需绑定）
2. upload-api-basic.ts - 将文件上传到 Images API
3. upload-via-url.ts - 从外部 URL 导入图像
4. direct-creator-upload-backend.ts - 生成一次性上传 URL
5. direct-creator-upload-frontend.html - 用户上传表单
6. transform-via-url.ts - URL 转换示例
7. transform-via-workers.ts - Workers 转换模式
8. variants-management.ts - 创建／列出／删除变体
9. signed-urls-generation.ts - HMAC-SHA256 签名 URL 生成
10. responsive-images-srcset.html - 响应式图像模式
11. batch-upload.ts - 用于大批量上传的批处理 API

用法：

cp templates/upload-api-basic.ts src/upload.ts
# Edit with your account ID and API token

参考资料（references/）

Claude 可按需加载的深入文档：

1. api-reference.md - 完整的 API 端点（上传、列出、删除、变体）
2. transformation-options.md - 所有转换参数及示例
3. variants-guide.md - 命名变体与灵活变体，以及各自的适用场景
4. signed-urls-guide.md - HMAC-SHA256 实现详情
5. direct-upload-complete-workflow.md - 完整架构和流程
6. responsive-images-patterns.md - srcset、sizes、艺术指导
7. format-optimization.md - WebP／AVIF 自动转换策略
8. top-errors.md - 全部 13+ 个错误及详细故障排查说明

加载时机：

• 深入了解特定功能
• 排查复杂问题
• 了解 API 详情
• 实现高级模式

脚本（scripts/）

check-versions.sh - 验证 API 端点是否为最新

高级主题

自定义域名：通过 /cdn-cgi/imagedelivery/<HASH>/<ID>/<VARIANT> 从你的域名提供服务（要求域名托管在 Cloudflare 上并启用代理）。使用 Transform Rules 设置自定义路径。

批量 API：通过 batch.imagedelivery.net 和批量令牌进行高容量上传（Dashboard → Images → Batch API）

Webhook：Direct Creator Upload 通知（Dashboard → Notifications → Webhooks）。负载包含 imageId、status、metadata。

内容凭证（C2PA）：Cloudflare Images 会保留并签署图像溯源链。使用内容凭证转换图像时，Cloudflare 会自动将转换操作追加到清单中，并使用 DigiCert 证书进行加密签名。通过 Dashboard → Images → Transformations → Preserve Content Credentials 启用。注意：仅当源图像已包含 C2PA 元数据时才有效（某些相机、DALL-E、兼容的编辑软件）。可在 contentcredentials.org/verify 验证。

浏览器缓存 TTL：默认浏览器缓存 TTL 为 2 天（172,800 秒）。可自定义为 1 小时至 1 年（账户级或按变体设置）。重要：私有图像（签名 URL）不遵循 TTL 设置。使用相同的 Custom ID 重新上传图像时可能会出现问题——用户最多可能在 2 天内看到旧版本。解决方案：使用唯一图像 ID（附加时间戳/哈希），或在重新上传后手动清除缓存。

产品合并迁移（2023 年 11 月）：Cloudflare 将 Image Resizing 合并到 Images 产品中，并采用新的定价：每月每 1,000 次唯一转换收费 $0.50（每 30 天按每项唯一转换计费一次）。迁移注意事项：旧版 Image Resizing 按未缓存请求计费（成本会因缓存行为变化而难以预测）。新计费方式按“唯一转换”（图像 ID + 参数组合）而非请求次数计费。每月请求同一转换 1,000 次 = 仅计费一次。现有客户可以继续使用旧版，也可以自愿迁移。

通过 R2 集成优化成本：Cloudflare Images 基于 R2 + Image Resizing 构建。若要节省成本，可将原始图像存储在 R2 中，并按需使用 Image Transformations：

1. 将图像上传到 R2 存储桶
2. 通过自定义域名提供服务，并使用 /cdn-cgi/image/ 转换
3. 不存储变体（转换是临时的/会缓存）

成本比较：

• R2：10GB 存储 + 不限流量（免费层级）
• Cloudflare Images：$5/月（100k 张图像）+ 每 100k 次转换 $1
• R2 + Transformations：R2 存储 + 每 1k 次唯一转换 $0.50

适用场景：如果不需要命名变体、批量上传或 Direct Creator Upload 功能，R2 更具成本效益。

使用 R2 的 Workers 示例模式：

export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    const imageKey = url.pathname.replace('/images/', '');
    const originURL = `https://r2-bucket.example.com/${imageKey}`;

    return fetch(originURL, {
      cf: {
        image: {
          width: 800,
          quality: 85,
          format: 'auto'
        }
      }
    });
  }
};

参考：Cloudflare Reference Architecture

---

故障排除

问题：图像未进行转换

症状：/cdn-cgi/image/... 返回原始图像或 404

解决方案：

1. 在区域上启用转换：Dashboard → Images → Transformations → Enable for zone
2. 确认区域已通过 Cloudflare 代理（橙色云朵）
3. 检查源图像是否可公开访问
4. 等待 5-10 分钟，让设置生效

问题：直接上传返回 CORS 错误

症状：浏览器控制台中出现 Access-Control-Allow-Origin 错误

解决方案：

1. 使用 multipart/form-data 编码（让浏览器设置 Content-Type）
2. 不要从浏览器调用 /direct_upload；应从后端调用
3. 将文件字段命名为 file（而不是 image）
4. 移除手动设置的 Content-Type 标头

问题：Worker 转换返回 9403 循环错误

症状：响应标头中出现 Cf-Resized: err=9403

解决方案：

1. 不要获取 Worker 自身的 URL（使用外部来源）
2. 不要转换已经调整过大小的图像
3. 检查 URL 路由逻辑，避免循环

问题：签名 URL 无法使用

症状：访问签名 URL 时返回 403 Forbidden

解决方案：

1. 确认上传图片时使用了 requireSignedURLs=true
2. 检查签名生成方式（HMAC-SHA256）
3. 确保过期时间戳在未来
4. 确认签名密钥与控制面板中的密钥一致（Images → Keys）
5. 签名 URL 不能使用灵活变体（请使用命名变体）

问题：图片已上传但未显示

症状：上传返回 200 OK，但图片未出现在控制面板中

解决方案：

1. 检查响应中是否有 draft: true（Direct Creator Upload）
2. 等待上传完成（通过 GET /images/v1/{id} 检查）
3. 确认账户 ID 匹配
4. 检查 Webhook 中是否有上传错误

问题：重新上传的图片仍显示旧版本

症状：即使从未访问过页面的用户，在重新上传后也会看到旧图片

解决方案：

1. 每次上传都使用唯一的图片 ID：const imageId = \${baseId}-${Date.now()}`;`
2. 设置较短的 Cache-Control 标头（例如，max-age=86400，即 1 天，而不是 30 天）
3. 使用相同 ID 重新上传后，通过控制面板手动清除缓存
4. 请注意，默认的浏览器缓存 TTL 为 2 天，用户可能会看到缓存版本

根本原因：Cloudflare 会遵循源站的 Cache-Control 标头。如果源站设置了较长的 max-age（例如 30 天），即使使用相同 ID 重新上传，图片仍会保留在缓存中。

问题：PNG 图片未被缓存

症状：PNG 图片绕过缓存，而其他格式（JPEG、WebP）可以正常缓存

解决方案：

1. 创建明确的缓存规则：Dashboard → Caching → Cache Rules
2. 添加规则：URI Path ends with .png → Cache Everything
3. 默认缓存扩展名不包括 .png（仅包含 .jpg、.jpeg、.gif、.webp、.bmp、.ico、.svg、.tif、.tiff）

---

官方文档

• Cloudflare Images：https://developers.cloudflare.com/images/
• 入门指南：https://developers.cloudflare.com/images/get-started/
• 上传图片：https://developers.cloudflare.com/images/upload-images/
• Direct Creator Upload：https://developers.cloudflare.com/images/upload-images/direct-creator-upload/
• 转换图片：https://developers.cloudflare.com/images/transform-images/
• 通过 URL 转换：https://developers.cloudflare.com/images/transform-images/transform-via-url/
• 通过 Workers 转换：https://developers.cloudflare.com/images/transform-images/transform-via-workers/
• 创建变体：https://developers.cloudflare.com/images/manage-images/create-variants/
• 提供私有图片：https://developers.cloudflare.com/images/manage-images/serve-images/serve-private-images/
• 故障排除：https://developers.cloudflare.com/images/reference/troubleshooting/
• API 参考：https://developers.cloudflare.com/api/resources/images/

---

包版本

最后验证日期：2026-01-21 API 版本：v2（直接上传），v1（标准上传） 可选：@cloudflare/[email protected]

---

技能版本：2.1.0 | 变更：新增 3 个问题（AVIF 限制、按设备缓存、PNG 缓存），完善了包含格式详情的元数据问题，新增 Content Credentials、浏览器缓存 TTL、Product Merge 说明、R2 集成模式、Mirage 弃用通知和缓存故障排除指南。错误数量：13 → 16。