功能

Cloudflare 使开发者能够通过实时动态生成不同版本来大规模优化图像。

本指南描述了可用于调整大小、裁剪、处理和应用视觉效果的所有参数。

通过以下方式使用 Cloudflare 的图像优化功能：

• URL 接口 — 直接在图像 URL 中应用参数，指定向浏览器提供图像时应如何优化。
• Workers — 将 Images API 直接绑定到 Worker，或在 fetch 子请求上设置 cf.image 选项以构建程序化图像工作流。

Cloudflare 根据您优化的是远程还是托管图像使用不同的 URL 结构：

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

https://imagedelivery.net/<ACCOUNT_HASH>/<IMAGE-ID>/<VARIANT-OR-OPTIONS>

使用 Images 与 Workers 时，您可以：

• 应用自定义逻辑来设置优化操作的顺序。例如，默认情况下，Images 会在 rotate 之前应用 flip；相反，您可以使用 Images 绑定自定义优化工作流，在翻转图像之前旋转它。
• 使用自定义 URL 方案而非默认 URL 结构。
• 实现内容协商，根据设备和网络状况动态调整图像大小、格式和质量。

指定是否保留输入文件中的动画帧。

• true（默认）— 输出包含所有帧的动画图像。
• false — 将动画输入的第一帧转换为静态图像。

放大图像或处理任意用户上传内容时建议使用此设置，因为动画 GIF 文件可能很大并增加页面加载时间。使用 format=json 时，设置 anim=false 也很有用，可在不返回帧数的情况下更快获得响应。

Original	anim=false

anim=false

cf: {image: {anim: false}}

指定用于填充图像中空白或透明像素的不透明或透明颜色。默认值为 %23FFFFFF（白色）。

接受以下属性：

• HEX 颜色代码，格式为 %23RRGGBB。
• CSS 颜色名称，例如 white 或 red。
• rgb() 或 rgba() CSS 颜色函数，例如 rgba(250,40,145,0.5)。

背景色在具有透明像素的图像中可见，包括使用 fit=pad 调整大小的图像。

Original 1080 x 720	Output 1080 x 900

background=%23ff0000
background=red
background=rgb%28240%2C40%2C145%29

cf: {image: {background: "#RRGGBB"}}
cf: {image: {background: "rgba(240,40,145,0)"}}

对图像应用模糊半径。接受 0（无模糊）到 250（最大模糊）的整数。默认值为 0。

通过 URL 优化时，不应依赖此参数可靠地遮挡图像内容，因为 URL 可被修改以移除 blur 参数。如需限制对原始图像的访问，可通过 Workers 限制对原始图像的访问。

Original	blur=50

blur=50

cf: {image: {blur: 50}}

在图像周围添加边框。

接受以下属性：

• color — 设置边框颜色。接受任何有效 CSS 颜色值，例如 #FF0000、rgb(0,0,0) 或 red。
• width — 设置四边统一的边框宽度（像素）。
• top、right、bottom、left — 分别设置各边的边框宽度（像素）。

边框在图像调整大小后应用。边框宽度会随 dpr 参数自动缩放，以确保在高分辨率屏幕上清晰显示。

cf: {image: {border: {color: "rgb(0,0,0,0)", top: 5, right: 10, bottom: 5, left: 10}}}
cf: {image: {border: {color: "#FFFFFF", width: 10}}}

使用乘数调整图像的整体亮度。

• 1（默认）— 不改变原始亮度。
• < 1.0 — 使图像变暗，例如 0.5 为一半亮度。
• > 1.0 — 使图像变亮，例如 2 为两倍亮度。

Original	brightness=0.5	brightness=2

brightness=0.5

cf: {image: {brightness: 0.5}}

选择压缩速度最快的输出格式。接受 fast。默认无。

compression=fast 选项优先编码速度而非输出质量和文件大小，通常会覆盖 format 参数，选择 JPEG 而非 AVIF 或 WebP 等更高效的格式。这会在缓存未命中时略微降低延迟，但可能导致文件增大和图像质量下降。

除非在特殊情况下（例如调整不可缓存、动态生成的图像大小），否则不建议使用此选项。

compression=fast

cf: {image: {compression: "fast"}}

使用乘数调整图像最暗与最亮部分之间的整体差异。

• 1（默认）— 不改变原始对比度。
• < 1.0 — 降低对比度，使阴影变亮、高光变暗。
• > 1.0 — 提高对比度，使阴影趋近黑色、高光趋近白色。

Original	contrast=0.5	contrast=2

contrast=0.5

cf: {image: {contrast: 0.5}}

通过乘数缩放输出分辨率，以匹配用户特定屏幕密度（例如 Retina 或 4K）。默认值为 1，即按请求的精确宽度和高度提供图像。支持的最大值为 2。

现代设备的物理像素多于 CSS 像素。若在高 DPR 智能手机上于 300px 容器中提供 300px 图像，图像会显得模糊。使用 dpr=2 可让 Cloudflare 为同一 300px 容器发送 600px 图像，从而获得更清晰、更锐利的图像。

dpr 参数可与 srcset 配合使用以提供响应式图像。

width=300,height=200,dpr=1	width=300,height=200,dpr=2

dpr=1

cf: {image: {dpr: 1}}

指定图像如何适应目标区域。

在设置图像的 width 和 height 尺寸后执行 fit 操作。

fit=pad

cf: {image: {fit: "pad"}}

在保持原始宽高比的同时，将图像调整为适应指定尺寸，但从不放大图像。这是默认的 fit 行为。

当原始图像小于目标区域时，将以其原始尺寸返回。例如，请求以 2000x2000 提供 1080x720 图像时，将返回 1080x720 的图像。

当原始图像较大时，在匹配原始宽高比的同时缩小图像以适应目标区域。

在下面的示例中，1080x720 图像被调整为适应 500x500 的目标区域。由于 scale-down 保持原始宽高比 (3:2)，输出图像的最终尺寸为 500x333。

Original 1080 x 720 (3:2)	Requested 500 x 500 (1:1)	Output 500 x 333 (3:2)

在保持原始宽高比的同时，将图像调整为在目标 width 和 height 尺寸内尽可能大。

当原始图像大于目标区域时，缩小以适应目标区域（类似 scale-down）。

当原始图像较小时，改为放大（类似 scale-up）。可与 upscale 参数配合，控制放大图像的算法。要避免放大，请使用 scale-down。

填满整个目标区域，必要时缩小或放大图像。输出区域始终与请求的 width 和 height 尺寸完全匹配。

当原始宽高比与目标宽高比不同时，调整图像大小以覆盖整个目标区域，超出部分将被裁剪。使用 gravity 参数控制裁剪时保留图像的哪一部分。

可与 upscale 参数配合，控制放大图像的算法。

在下面的示例中，1080×720 图像首先调整为 750×500（匹配请求的高度）以适应目标区域，然后从左右边缘裁剪至最终的 500x500 尺寸。

Original 1080 x 720 (3:2)	Requested 500 x 500 (1:1)	Output 500 x 500 (1:1)

当原始图像小于目标区域时，改为放大。要避免放大，请使用 crop。

调整图像大小以填满目标区域，但不放大。

当原始图像小于目标区域时，保持其原始尺寸和宽高比（类似 scale-down）。

在下面的示例中，原始图像 (1080x720) 小于目标区域 (1296x1296)，因此保持其原始尺寸和宽高比。

Original 1080 x 720 (3:2)	Requested 1296 x 1296 (1:1)	Output 1080 x 720 (3:2)

当原始图像大于目标区域时，其行为类似 cover（填满目标区域并裁剪其余部分）。

裁剪图像以匹配目标宽高比，必要时缩小但从不放大。

当原始图像大于目标区域时，缩小到仍能填满目标尺寸的最小尺寸，然后裁剪以匹配目标宽高比（类似 cover）。

当原始图像小于目标区域时，保持其原始尺寸，但裁剪以匹配目标宽高比。与保留较小图像原始尺寸和维度的 crop 不同，aspect-crop 始终强制使用目标宽高比。

例如，请求以 1920x1120 提供 612x613 图像时不会放大。相反，它保持原始尺寸并裁剪为 612x357，匹配 1920:1120 的宽高比。使用 gravity 参数控制裁剪时保留图像的哪一部分。

将图像调整为在尺寸范围内尽可能大。如果适用，输出区域将扩展以精确匹配 width 和 height 尺寸。

可与 background 参数配合，填充任何空白或透明像素。但是，对于 Web 应用，你通常可以使用 contain 选项配合 CSS object-fit: contain 属性实现相同的视觉效果，从而避免将填充像素编码到图像本身中。

在下面的示例中，原始图像 (1080x720) 小于目标区域 (1080x1080)，因此为剩余像素创建空白。

Original 1080 x 720 (3:2)	Requested 1080 x 1080 (1:1)	Output 1080 x 1080 (1:1)

将图像调整为精确匹配请求的宽度和高度，不裁剪边缘或约束部分。

当原始宽高比与目标宽高比不同时，图像将变形以适应目标区域。

Original 1080 x 720	Output 1080 x 540

Original 1080 x 1080	Output 1080 x 540

在保持原始宽高比的同时，将图像调整为适应指定尺寸，但从不缩小图像。这是 scale-down 的逆操作。

当原始图像大于目标区域时，以其原始尺寸返回。

当原始图像小于目标区域时，放大以适应目标尺寸。使用 upscale 参数控制用于放大图像的算法 — 设置 upscale=generate 使用 AI 驱动的放大，或设置 upscale=interpolate（默认）使用双三次插值。

水平、垂直或同时翻转图像。

接受以下值：

• h — 水平翻转图像。
• v — 垂直翻转图像。
• hv — 同时水平和垂直翻转图像。

flip 可与 rotate 参数配合设置图像方向。翻转在旋转之前执行。例如，应用 flip=h,rotate=90 时，图像会先水平翻转，再旋转 90 度。

Original	flip=h	flip=v

flip=h

cf: {image: {flip: "h"}}

指定图像的输出格式。

接受以下值：

• auto — 自动提供请求浏览器支持的最高效格式。提供托管图像时，这是默认的 format 选项。
• avif — 如可能，将图像转码为 AVIF。AVIF 编码可能比编码为其他格式慢一个数量级。如果图像太大无法快速编码为 AVIF，Cloudflare 将回退到 WebP 或 JPEG。
• webp — 将图像转码为 Google WebP 格式。使用 quality=100 可返回 WebP 无损格式。
• jpeg — 以交错渐进式 JPEG 格式转码图像，数据在多次传递中按逐步提高的细节压缩。
• baseline-jpeg — 以基线顺序 JPEG 格式转码图像。当目标设备不支持渐进式 JPEG 或其他现代文件格式时应使用。
• json — 以 JSON 对象输出图像信息。包含调整大小前后的图像尺寸、源图像 MIME 类型和文件大小等数据。

format=auto
f=auto

cf: {image: {format: "avif"}}

要在自定义 Worker 中使用 format=auto，需要解析 Accept 头。有关如何设置图像转换 Worker 的完整概述，请参阅此示例 Worker。

const accept = request.headers.get("accept");
let image = {};

if (/image\/avif/.test(accept)) {
	image.format = "avif";
} else if (/image\/webp/.test(accept)) {
	image.format = "webp";
}

return fetch(url, { cf: { image } });

使用乘数调整图像曝光。Gamma 控制中间调亮度，不影响图像最暗或最亮部分。

• 0 和 1（默认）— 不改变原始 gamma。
• < 1.0 — 提高中间调亮度，使图像整体更亮。
• > 1.0 — 降低中间调亮度，使图像整体更暗。

Original	gamma=0.5	gamma=2

gamma=0.5

cf: {image: {gamma: 0.5}}

指定与 fit=cover 和 fit=crop 配合使用时如何裁剪图像。默认情况下，Cloudflare 会裁剪到原始图像的中心点。

接受 auto、face、边（left、right、top、bottom）和相对坐标（XxY）。

gravity=auto
g=auto
gravity=face
gravity=left
gravity=0.5x1

cf: {image: {gravity: "auto"}}
cf: {image: {gravity: "face"}}
cf: {image: {gravity: "left"}}
cf: {image: {gravity: {x:0.5, y:0.2}}}

通过显著性算法自动检测视觉上最有趣的像素来设置焦点。

当你事先不知道图像内容时（例如用户生成内容）这很有用。对于大型图像库（如电商产品图库），此功能无需为每张图像手动设置焦点。

Original	默认裁剪	gravity=auto

根据图像中的人脸自动设置焦点。

可与 zoom 参数配合，指定裁剪时向人脸靠近的程度。

Original	默认裁剪	gravity=face

摄影：Suad Kamardeen (@suadkamardeen) on Unsplash ↗

设置不应被裁剪的图像边。

在下面的示例中，1080x720 图像被裁剪为 1080x400 区域，从其底边开始：

Original	gravity=bottom

设置焦点 (X,Y)，使输出图像的相对坐标位于原始图像的相对坐标处。接受格式为 XxY 的坐标对，其中 X 和 Y 是 0.0 到 1.0 之间的小数值。

• 水平值 (X) — 0.0 为图像左边缘，1.0 为右边缘。
• 垂直值 (Y) — 0.0 为图像顶部边缘，1.0 为底部边缘。

下面的示例将 900x900 图像裁剪为 300x900，使用 0.33x0.5 重力点：

• 原始图像和目标区域的重力点都设置在距左边缘 1/3 宽度、距顶部边缘 1/2 高度处。
• 输出重力点的相对坐标位于原始图像的相对坐标处。即，目标区域的位置使其重力点与原始图像中的相同相对位置 (0.33, 0.5)。
• 图像的暗色部分显示请求输出区域之外的部分，将被裁剪。
• 最终裁剪结果捕获重力点 (0.33, 0.5) 周围的 300x900 内容。

Original	对齐	裁剪	Output

通过 Workers 优化时，使用对象 {x, y} 指定坐标。例如 {fit: "cover", gravity: {x:0.5, y:0.2}} 会裁剪各边，以尽可能保留原始图像高度 20% 处的点周围内容。

使用正整数值设置输出图像的高度（像素）。默认情况下，Cloudflare 使用输入图像的原始高度。

设置 height 时，具体行为取决于 fit 参数。

height=250
h=250

cf: {image: {height: 250}}

控制 JPEG 图像应保留多少不可见元数据（EXIF）。对于所有其他输出格式（例如 WebP 或 PNG），所有元数据始终会被丢弃。

即使丢弃元数据，颜色配置文件和 EXIF 旋转仍会应用于图像。

接受以下值：

• copyright（默认）— 丢弃除 EXIF 版权标签外的所有元数据。
• keep — 保留大部分 EXIF 元数据，包括 GPS 位置（如有）。
• none — 丢弃所有不可见 EXIF 元数据。

metadata=none

cf: {image: {metadata: "none"}}

当致命错误阻止图像转换时，将最终用户重定向到原始源图像的 URL。接受 redirect。默认值为 none。

此选项仅在图像位于同一 zone（接受子域名）时有效。如果原始图像来自不同 zone，此选项无效。

当图像需要用户身份验证且无法通过 Workers 匿名获取时，此选项可能有用。但如果源图像非常大，不建议使用此选项。

onerror=redirect

指定 JPEG、WebP 和 AVIF 格式图像的输出质量，可为固定值或感知质量级别。默认值为 85。

• 固定质量 — 接受 1（低质量、小文件）到 100（高质量、大文件）的正整数。
• 感知质量 — 接受 high、medium-high、medium-low 和 low。

当输出格式为 PNG 时，显式 quality 设置允许使用 PNG8（调色板）变体。

quality=50
quality=low
q=50

cf: {image: {quality: 50}}
cf: {image: {quality: "high"}}

将图像旋转指定度数。接受 90、180 或 270。默认值为 0（不旋转）。

旋转在调整大小之前执行；width 和 height 选项将指向旋转后的坐标轴。

Original	rotate=180

rotate=90

cf: {image: {rotate: 90}}

使用乘数调整图像的色彩饱和度。

• 0 — 完全去饱和（灰度）。
• < 1.0 — 降低色彩强度。例如 0.5 为一半饱和度。
• 1（默认）— 不改变原始饱和度。
• > 1.0 — 提高色彩强度。例如 2 为两倍饱和度。

Original	saturation=0	saturation=2

saturation=0.5

cf: {image: {saturation: 0.5}}

通过将背景替换为透明像素，自动分离图像主体。接受 foreground。默认无。

此功能通过 Workers AI 使用名为 BiRefNet 的开源模型。了解更多关于 Cloudflare 负责任 AI 的方法 ↗。

Original	segment=foreground

segment=foreground

cf: {image: {segment: "foreground"}}

应用锐化滤镜以增强图像边缘定义。接受 0（不锐化）到 10（最大锐化）的小数值。默认值为 0。缩小图像的推荐值为 1。

Original	sharpen=5

sharpen=2

cf: {image: {sharpen: 2}}

检测到慢速连接时覆盖 quality 值。接受与 quality 相同的固定或感知质量设置。默认值为 none。

要检测慢速连接，请在 HTTP 头中启用以下任一 client hints：

accept-ch: rtt, save-data, ect, downlink

当 client hint 存在且满足以下任一条件时，应用 slow-connection-quality：

• rtt ↗：大于 150ms。
• save-data ↗：值为 "on"。
• ect ↗：值为 slow-2g|2g|3g 之一。
• downlink ↗：小于 5Mbps。

slow-connection-quality=50
scq=50

移除图像边缘周围的像素。

此功能可用于按边框颜色裁剪图像，或从各边裁剪指定数量的像素。

Trim 会考虑 dpr 参数，并在调整大小和旋转之前执行。

根据边框颜色自动裁剪图像边缘。

trim=border 选项可使用以下参数进一步调整：

• trim.border.color — 选择要裁剪的边框颜色。接受 CSS4 现代语法的任何 CSS 颜色。如省略，则自动检测颜色。
• trim.border.tolerance — 设置检测到的像素在颜色上必须匹配的紧密程度。接受 0（无需匹配）到 255（必须完全匹配）的整数。
• trim.border.keep — 指定保留未裁剪的原始边框像素数。

指定从图像各边移除的像素数。接受四个值，以分号分隔，可一次性设置图像四边的裁剪。

所有 trim 值可接受整数（像素数）或 0 到 1 之间的小数，表示图像尺寸的分数。例如 0.25 从该边裁剪 25%。

也可使用以下参数对特定边应用 trim：

• trim.top — 从图像顶部移除像素。
• trim.left — 从图像左侧移除像素。
• trim.height — 从顶部边缘设置图像高度，然后裁剪下方所有内容。
• trim.width — 从左侧边缘设置图像宽度，然后裁剪右侧所有内容。

trim=border
trim.height=800
// This sets the height of the image to 800 pixels from the top of the image, then trims everything below that point

trim.left=800
// This removes 800 pixels from the left of the image

trim=0.1;0.2;0.1;0.2
// This trims 10% from the top and bottom, and 20% from the left and right

trim.top=0.25
// This trims 25% of the image height from the top

cf: {image: {trim: {top: 12, right: 78, bottom: 34, left: 56, width: 678, height: 678}}}
// Using decimals to trim 10% from each side:
cf: {image: {trim: {top: 0.1, right: 0.1, bottom: 0.1, left: 0.1}}}

控制图像需要放大时使用的算法。此参数适用于任何会放大的 fit 模式，例如 contain、cover 和 scale-up。当 fit=scale-down 或目标尺寸小于源图像时无效。

接受以下值：

• interpolate（默认）— 使用双三次插值，可能降低图像质量。未指定 upscale 时为默认行为。
• generate — 使用 AI 放大（ESRGAN ↗）在放大图像时产生更清晰、更细致的结果。

指定 upscale=generate 时，AI 模型会以最近支持的比例（2x 或 4x）运行一次，然后调整到精确的目标尺寸。超过 4x 的缩放因子会先通过 AI 放大到 4x，剩余部分使用双三次插值处理。

upscale=generate

cf: {image: {upscale: "generate"}}

使用正整数值设置输出图像的宽度（像素）。默认情况下，Cloudflare 使用输入图像的原始宽度。

设置 width 时，具体行为取决于 fit 参数。

接受以下值：

• 像素数（例如 250）。
• auto — 根据浏览器和设备可用信息，自动以最优宽度提供图像。接受 wbreakpoints（client hints）、wmobile（user-agent 检测）和 wdesktop（user-agent 检测）作为子参数。

width=250
w=250

cf: {image: {width: 250}}

指定 width=auto 时，Cloudflare 使用 client hints（浏览器发送）或 user-agent 检测作为后备来调整图像大小。

可使用以下子参数自定义 width=auto 行为：

使用 width=auto 优化远程图像时，每个唯一宽度计为单独的可计费 transformation。

要了解 width=auto 的工作原理，请参阅提供响应式图像指南。

wbreakpoints=320;768;960;1920 // 将最大断点更改为 1920 像素
wbreakpoints=320;768;960;1200;1920 // 在 1920 像素处添加另一个断点

cf: {image: {wbreakpoints: "320;768;960;1920"}}

指定与 gravity=face 选项配合使用时，裁剪图像时向检测到的人脸靠近的程度。接受 0.0（尽可能保留背景）到 1.0（尽可能贴近人脸裁剪）之间的有效范围。默认值为 0。

zoom=0.1

cf: {image: {zoom: 0.5}}

理想情况下，图像尺寸应与页面上显示的尺寸完全匹配。如果页面包含带有 <img width="200" …> 等标记的缩略图，则图像应调整为 width=200。

要提供响应式图像，您可以使用 HTML srcset 属性让提供者选择最优尺寸。如果您无法使用 <img srcset> 标记且必须硬编码特定最大尺寸，Cloudflare 建议以下尺寸：

• 桌面浏览器最大 1920 像素。
• 平板电脑最大 960 像素。
• 手机最大 640 像素。

例如，fit=scale-down,width=1920 设置 1920px 的最大尺寸，并确保不会不必要地放大图像。

您可以通过 Cache Rule 启用 CF-Device-Type 标头来检测设备类型。

使用 Images 优化时，将从源站服务器获取原始图像并缓存——遵循 HTTP 缓存、Cache-Control 标头等的常规规则。对多种不同图像尺寸的请求可能会重用缓存的原始图像，而不会导致源站服务器的额外传输。

如果对原始图像使用了自定义缓存键，原始图像可能不会被缓存，可能导致更多对源站的调用。

优化后的图像遵循与其调整大小的原始图像相同的缓存规则，但最小缓存时间为一小时。如果您需要更频繁地更新图像，请在 Cache-Control 标头中添加 must-revalidate。Images 服务支持缓存重新验证，因此我们建议使用 Etag 标头提供图像。有关更多信息，请参阅缓存文档。

Cloudflare 不支持单独清除优化后的图像。以 /cdn-cgi/ 开头的 URL 无法被清除。但是，清除原始图像的 URL 也会清除其所有优化版本。