HGfast Cloud 灵狐加速 · 一站式全球云网络返回首页

Cloudflare Images是什么?怎么用:上传、缩放、裁剪与费用排查指南

更新于 2026-11-20 · hgfastapp.lol

简答:Cloudflare Images 是用于图片托管、缩放、裁剪、格式转换和边缘交付的图片服务。你可以选择托管图片,或保留源站图片后用 Transformations 处理;当前免费计划、付费价格和账户可用功能应以你查看当天的官方 Pricing 页面为准。

定义:Cloudflare Images 是一套把图片存储、处理和交付组合在一起的云端图片服务,也支持对外部源站图片进行边缘转换。

先判断:你应该用哪条 Cloudflare Images 路径

本文为独立技术整理,不代表 Cloudflare 官方;操作时请以你查看当天的控制台界面和官方文档为准。最快的判断方法不是先上传图片,而是先确认图片现在放在哪里,以及是否需要用户上传。

需求建议路径适合场景主要注意点
图片已经在自己的网站、R2或其他源站Images Transformations只想缩放、裁剪、压缩或转换格式源图必须能被服务获取;需要配置允许的源站
想让Cloudflare负责存储、处理和交付托管到 Cloudflare Images产品图、头像、用户媒体库托管存储和交付使用独立计费指标
想保留对象存储控制权R2 + Images Transformations需要存储桶权限、生命周期或自定义媒体管线图片处理与对象存储要分别设计
需要在请求中动态处理原始字节Workers Images Binding需要鉴权、组合处理、非公开源图或复杂逻辑Binding调用不会自动缓存,应自行配置缓存
让终端用户直接上传Direct Creator Upload头像上传、投稿、商品图片上传后端生成一次性上传地址,令牌不能放到浏览器

官方入门文档将主要路径分为“优化远程图片”和“上传并交付图片”:前者保留源站,后者把图片放入 Images 存储;官方也建议在需要精细对象存储权限或生命周期管理时考虑 R2,再使用 Images 做转换。可查看 Cloudflare Images 入门说明。

Cloudflare Images怎么开始:5步完成基础配置

  1. 准备账户和域名。登录 Cloudflare Dashboard,选择目标账户和已接入的站点。若只是处理远程图片,先确认源图所在域名可被服务端访问。
  2. 选择存储方式。需要托管图片时进入 Images 相关功能创建或使用托管图片存储;只做远程转换时,不必先把原图迁移到 Images。
  3. 开启 Transformations。在目标站点的图片优化功能中启用 Transformations,并按实际界面配置允许的源站。官方文档说明,默认情况下通常只接受与转换服务同一站点的源图片,跨源站使用前要检查允许列表。
  4. 先做一个固定尺寸测试。用一张公开可访问的图片测试宽度、裁剪方式和输出格式,确认源图状态码、响应类型和访问权限都正常。
  5. 再接入业务代码。固定尺寸可用后,再接入响应式宽度、预定义变体、Direct Creator Upload或Workers Binding,避免一开始同时排查多个变量。

Transformations在缓存命中时可直接返回已经生成的版本;缓存未命中时会重新获取原图、执行参数并缓存结果。具体流程可参阅 Transformations工作原理与配置文档。

如果控制台菜单名称与你看到的界面不同,应以当前账户实际界面为准,不要仅凭旧教程判断功能是否不存在。

远程图片怎么缩放、裁剪和转格式

远程图片转换适合“原图仍由自己管理,但希望按访问场景输出不同尺寸”的网站。常见的参数是 width、height、fit、quality 和 format。示例中的域名、账户标识和路径均为占位符,不能直接当作真实地址使用。

https://img.example.com/cdn-cgi/image/width=800,height=450,fit=cover,quality=80,format=auto/source/photo.jpg
  • width=800:设置输出宽度为800像素。
  • height=450:设置目标高度;是否裁剪取决于fit。
  • fit=cover:填满目标区域,必要时裁剪,适合卡片封面。
  • fit=contain:完整显示图片并保留比例,适合商品图或证件图。
  • fit=scale-down:只缩小、不放大,适合避免小图被强行放大。
  • quality=80:设置压缩质量;质量越高通常文件越大,但实际效果仍需用目标图片测试。
  • format=auto:让服务根据请求环境选择可用输出格式。

官方参数文档说明,width和height的最终表现会受到fit影响,quality可使用固定数值或感知质量等级。完整参数以 Images Features参数文档 为准。

一个实用的选择顺序是:头像或商品卡片用固定宽高加cover;文章正文使用单独的宽度并保留比例;不希望小图放大时使用scale-down;需要响应式图片时再测试width=auto和浏览器 Client Hints。

托管图片怎么上传:控制台、API与Direct Creator Upload

控制台上传

控制台适合少量手动上传。官方文档给出的流程是进入账户的 Images & Stream、Hosted images 页面,再通过上传区域选择本地文件。上传完成后,图片会出现在托管图片列表,并可使用已有或新建的变体地址。

API上传

API适合后台批量管理。下面是上传远程图片的结构示例,令牌只应在服务器或受保护的CI环境中使用:

curl --request POST \
  "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/images/v1" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --form "url=https://static.example.com/photo.jpg" \
  --form "requireSignedURLs=true"

file和url是两种互斥的上传方式;API返回结果通常会包含图片ID和可用变体地址。官方上传说明见 Images上传方式文档,远程URL示例见 通过URL上传图片。

Direct Creator Upload

如果是用户上传头像或投稿图片,不要把主API Token交给浏览器。后端先调用/images/v2/direct_upload生成一次性上传地址,再把上传地址传给前端;前端使用该地址提交图片,后端保存返回的图片ID。官方文档明确说明,这种方式可以让用户直接上传而不暴露API密钥或令牌。

curl --request POST \
  "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/images/v2/direct_upload" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --form "requireSignedURLs=true"

上传前还应在后端限制文件类型、大小、用户身份和业务配额;图片上传成功不等于业务审核完成。Direct Creator Upload的官方说明见 Accept user-uploaded images。

预定义变体怎么创建,访问地址怎么拼

预定义变体适合把“头像、缩略图、横幅”等固定尺寸统一成名称,减少业务代码里散落大量参数。官方文档说明,默认可以使用public变体,也可以创建自定义变体;当前文档写明最多可创建100个变体,具体账户限制仍应以控制台和官方文档为准。

控制台路径通常是 Hosted images → Delivery → Create variant,然后设置变体名称、宽高、fit和元数据策略。也可以通过API创建:

curl "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/images/v1/variants" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{"id":"thumb","options":{"fit":"cover","metadata":"none","width":400,"height":300},"neverRequireSignedURLs":true}'

托管图片的访问地址通常由账户的图片交付域名、图片ID和变体名组成,结构类似:

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

是否公开访问取决于图片和变体的签名URL设置。若图片包含用户隐私、内部资料或未发布内容,应优先使用签名访问,并在后端控制签名生成和有效期。创建变体的字段和fit行为可查看 Create predefined variants。

Cloudflare Images、Transformations、R2和Workers Binding区别

组件主要职责是否负责原图存储适合谁
Cloudflare Images托管图片存储、变体、交付和图片管理是想减少自建图片管线的团队
Images Transformations对远程图片做缩放、裁剪、压缩和格式转换否已有源站或R2图片的网站
R2对象存储、访问控制、生命周期和自定义目录是需要更细存储控制的应用
Workers Images Binding在Worker中用原始字节执行图片处理不一定需要鉴权、组合处理或动态逻辑的开发者

Images Binding与URL接口的关键区别是:URL接口要求源图片可通过URL访问,而Binding可以接收Images、R2、fetch响应或请求体中的原始图片字节。官方文档还提醒,Binding响应不会自动缓存,应按业务设置Workers Cache和响应头。配置方式与示例见 Optimize with Workers。

export default {
  async fetch(request, env) {
    const source = await fetch("https://static.example.com/photo.jpg");
    const result = await env.IMAGES
      .input(source.body)
      .transform({ width: 800, fit: "scale-down" })
      .output({ format: "image/webp" });
    return result.response({
      headers: { "Cache-Control": "public, max-age=3600" }
    });
  }
};

费用怎么核对:不要只看图片访问次数

截至2026-11-20检索到的官方 Pricing 页面,Images Free计划包含每月最多5,000次唯一转换;超过后,已有缓存版本继续提供,新转换可能返回9422错误,免费计划超出部分不会按超额量收费。付费计划页面列出的指标包括转换、存储和交付,具体价格和账户账单仍应以你查看当天的官方页面为准。

使用方式主要计费指标核对重点
转换外部源站或R2图片Images Transformed同一原图与同一组参数在当月通常按唯一转换计算
使用Images托管图片Images Stored、Images Delivered存储图片数量与成功交付请求分别核对
Workers Images Binding唯一转换每个源图与参数组合计入当月转换;.info()是否计费需按当前文档核对

官方 Pricing 页面说明,转换是否唯一取决于源图片和优化参数组合;重复请求同一转换在同一自然月内不会重复计算。页面还特别说明,format和quality在唯一转换判断中的处理有特定规则,不能简单按每个输出文件格式相加。请直接查看 Cloudflare Images Pricing 的当前版本。

当前官方变更记录还显示,Hosted Images Analytics可查看最多30天的交付数据,并能按状态码、国家、ASN、引用来源、浏览器和变体分析请求。需要核对异常流量时,可查看 Hosted Images Analytics更新说明。

图片打不开、变体无效或缓存未更新怎么排查

  1. 先查源图。用浏览器或命令行确认源图返回成功状态、正确的Content-Type,并且不是登录后才能访问。远程转换无法获取需要认证的源图时,先解决源站权限。
  2. 再查来源限制。确认转换请求中的源图片域名已经加入允许列表。跨域名、重定向链或临时URL都可能导致源图无法被正常获取。
  3. 核对参数。先删除所有参数,只请求原图;再逐个加入width、height、fit和format。变体名称必须与控制台或API创建的名称完全一致。
  4. 检查签名。私有图片需要有效签名;签名过期、路径变化、时间戳不一致都会造成访问失败。不要把签名密钥写入前端代码。
  5. 最后查缓存。原图已经替换但输出仍旧不变时,确认请求URL是否真的变化,并按业务规则处理缓存失效;不要在未确认缓存层级前反复改源图。

如果想区分“源图获取失败”和“转换参数错误”,可以先使用最简单的公开图片做对照,再逐步替换为真实源图。对于托管图片,可在Hosted Images Analytics中按响应状态码和变体查看交付异常。

安全与接入清单:上线前逐项确认

  • API Token只放在服务器、Worker密钥或受保护的部署环境,不放在HTML、React前端包或公开仓库。
  • 用户上传流程使用Direct Creator Upload一次性地址,并在后端限制用户、文件类型、文件大小和上传次数。
  • 私有图片启用签名访问;公开变体不要误用于内部图片。
  • 源站允许列表只加入确实需要转换的域名,避免把任意远程URL变成图片代理。
  • 固定尺寸优先使用预定义变体,动态参数要限制尺寸范围,避免业务代码产生大量无意义的唯一转换。
  • Workers Binding处理后的图片设置合适的Cache-Control,并根据实际更新策略决定缓存时间。
  • 上线前分别测试原图、缩略图、移动端宽度、错误格式、过期签名和源图替换后的缓存行为。

如果你的核心问题不是图片处理,而是网站访问延迟、源站连接或Cloudflare缓存策略,可继续查看站内的Cloudflare CDN接入与缓存验证指南;如果重点是对象存储权限和文件管理,可查看Cloudflare R2创建存储桶与访问配置指南。两页分别负责网络交付和对象存储,不替代本文的图片处理选型。

常见问题

Cloudflare Images是CDN还是对象存储?

它不是单一的传统CDN或普通对象存储,而是把图片托管、处理和交付组合起来的服务。Transformations还可以处理放在外部源站或R2中的图片,因此是否使用Images托管存储要按权限、生命周期和业务复杂度选择。

Cloudflare Images免费吗?

官方 Pricing 页面显示,Images Free计划包含每月最多5,000次唯一转换;Images托管存储、图片交付和超出后的具体规则要按当前计划核对,不能只根据“免费”判断所有功能都没有费用。

Cloudflare Images和R2怎么选?

想少配置、直接获得托管图片和预定义变体时优先考虑Images;需要存储桶级权限、生命周期、目录和自定义媒体管线时,可选择R2并用Images做图片转换。

用户上传图片时,API Token能不能放到前端?

不建议。后端应调用Direct Creator Upload接口生成一次性上传地址,再让浏览器把图片提交到该地址;主API Token和签名密钥始终保留在服务端。

为什么Cloudflare Images变体地址访问失败?

先确认图片ID、账户交付域名和变体名称完全匹配,再检查图片是否要求签名、签名是否过期,以及该变体是否被设置为允许公开访问。

width、height和fit应该怎么搭配?

头像和卡片通常使用固定宽高加cover;需要完整显示图片时使用contain;不希望放大原图时使用scale-down。先用一张公开图片测试,再把参数接入生产页面。

图片已经替换,为什么访问结果仍然没变化?

可能是边缘缓存、浏览器缓存、应用缓存或请求URL没有变化。先确认源图本身已更新,再查看请求响应和缓存状态,必要时按当前缓存策略更新URL或执行合适的失效操作。

相关阅读

参考资料

  1. Introduction · Cloudflare Images docs
  2. Overview · Cloudflare Images Transformations
  3. Features · Cloudflare Images
  4. Methods · Cloudflare Images upload images
  5. Upload via URL · Cloudflare Images
  6. Accept user-uploaded images · Cloudflare Images
  7. Create predefined variants · Cloudflare Images
  8. Optimize with Workers · Cloudflare Images
  9. Pricing · Cloudflare Images docs
  10. View delivery analytics for hosted images · Cloudflare Changelog