本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 框架作者的图像优化集成
<a name="integrate-image-optimization-framework"></a>

框架作者可以使用 Amplify Hosting 部署规范来集成 Amplify 的图像优化功能。要启用图像优化，您的部署清单必须包含针对图像优化服务的路由规则。以下示例演示了如何配置路由规则。

```
// .amplify-hosting/deploy-manifest.json
 
{
  "routes": [
    {
      "path": "/images/*",
      "target": {
        "kind": "ImageOptimization",
        "cacheControl": "public, max-age=31536000, immutable"
      }
    }
  ]
}
```

有关使用部署规范配置图像优化设置的更多信息，请参阅 [使用 Amplify Hosting 部署规范配置构建输出](ssr-deployment-specification.md)。

## 了解图像优化 API
<a name="understand-image-optimization-api"></a>

图像优化可以在运行时通过 Amplify 应用程序的域 URL 在路由规则定义的路径上调用。

```
GET https://{appDomainName}/{path}?{queryParams}
```

图像优化对图像施加了以下规则。
+ Amplify 无法优化 GIF、APNG 和 SVG 格式，也无法将其转换为其他格式。
+ 除非启用 `dangerouslyAllowSVG` 设置，否则不提供 SVG 图像。
+ 源图像的宽度或高度不能超过 11 MB 或 9000 像素。
+ 经过优化的图像的大小限制为 4 MB。
+ HTTPS 是唯一支持通过远程获取图像的协议 URLs。

### HTTP 标头
<a name="http-headers"></a>

**Accept** 请求 HTTP 标头用于指定客户端（通常是 Web 浏览器）允许的图像格式，以 MIME 类型表示。图像优化服务将尝试将图像转换为指定格式。为此标头指定的值将比格式查询参数具有更高的优先级。例如，**Accept** 标头的有效值为 `image/png, image/webp, */* `。Amplify 部署清单中指定的格式设置会将格式限制为列表中的格式。即使 **Accept** 标头要求使用特定的格式，如果该格式不在允许列表中，它也会被忽略。

### URI 请求参数
<a name="uri-request-parameters"></a>

下表介绍了的图像优化的 URI 请求参数。


| 查询参数 | Type | 必需 | 说明 | 示例 | 
| --- | --- | --- | --- | --- | 
| url | 字符串 | 是 | 源图像的相对路径或绝对 URL。对于远程 URL，HTTPS 是唯一受支持的协议。值必须为 URL 编码。 | `?url=https%3A%2F%2Fwww.example.com%2Fbuffalo.png` | 
| width | 数字 | 是 | 以像素为单位的优化图像宽度。 | `?width=800` | 
| height | 数字 | 否 | 以像素为单位的优化图像高度。如果未指定，则将自动缩放图像以匹配宽度。 | `?height=600` | 
| fit | 枚举值：`cover`、`contain`、`fill`、`inside`、`outside` | 否 | 如何调整图像大小以适应指定的宽度和高度。 | `?width=800&height=600&fit=cover` | 
| position | 枚举值：`center`、`top`、`right`、`bottom`、`left` | 否 | fit 为 `cover` 或 `contain` 时要使用的位置。 | `?fit=contain&position=centre` | 
| trim | 数字 | 否 | 修剪所有边缘的像素，这些像素包含与左上角像素的指定背景颜色相似的值。 | `?trim=50` | 
| 扩展 | 对象 | 否 | 使用从最近的边缘像素派生的颜色将像素添加到图像的边缘。格式为 `{top}_{right}_{bottom}_{left}`，其中每个值都是要添加的像素数。 | `?extend=10_0_5_0` | 
| extract | 对象 | 否 | 将图像裁剪到由顶部、左侧、宽度和高度分隔的指定矩形。格式为 {left}\_{top}\_{width}\_{right}，其中每个值都是要裁剪的像素数。 | `?extract=10_0_5_0` | 
| format | 字符串 | 否 | 优化图像所需的输出格式。 | `?format=webp` | 
| quality | 数字 | 否 | 图像的质量，从 1 到 100。仅在转换图像格式时使用。 | `?quality=50` | 
| rotate | 数字 | 否 | 按指定角度（以度数为单位）旋转图像。 | `?rotate=45` | 
| flip | 布尔值 | 否 | 在 x 轴上垂直（上下方向）镜像图像。此操作总是发生在旋转之前（如果有）。 | `?flip` | 
| flop | 布尔值 | 否 | 在 y 轴上水平（左右方向）镜像图像。此操作总是发生在旋转之前（如果有）。 | `?flop` | 
| sharpen | 数字 | 否 | 锐化可增强图像中边缘的清晰度。有效值在 0.000001 到 10 之间。 | `?sharpen=1` | 
| median | 数字 | 否 | 应用中值滤波。这样可以去除噪点或平滑图像的边缘。 | `?sharpen=3` | 
| blur | 数字 | 否 | 应用指定 sigma 的高斯模糊。有效值介于 0.3 到 1,000 之间。 | `?blur=20` | 
| gamma | 数字 | 否 | 应用伽玛校正以改善调整大小的图像的感知亮度。值必须在 1.0 到 3.0 之间。 | `?gamma=1` | 
| negate | 布尔值 | 否 | 反转图像的颜色。 | `?negate` | 
| normalize | 布尔值 | 否 | 通过拉伸其亮度以覆盖整个动态范围来增强图像对比度。 | `?normalize` | 
| threshold | 数字 | 否 | 如果图像中的任何像素的强度小于指定的阈值，则将其替换为黑色像素。或者，如果它大于阈值，则使用白色像素。有效值在 0 到 255 之间。 | `?threshold=155` | 
| tint | 字符串 | 否 | 使用提供的 RGB 对图像进行着色，同时保持图像的亮度。 | `?tint=#7743CE` | 
| grayscale | 布尔值 | 否 | 将图像转换为灰度（黑色和白色）。 | `?grayscale` | 

### 响应状态代码
<a name="response-status-codes"></a>

下表介绍了图像优化的响应状态代码。

**Success – HTTP 状态代码 200**  
请求已成功完成。

**BadRequest -HTTP 状态码 400**  
+ 输入查询参数的指定不正确。
+ 远程 URL 未在 `remotePatterns` 设置中列为允许。
+ 远程 URL 无法解析为图像。
+ `sizes` 设置中未将请求的宽度或高度列为允许值。
+ 请求的图像是 SVG，但 `dangerouslyAllowSvg` 设置已禁用该格式。

**Not Found – HTTP 状态代码 404**  
找不到源图像。

**Content too large – HTTP 状态代码 413**  
源图像或优化的图像超过了允许的最大字节大小。

### 了解经优化的图像缓存
<a name="image-optimization-caching"></a>

Amplify Hosting 会将经过优化的图像缓存在我们的 CDN 上，以便后续对具有相同查询参数的同一张图像的请求可以从缓存中获取。缓存存续时间（TTL）由 `Cache-Control` 标头控制。下表介绍了用于指定 `Cache-Control` 标头的选项。
+ 在以图像优化为目标的路由规则中使用 `Cache-Control` 键。
+ 使用 Amplify 应用程序中定义的自定义标头。
+ 对于远程图像，将使用远程图像返回的 `Cache-Control` 标头。

图像优化设置中指定的 `minimumCacheTTL` 定义了 Cache-Control max-age 指令的下限。例如，如果远程图像 URL 以 `Cache-Control s-max-age=10` 响应，但值 `minimumCacheTTL` 为 60，则使用 60。