Cloudflare Images是什么?怎么用:上传、缩放、裁剪与费用排查指南
简答: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步完成基础配置
- 准备账户和域名。登录 Cloudflare Dashboard,选择目标账户和已接入的站点。若只是处理远程图片,先确认源图所在域名可被服务端访问。
- 选择存储方式。需要托管图片时进入 Images 相关功能创建或使用托管图片存储;只做远程转换时,不必先把原图迁移到 Images。
- 开启 Transformations。在目标站点的图片优化功能中启用 Transformations,并按实际界面配置允许的源站。官方文档说明,默认情况下通常只接受与转换服务同一站点的源图片,跨源站使用前要检查允许列表。
- 先做一个固定尺寸测试。用一张公开可访问的图片测试宽度、裁剪方式和输出格式,确认源图状态码、响应类型和访问权限都正常。
- 再接入业务代码。固定尺寸可用后,再接入响应式宽度、预定义变体、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.jpgwidth=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更新说明。
图片打不开、变体无效或缓存未更新怎么排查
- 先查源图。用浏览器或命令行确认源图返回成功状态、正确的
Content-Type,并且不是登录后才能访问。远程转换无法获取需要认证的源图时,先解决源站权限。 - 再查来源限制。确认转换请求中的源图片域名已经加入允许列表。跨域名、重定向链或临时URL都可能导致源图无法被正常获取。
- 核对参数。先删除所有参数,只请求原图;再逐个加入
width、height、fit和format。变体名称必须与控制台或API创建的名称完全一致。 - 检查签名。私有图片需要有效签名;签名过期、路径变化、时间戳不一致都会造成访问失败。不要把签名密钥写入前端代码。
- 最后查缓存。原图已经替换但输出仍旧不变时,确认请求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或执行合适的失效操作。
相关阅读
参考资料
- Introduction · Cloudflare Images docs
- Overview · Cloudflare Images Transformations
- Features · Cloudflare Images
- Methods · Cloudflare Images upload images
- Upload via URL · Cloudflare Images
- Accept user-uploaded images · Cloudflare Images
- Create predefined variants · Cloudflare Images
- Optimize with Workers · Cloudflare Images
- Pricing · Cloudflare Images docs
- View delivery analytics for hosted images · Cloudflare Changelog