[适用于 JavaScript 的 AWS SDK V3 API 参考指南](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/)详细描述了 适用于 JavaScript 的 AWS SDK 版本 3 (V3) 的所有 API 操作。

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

# 跨源资源共享 (CORS)
<a name="cors"></a>

跨源资源共享（即 CORS）是一项现代 Web 浏览器的安全功能。它使得 Web 浏览器可以协商哪些域能够发出对外部网站或服务的请求。

在使用 适用于 JavaScript 的 AWS SDK 开发浏览器应用程序时，CORS 是一个重要的考虑因素，因为对资源的大部分请求发送到外部域，例如 Web 服务的端点。如果您的 JavaScript 环境实施 CORS 安全性，则必须对该服务配置 CORS。

CORS 根据以下条件，确定是否允许跨源请求中的共享：
+ 发出请求的特定域 
+ 发出的 HTTP 请求的类型（GET、PUT、POST、DELETE 等等）

## CORS 工作原理
<a name="how-cors-works"></a>

在最简单的情况下，浏览器脚本从其他域中的服务器发出对某个资源的 GET 请求。根据该服务器的 CORS 配置，如果请求来自已授权提交 GET 请求的域，则跨来源服务器通过返回请求的资源做出响应。

如果请求域或者 HTTP 请求的类型未获得授权，则将拒绝请求。但是，CORS 实现了在实际提交请求之前进行预检。在这种情况下将提交预检请求，在其中发送 `OPTIONS` 访问请求操作。如果跨来源服务器的 CORS 配置授予对请求域的访问权限，则服务器发送回预检响应，其中列出请求域可以对所请求资源发出的所有 HTTP 请求类型。

![\[CORS 请求的流程流\]](http://docs.aws.amazon.com/zh_cn/sdk-for-javascript/v3/developer-guide/images/cors-overview.png)


## 是否需要 CORS 配置？
<a name="the-need-for-cors-configuration"></a>

Amazon S3 存储桶需要 CORS 配置，然后才能在存储桶上执行操作。在某些 JavaScript 环境中，CORS 可能未实施，因此不需要配置 CORS。例如，如果您在 Amazon S3 存储桶中托管应用程序并访问 `*.s3.amazonaws.com` 或某个其它特定端点的资源，您的请求不会访问外部域。因此，此配置不需要 CORS。在这种情况下，Amazon S3 之外的服务仍使用 CORS。

## 配置 Amazon S3 存储桶的 CORS
<a name="configuring-cors-s3-bucket"></a>

您可以在 Amazon S3 控制台中配置 Amazon S3 存储桶，以使用 CORS。

如果要在 AWS Web Services Management 控制台中配置 CORS，则必须使用 JSON 来创建 CORS 配置。新的 AWS Web Services Management 控制台仅支持 JSON CORS 配置。

**重要**  
在新的 AWS Web Services Management 控制台中，CORS 配置必须是 JSON。

1. 在 AWS Web Services Management 控制台中，打开 Amazon S3 控制台，找到要配置的存储桶，然后选中其复选框。

1. 在打开的窗格中，选择**权限**。

1. 在**权限**选项卡中，选择 **CORS 配置**。

1. 在 **CORS 配置编辑器** 中输入您的 CORS 配置，然后选择**保存**。

CORS 配置是一个 XML 文件，在 `<CORSRule>` 中包含了一系列规则。一个配置最多可以有 100 个规则。规则由以下标签之一定义：
+ `<AllowedOrigin>` - 指定您允许发出跨域请求的域源。
+ `<AllowedMethod>` - 指定您允许在跨域请求中使用的请求类型（GET、PUT、POST、DELETE、HEAD）。
+ `<AllowedHeader>` - 指定预检请求中允许的标头。

有关示例配置，请参阅《Amazon Simple Storage Service 用户指南》**中的[如何在我的存储桶上配置 CORS？](https://docs.aws.amazon.com/AmazonS3/latest/userguide/cors.html#how-do-i-enable-cors)。

## CORS 配置示例
<a name="cors-configuration-example"></a>

以下 CORS 配置示例允许用户从域 `example.org` 中查看、添加、移除或更新存储桶内的对象。不过，我们建议您将 `<AllowedOrigin>` 的范围限定到您的网站域名。您可以指定 `"*"` 以允许任意源。

**重要**  
在新的 S3 控制台中，CORS 配置必须是 JSON。

------
#### [ XML ]

```
<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <CORSRule>
    <AllowedOrigin>https://example.org</AllowedOrigin>
    <AllowedMethod>HEAD</AllowedMethod>
    <AllowedMethod>GET</AllowedMethod>
    <AllowedMethod>PUT</AllowedMethod>
    <AllowedMethod>POST</AllowedMethod>
    <AllowedMethod>DELETE</AllowedMethod>
    <AllowedHeader>*</AllowedHeader>
    <ExposeHeader>ETag</ExposeHeader>
    <ExposeHeader>x-amz-meta-custom-header</ExposeHeader>
  </CORSRule>
</CORSConfiguration>
```

------
#### [ JSON ]

```
[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "HEAD",
            "GET",
            "PUT",
            "POST",
            "DELETE"
        ],
        "AllowedOrigins": [
            "https://www.example.org"
        ],
        "ExposeHeaders": [
             "ETag",
             "x-amz-meta-custom-header"]
    }
]
```

------

此配置不授权用户在存储桶上执行操作。它使浏览器的安全模型允许对 Amazon S3 的请求。必须通过存储桶权限或 IAM 角色权限来配置权限。

您可以使用 `ExposeHeader`，让 SDK 读取从 Amazon S3 返回的响应标头。例如，如果要从 `PUT` 或分段上传读取 `ETag` 标头，则需要在配置中包括 `ExposeHeader` 标签，如上例中所示。SDK 只能访问通过 CORS 配置公开的标头。如果您在对象上设置元数据，则将值作为标头返回并带有 `x-amz-meta-` 前缀，例如 `x-amz-meta-my-custom-header`，并且也必须通过相同的方式公开。