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

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

# 浏览器脚本注意事项
<a name="browser-js-considerations"></a>

以下主题描述了 适用于 JavaScript 的 AWS SDK 在浏览器中使用脚本时的特殊注意事项。

**Topics**
+ [为浏览器构建 SDK](building-sdk-for-browsers.md)
+ [跨源资源共享 (CORS)](cors.md)
+ [使用 Webpack 捆绑应用程序](webpack.md)

# 为浏览器构建 SDK
<a name="building-sdk-for-browsers"></a>

与 JavaScript 版本 2 (V2) 的 SDK 不同，V3 不是作为包含默认服务集支持的 JavaScript 文件提供的。取而代之的是，V3 允许您仅在浏览器中捆绑和包含所需 JavaScript 文件的 SDK，从而减少开销。我们建议使用 Webpack 将所需的 JavaScript 文件 SDK 以及您需要的任何其他第三方软件包捆绑到一个`Javascript`文件中，然后使用`<script>`标签将其加载到浏览器脚本中。有关 Webpack 的更多信息，请参阅[使用 Webpack 捆绑应用程序](webpack.md)。

如果您在浏览器中强制执行 CORS 的环境之外使用 SDK，并且想要访问 SDK 为其提供的所有服务 JavaScript，则可以通过克隆存储库并运行与构建 SDK 的默认托管版本相同的构建工具在本地构建 SDK 的自定义副本。下面几部分介绍使用额外服务和 API 版本构建 SDK 的步骤。

## 使用 SDK 生成器构建 SDK JavaScript
<a name="using-the-sdk-builder"></a>

**注意**  
Amazon Web Services 版本 3 (V3) 不再支持浏览器生成器。为了最大限度地减少浏览器应用程序的带宽使用量，我们建议您导入命名模块，然后捆绑它们以减小大小。有关捆绑的更多信息，请参阅[使用 Webpack 捆绑应用程序](webpack.md)。

# 跨源资源共享 (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`，并且也必须通过相同的方式公开。

# 使用 Webpack 捆绑应用程序
<a name="webpack"></a>

浏览器脚本或 Node.js 中使用代码模块的 Web 应用程序会创建依赖关系。这些代码模块可能会具有自身的依赖关系，导致您的应用程序需要一组互连的模块才能正常工作。要管理依赖关系，您可以使用 `webpack` 等模块捆绑程序。

`webpack` 模块捆绑程序解析您的应用程序代码，搜索 `import` 或 `require` 语句，创建包含您应用程序所需的全部资产的捆绑。这样可以轻松地通过网页提供资产服务。SDK for JavaScript 可以作为包括在输出包中的依赖项之一包括在 `webpack` 中。

有关 `webpack` 的更多信息，请参阅 GitHub 上的 [webpack 模块捆绑程序](https://webpack.github.io/)。

## 安装 Webpack
<a name="webpack-installing"></a>

要安装 `webpack` 模块捆绑程序，您必须已经安装了 npm（Node.js 程序包管理器）。键入以下命令以安装 `webpack` CLI 和 JavaScript 模块。

```
npm install --save-dev webpack
```

要使用 `path` 模块来处理文件和目录路径（该模块是通过 webpack 自动安装的），您可能需要安装 Node.js `path-browserify` 软件包。

```
npm install --save-dev path-browserify
```

## 配置 Webpack
<a name="webpack-configuring"></a>

默认情况下，webpack 在项目的根目录中搜索名为 `webpack.config.js` 的 JavaScript 文件。此文件指定您的配置选项。以下是 WebPack 版本 5.0.0 及更高版本的 `webpack.config.js` 配置文件示例。

**注意**  
Webpack 配置要求因您安装的 Webpack 版本而异。有关更多信息，请参阅 [Webpack 文档](https://webpack.js.org/configuration/)。

```
// Import path for resolving file paths
var path = require("path");
module.exports = {
  // Specify the entry point for our app.
  entry: [path.join(__dirname, "browser.js")],
  // Specify the output file containing our bundled code.
  output: {
    path: __dirname,
    filename: 'bundle.js'
  },
   // Enable WebPack to use the 'path' package.
   resolve:{
  fallback: { path: require.resolve("path-browserify")}
  }
  /**
  * In Webpack version v2.0.0 and earlier, you must tell 
  * webpack how to use "json-loader" to load 'json' files.
  * To do this Enter 'npm --save-dev install json-loader' at the 
  * command line to install the "json-loader' package, and include the 
  * following entry in your webpack.config.js.
  * module: {
    rules: [{test: /\.json$/, use: use: "json-loader"}]
  }
  **/
};
```

在本示例中，指定 `browser.js` 为*入口点*。*入口点* 是 `webpack` 开始搜索导入的模块所用的文件。输出的文件名指定为 `bundle.js`。此输出文件包含应用程序运行所需的全部 JavaScript。如果入口点中指定的代码导入或需要其它模块（例如 SDK for JavaScript），则将捆绑该代码而无需在配置中指定它。

## 运行 Webpack
<a name="webpack-running"></a>

要生成应用程序以使用 `webpack`，请将以下内容添加到您 `package.json` 文件的 `scripts` 对象。

```
"build": "webpack"
```

以下是演示如何添加 `webpack` 的示例 `package.json` 文件。

```
{
  "name": "aws-webpack",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "build": "webpack"
  },
  "author": "",
  "license": "ISC",
  "dependencies": {
    "@aws-sdk/client-iam": "^3.32.0",
    "@aws-sdk/client-s3": "^3.32.0"
  },
  "devDependencies": {
    "webpack": "^5.0.0"
  }
}
```

要生成应用程序，请输入以下命令。

```
npm run build
```

随后，`webpack` 模块捆绑程序生成您在项目的根目录中指定的 JavaScript 文件。

## 使用 Webpack 捆绑
<a name="webpack-using-bundle"></a>

要在浏览器脚本中使用捆绑，您可以使用 `<script>` 标签整合捆绑，如下例中所示。

```
<!DOCTYPE html>
<html>
    <head>
        <title>Amazon SDK with webpack</title>
    </head> 
    <body>
        <div id="list"></div>
        <script src="bundle.js"></script>
    </body>
</html>
```

## 适用于 Node.js 的捆绑
<a name="webpack-nodejs-bundles"></a>

您可以通过在配置中将 `node` 指定为目标，使用 `webpack` 生成在 Node.js 中运行的捆绑。

```
target: "node"
```

在磁盘空间有限的环境中运行 Node.js 应用程序时，这非常有用。此处是将 Node.js 指定为输出目标的示例 `webpack.config.js` 配置。

```
// Import path for resolving file paths
var path = require("path");
module.exports = {
  // Specify the entry point for our app.
  entry: [path.join(__dirname, "browser.js")],
  // Specify the output file containing our bundled code.
  output: {
    path: __dirname,
    filename: 'bundle.js'
  },
  // Let webpack know to generate a Node.js bundle.
  target: "node",
   // Enable WebPack to use the 'path' package.
   resolve:{
  fallback: { path: require.resolve("path-browserify")}
   /**
   * In Webpack version v2.0.0 and earlier, you must tell 
   * webpack how to use "json-loader" to load 'json' files.
   * To do this Enter 'npm --save-dev install json-loader' at the 
   * command line to install the "json-loader' package, and include the 
   * following entry in your webpack.config.js.
   module: {
    rules: [{test: /\.json$/, use: use: "json-loader"}]
  }
  **/
};
```