Images 常见陷阱

# 常见问题与最佳实践 ## 适配模式 (Fit Modes) | 模式 | 适用场景 | 行为 | |------|----------|----------| | `cover` | 英雄图、缩略图 | 填充空间，裁剪多余部分 | | `contain` | 产品图、艺术品 | 保留完整图像，可能会添加填充 | | `scale-down` | 用户上传 | 绝不放大 | | `crop` | 精确裁剪 | 使用重力 (gravity) | | `pad` | 固定长宽比 | 添加背景 | ## 格式选择 typescript format: 'auto' // 推荐 - 协商最佳格式 **支持：** AVIF (Chrome 85+, Firefox 93+, Safari 16.4+), WebP (Chrome 23+, Firefox 65+, Safari 14+) ## 质量设置 | 用例 | 质量 | |----------|---------| | 缩略图 | 75-80 | | 标准 | 85 (默认) | | 高质量 | 90-95 | ## 常见错误 ### 5403: "图像转换失败" - 验证 `width`/`height` ≤ 12000 - 检查 `quality` 1-100, `dpr` 1-3 - 不要组合不兼容的选项 ### 9413: "超出速率限制" 实现缓存和指数退避： typescript for (let i = 0; i setTimeout(r, 2 ** i * 1000)); } } ### 5401: "图像太大" 上传前预处理图像（最大 100MB, 12000×12000px） ### 5400: "无效图像格式" 支持：JPEG, PNG, GIF, WebP, AVIF, SVG ### 401/403: "未授权" 验证 API 令牌具有 `Cloudflare Images → Edit` 权限 ## 限制 | 资源 | 限制 | |----------|-------| | 最大输入大小 | 100MB | | 最大尺寸 | 12000×12000px | | 质量范围 | 1-100 | | DPR 范围 | 1-3 | | API 速率限制 | ~1200 次请求/分钟 | ## AVIF 注意事项 - **编码较慢**：首次请求可能会有更高的延迟 - **浏览器检测**： typescript const format = /image/avif/.test(request.headers.get('Accept') || '') ? 'avif' : 'webp'; ## 反模式 typescript // ❌ 无缓存 - 每次请求都进行转换 return env.IMAGES.input(buffer).transform({...}).output().response(); // ❌ cover 模式下未同时设置两个维度 transform({ width: 800, fit: 'cover' }) // ✅ cover 模式下始终设置两个维度 transform({ width: 800, height: 600, fit: 'cover' }) // ❌ 向客户端暴露 API 令牌 // ✅ 使用直接创建者上传 (patterns.md) ## 调试 typescript // 检查响应头 console.log('Content-Type:', response.headers.get('Content-Type')); // 使用 curl 测试 // curl -I "https://imagedelivery.net/{hash}/{id}/width=800,format=avif" // 监控日志 // npx wrangler tail