跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

故障排除

最后更新 查看 MarkdownAgent 设置

未启用调整大小的请求

响应是否包含 Cf-Resized 标头?如果没有,则未尝试调整大小。可能的原因:

  • 未在 Cloudflare 仪表板中启用该功能。
  • 同一请求上运行了另一个 Worker。一旦一个 Worker 调用另一个 Worker,调整大小就会被"遗忘"。请勿使用作用域为整个域名 /* 的 Workers。
  • Cloudflare 仪表板中 Editor 的预览不会模拟图像调整大小。您必须部署 Worker 并从另一个浏览器标签页进行测试。

调整大小返回的错误

调整大小失败时,响应体包含解释原因的错误消息,以及包含 err=code 的 Cf-Resized 标头:

  • 9401 — {cf:image{…}} 选项中的必需参数缺失或无效。请重试。请参阅获取选项了解支持的参数。
  • 9402 — 图像太大或连接中断。请参阅支持的格式和限制了解更多信息。
  • 9403 — 发生请求循环,因为图像已被调整大小或 Worker 获取了自身的 URL。请验证 Worker 路径和服务器上的图像路径不重叠。
  • 9406 和 9419 — 图像 URL 是非 HTTPS URL,或 URL 包含空格或未转义的 Unicode。请检查 URL 并重试。
  • 9407 — 源站服务器域名发生查找错误。请检查 DNS 设置并重试。
  • 9404 — 源站服务器上不存在该图像,或用于调整图像大小的 URL 错误。请验证图像存在并检查 URL。
  • 9408 — 源服务器返回了 HTTP 4xx 状态码,并且可能拒绝访问该图像。确认图像设置后重试。
  • 9509 — 源服务器返回了 HTTP 5xx 状态码。这很可能是源服务器端软件的问题,而不是图像调整大小的问题。
  • 9412 — 源站服务器返回非图像内容,例如 HTML 页面。这通常发生在指定无效 URL 或服务器端软件打印错误或呈现登录页面时。
  • 9413 — 图像超过 100 兆像素的最大图像面积。请使用较小的图像并重试。
  • 9420 — 源站服务器重定向到无效 URL。请确认源站设置并重试。
  • 9421 — 源站服务器重定向次数过多。请确认源站设置并重试。
  • 9422 - 转换请求被拒绝,因为已达到用量限制。如需请求超过 5,000 次唯一转换,请升级到 Images Paid 计划。
  • 9432 — 使用旧版计费时 Images Binding 不可用。您的账户使用的是旧版 Image Resizing 订阅。要将 Images 绑定到 Worker,您需要在仪表板中将计划更新为 Images 订阅。
  • 9504、9505 和 9510 — 无法联系源站服务器,因为源站服务器可能已关闭或过载。请稍后重试。
  • 9519 - 由于意外原因(例如 DNS 解析失败),无法访问源站服务器。请确保可以通过公共 DNS 访问源站。
  • 9523 — /cdn-cgi/image/ 调整大小服务无法执行调整大小。这可能发生在图像格式无效时。请使用格式正确的图像并重试。
  • 9524 — /cdn-cgi/image/ 调整大小服务无法执行调整大小。这可能发生在图像 URL 被 Worker 拦截时。作为替代方案,您可以在 Worker 内调整大小。这也可能发生在使用 Cloudflare Pages 项目的 pages.dev URL 时。在这种情况下,您可以使用自定义域名代替。
  • 9520 — 不支持该图像格式。请参阅支持的格式和限制了解支持的输入和输出格式。
  • 9522 — 图像超过处理限制。这在清除整个 zone 后或请求尺寸非常大的文件时可能短暂发生。如果问题持续存在,请联系支持。
  • 9529 - 图像处理超时。这可能发生在请求尺寸非常大的文件或服务器过载时。
  • 9424、9516、9517、9518 — 内部错误。如果遇到这些错误,请联系支持。

调整大小时的警告

某些情况不会导致转换失败,但会妨碍 Cloudflare 充分优化图像。图像仍会以 200 状态码返回,Warning 响应标头会说明原因。响应中可能包含多个 Warning 标头。这些警告仅供参考,不会改变状态码。

cache-control is too restrictive

优化图像会消耗 CPU 时间,只有在结果可从缓存重复使用时才值得这样做。转换远程图像前,Cloudflare 会检查源图像响应中的缓存指令。如果优化后的图像不太可能在缓存中保留至少一小时,Cloudflare 会返回:

Warning: cf-images 299 "cache-control is too restrictive"

出现以下任一情况时,源图像会被视为不适合缓存:

  • 缓存指令包含 private 或 no-store。
  • 缓存指令包含 no-cache 或 must-revalidate,且响应中没有 ETag 或 Last-Modified 标头。
  • max-age 小于 3600 秒。如果存在 s-maxage,则会使用它而不是 max-age。

随后,Cloudflare 会以较低的优化力度处理图像。

若要恢复完整优化力度,请将源图像设为可缓存至少一小时:

  • 让源站返回 Cache-Control: public, max-age=3600 或更长的缓存时间。图像通常适合设置更长的有效期,例如 max-age=604800。
  • 如果无法更改源站,可以使用 Cache Response Rule,在源站响应到达 Cloudflare 缓存前为其设置 max-age 指令。

更改标头后,请清除源图像 URL 的缓存,使新指令生效。请参阅缓存和清除缓存。


限制

以下限制适用于存储在 Images 之外的图像:

  • 最大图像大小为 100 兆像素(例如,10,000×10,000 像素)。最大文件大小为 100 兆字节(MB)。GIF/WebP 动画限制为总共 50 兆像素(所有帧大小之和)。
  • 优化远程图像(转换)时,Bring Your Own IP (BYOIP) 与 Images 不兼容。
  • 当 Polish 无法优化图像时,响应标头返回 Warning: cf-images 299 "original is smaller"。

对源站的图像请求将被匿名化(无 Cookie、无身份验证、无自定义标头)。这是因为我们必须为调整大小的图像拥有一个公共缓存,共享为个别访问者个性化的图像是不安全的。

但是,在客户同意在公共缓存中存储此类图像的情况下,Cloudflare 支持通过 Workers 在已认证的源站上调整图像大小。


缓存和清除

更改图像尺寸或其他调整大小选项始终立即生效——无需清除。

图像请求由两部分组成:运行 Worker 代码和图像处理。Worker 代码始终执行且不被缓存。如果源站服务器的 Cache-Control 标头允许,图像处理结果缓存一小时或更长时间。源图像使用常规缓存规则缓存。调整大小在内部遵循重定向,因此重定向也会被缓存。

由于 Workers 本身的响应不在边缘缓存,清除 Worker URL 没有任何效果。调整大小的图像变体一起缓存在其源 URL 下。清除时,使用(全尺寸)源图像的 URL,而不是请求调整大小的 Worker 的 URL。

如果源站服务器发送 Etag HTTP 标头,调整大小后的图片也会带有格式为 cf-<gibberish>:<etag of the original image> 的 Etag HTTP 标头。你可以将第二部分与源图片 URL 的 Etag 标头进行比较,以检查调整大小后的图片是否为最新版本。

使用 URL 重写规则时清除缓存

如果使用 URL 重写规则将图像请求通过 /cdn-cgi/image/ 发送,清除缓存请求也会经过重写规则评估。这可能导致单文件缓存清除返回成功响应,却没有清除缓存的图像。

要解决此问题,请在规则表达式中添加以下内容,将缓存清除请求排除在重写规则之外:

and (not (http.request.method eq "PURGE"))

如果无法修改重写规则,可以改用按前缀清除缓存或按缓存标签清除缓存。

关于清除 Transform Rule 修改过的 URL,请参阅按单个文件清除缓存中的相关说明。

这篇文档对您有帮助吗?