# @aws-cdk/aws-s3-deployment 中文文档

规范地址：https://npmcn.com/package/%40aws-cdk/aws-s3-deployment/

版本：1\.204\.0
npm 元数据更新时间：2023-11-21T10:16:42.637Z
中文译文更新时间：2026-11-07T14:28:27.468Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aws-cdk/aws-s3-deployment
原文对照：https://npmcn.com/package/%40aws-cdk/aws-s3-deployment/?lang=original
项目主页：https://github.com/aws/aws-cdk
源码仓库：https://github.com/aws/aws-cdk

弃用说明：AWS CDK v1 has reached End-of-Support on 2023-06-01\. This package is no longer being updated, and users should migrate to AWS CDK v2\. For more information on how to migrate, see https://docs\.aws\.amazon\.com/cdk/v2/guide/migrating-v2\.html

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：393 kB，28 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 14\.15\.0
- 运行依赖：12 个
- peer 依赖：@aws-cdk/aws-cloudfront 1\.204\.0，@aws-cdk/aws-ec2 1\.204\.0，@aws-cdk/aws-efs 1\.204\.0，@aws-cdk/aws-iam 1\.204\.0，@aws-cdk/aws-lambda 1\.204\.0，@aws-cdk/aws-logs 1\.204\.0，@aws-cdk/aws-s3 1\.204\.0，@aws-cdk/aws-s3-assets 1\.204\.0，@aws-cdk/core 1\.204\.0，@aws-cdk/lambda-layer-awscli 1\.204\.0，constructs ^3\.3\.69
- 首次发布：2018-10-19T13:38:25.786Z
- 最新版本发布：2023-06-19T21:10:01.133Z
- 近 30 天下载量：18761（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：280（近 12 个月 0 个）

## 中文简介

用于向 S3 桶部署内容的构造

## 安装

```sh
npm install @aws-cdk/aws-s3-deployment
```

也可以使用：`pnpm add @aws-cdk/aws-s3-deployment`、`yarn add @aws-cdk/aws-s3-deployment`、`bun add @aws-cdk/aws-s3-deployment`

## README

# AWS S3 部署构造库

* * *

![End-of-Support](https://img.shields.io/badge/End--of--Support-critical.svg?style=for-the-badge)

> AWS CDK v1在2023-06-01上达到了支持结束. 此软件包不再更新,用户应该迁移到 AWS CDK v2.
> 
> 关于如何移徙的更多信息,请参见: [_移动到 AWS CDK v2_ 指南](https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html)。 。 。 .

* * *

这个库允许充入带有.zip文件内容的 S3 桶 从其他 S3 桶或从本地磁盘.

以下示例定义了可公开访问的 S3 桶, 并带有网页托管功能 启用并输入磁盘上的本地目录.

```ts
const websiteBucket = new s3.Bucket(this, 'WebsiteBucket', {
  websiteIndexDocument: 'index.html',
  publicReadAccess: true,
});

new s3deploy.BucketDeployment(this, 'DeployWebsite', {
  sources: [s3deploy.Source.asset('./website-dist')],
  destinationBucket: websiteBucket,
  destinationKeyPrefix: 'web/static', // optional prefix in destination bucket
});
```

这是在引擎盖下发生的事情:

1.  当部署此堆栈时( 要么通过 `cdk deploy` 或通过CI/CD) 本地目录中的内容 `website-dist` 目录将存档并上传 到一个中介资产桶。 如果不止一个来源,他们会 个人上传.
2.  这个 `BucketDeployment` 构造自定义 CloudFormation 资源 类型 `Custom::CDKBucketDeployment` 输入模板。 源桶/钥匙 用于指向资产桶.
3.  自定义资源下载 .zip 归档,取出并发行 `aws s3 sync --delete` 攻击目的地桶(在这种情况下) `websiteBucket`) (中文(简体) ). 如果有一个以上的来源,来源将是 在此步骤下下载并合并了部署前.

如果您在另一个构造中引用填充的桶,则取决于 文件已经存在, 请确定使用 `deployment.deployedBucket`这个 将确保在使用资源之前完成水桶部署 创建桶 :

```ts
declare const websiteBucket: s3.Bucket;

const deployment = new s3deploy.BucketDeployment(this, 'DeployWebsite', {
  sources: [s3deploy.Source.asset(path.join(__dirname, 'my-website'))],
  destinationBucket: websiteBucket,
});

new ConstructThatReadsFromTheBucket(this, 'Consumer', {
  // Use 'deployment.deployedBucket' instead of 'websiteBucket' here
  bucket: deployment.deployedBucket,
});
```

## 支助来源

用于桶部署的源类型有:

-   本地 .zip 文件 : `s3deploy.Source.asset('/path/to/local/file.zip')`
-   本地目录 : `s3deploy.Source.asset('/path/to/local/directory')`
-   又一个桶: `s3deploy.Source.bucket(bucket, zipObjectKey)`
-   字符串数据 : `s3deploy.Source.data('object-key.txt', 'hello, world!')` (支助) [部署时间值](https://npmcn.com/package/%40aws-cdk/aws-s3-deployment/#readme-data-with-deploy-time-values)(中文(简体) )
-   JSON数据 : `s3deploy.Source.jsonData('object-key.json', { json: 'object' })` (支助) [部署时间值](https://npmcn.com/package/%40aws-cdk/aws-s3-deployment/#readme-data-with-deploy-time-values)(中文(简体) )

要从一个文件创建源, 您可以通过 `AssetOptions` 排除 除单一文件外的所有文件 :

-   单一文件 : `s3deploy.Source.asset('/path/to/local/directory', { exclude: ['**', '!onlyThisFile.txt'] })`

**重要性** 这个 `aws-s3-deployment` 模块仅用于 来自可信来源的zip文件 。 由 CDK CLI 捆绑的目录( 通过使用 `Source.asset()` 在目录上)是安全的. 使用时 `Source.asset()` 或者说 `Source.bucket()` 引用已有的zip文件,确保您信任 文档中您正在引用 。 来自不信任来源的分页可能能够执行 此模块使用的 Lambda 函数中的任意代码,并使用其权限 在 S3 桶中读取或写入出乎意料的文件.

## 删除时保留

默认情况下, 目的地桶的内容会 **没有** 当 `BucketDeployment` 资源从堆栈中移除,或当目的地是 换了 您可以使用选项 `retainOnDelete: false` 要禁用这种行为, 在这种情况下,内容将被删除.

假设这一点有以下几个含义:

-   **逻辑标识更改**
    
    更改逻辑编号 `BucketDeployment` 构造,不改变目的地 (例如由于重构,或有意改变ID) **将导致删除对象**。 。 。 . 这是因为"云阵"将首先创建新的资源,不会影响, 之后删除旧资源,这将导致删除对象, 因为目的地没有改变 `retainOnDelete` 实值 `false`。 。 。 .
    
-   **目标变化**
    
    当目标桶或前缀被更改时,上一个目标的所有文件都会 **第一个** 为: 删除后上传到新的目的地位置。 这可能涉及可用性 您的用户.
    

### 一般性建议

#### 共享密钥

如果目标桶 **没有** 专为具体 `BucketDeployment` 构造(即由其他实体共享), 我们建议永远配置 `destinationKeyPrefix` 属性。 这将防止部署人员 不小心删除了它没有上传的数据.

#### 专注的小桶

如果目标桶 **实值** 专门,跳过前缀配置可能是合理的, 在这种情况下,我们建议删除 `retainOnDelete: false`,转而配置 [`autoDeleteObjects`](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-s3-readme.html#bucket-deletion) 财产在目的地桶。 这将避免上述逻辑识别问题.

## 发泡

默认情况下, 来源中不存在的目标桶中的文件将被删除 当 `BucketDeployment` 创建或更新资源。 您可以使用选项 `prune: false` 无法禁用 ,在这种情况下,文件将不会被删除.

```ts
declare const destinationBucket: s3.Bucket;
new s3deploy.BucketDeployment(this, 'DeployMeWithoutDeletingFilesOnDestination', {
  sources: [s3deploy.Source.asset(path.join(__dirname, 'my-website'))],
  destinationBucket,
  prune: false,
});
```

此选项也允许您 同一目的桶前缀的多桶布置, 每一个都有各自的特性。 例如,您可以设置不同的缓存控制头 基于文件扩展名 :

```ts
declare const destinationBucket: s3.Bucket;
new s3deploy.BucketDeployment(this, 'BucketDeployment', {
  sources: [s3deploy.Source.asset('./website', { exclude: ['index.html'] })],
  destinationBucket,
  cacheControl: [s3deploy.CacheControl.fromString('max-age=31536000,public,immutable')],
  prune: false,
});

new s3deploy.BucketDeployment(this, 'HTMLBucketDeployment', {
  sources: [s3deploy.Source.asset('./website', { exclude: ['*', '!index.html'] })],
  destinationBucket,
  cacheControl: [s3deploy.CacheControl.fromString('max-age=0,no-cache,no-store,must-revalidate')],
  prune: false,
});
```

## 排除和包含过滤器

在部署中评价过滤器有两点:资产捆绑和实际部署。 如果您只是想在资产捆绑过程中排除文件, 您应该利用 `exclude` 财产 `AssetOptions` 定义源时:

```ts
declare const destinationBucket: s3.Bucket;
new s3deploy.BucketDeployment(this, 'HTMLBucketDeployment', {
  sources: [s3deploy.Source.asset('./website', { exclude: ['*', '!index.html'] })],
  destinationBucket,
});
```

如果您想要指定在部署过程中使用的过滤器, 您可以使用 `exclude` 财务报告和审定财务报表 `include` 打开过滤器 `BucketDeployment`。如果排除,这些文件将不会被部署到目的地桶。 此外,如果文件在目的桶中已经存在,如果您正在使用 `prune` 选项 :

```ts
declare const destinationBucket: s3.Bucket;
new s3deploy.BucketDeployment(this, 'DeployButExcludeSpecificFiles', {
  sources: [s3deploy.Source.asset(path.join(__dirname, 'my-website'))],
  destinationBucket,
  exclude: ['*.txt'],
});
```

这些过滤器遵循的是AWS CLI所使用的相同格式. 详情见CLI文件 [使用包含和排除过滤器](https://docs.aws.amazon.com/cli/latest/reference/s3/index.html#use-of-exclude-and-include-filters)。 。 。 .

## 对象元数据

您可以指定用于部署中所有对象的元数据. S3中元数据有2个类型:系统自定义元数据和用户自定义元数据. 系统定义的元数据有一个特殊的目的,例如缓存控制定义了保存一个对象缓存的时间. S3 不使用用户定义的元数据,密钥总是从 `x-amz-meta-` (此前缀会自动添加).

系统定义的元数据密钥包括以下内容:

-   缓存控制( e)`--cache-control` 内 `aws s3 sync`(中文(简体) )
-   内容分散( e)`--content-disposition` 内 `aws s3 sync`(中文(简体) )
-   内容编码( e)`--content-encoding` 内 `aws s3 sync`(中文(简体) )
-   内容 - 语言`--content-language` 内 `aws s3 sync`(中文(简体) )
-   内容类型( e)`--content-type` 内 `aws s3 sync`(中文(简体) )
-   期满`--expires` 内 `aws s3 sync`(中文(简体) )
-   x- amz- 存储级( )`--storage-class` 内 `aws s3 sync`(中文(简体) )
-   x-amz-website-再定向定位(`--website-redirect` 内 `aws s3 sync`(中文(简体) )
-   x-amz- server- side- 加密 (`--sse` 内 `aws s3 sync`(中文(简体) )
-   x-amz-server-side-加密-aws-kms-key-id (英语:`--sse-kms-key-id` 内 `aws s3 sync`(中文(简体) )
-   x-amz-server-side-加密-客户-算法(`--sse-c-copy-source` 内 `aws s3 sync`(中文(简体) )
-   x- amz- acl (帮助`--acl` 内 `aws s3 sync`(中文(简体) )

您可以在 [S3 设置对象文档](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) 财务报告和审定财务报表 [`aws s3 sync` 文档](https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html)。 。 。 .

```ts
const websiteBucket = new s3.Bucket(this, 'WebsiteBucket', {
  websiteIndexDocument: 'index.html',
  publicReadAccess: true,
});

new s3deploy.BucketDeployment(this, 'DeployWebsite', {
  sources: [s3deploy.Source.asset('./website-dist')],
  destinationBucket: websiteBucket,
  destinationKeyPrefix: 'web/static', // optional prefix in destination bucket
  metadata: { A: "1", b: "2" }, // user-defined metadata

  // system-defined metadata
  contentType: "text/html",
  contentLanguage: "en",
  storageClass: s3deploy.StorageClass.INTELLIGENT_TIERING,
  serverSideEncryption: s3deploy.ServerSideEncryption.AES_256,
  cacheControl: [
    s3deploy.CacheControl.setPublic(),
    s3deploy.CacheControl.maxAge(Duration.hours(1)),
  ],
  accessControl: s3.BucketAccessControl.BUCKET_OWNER_FULL_CONTROL,
});
```

## 云纹无效

您可以提供 CloudFront 分发和可选路径, 以在桶部署完成后无效 .

```ts
import * as cloudfront from '@aws-cdk/aws-cloudfront';
import * as origins from '@aws-cdk/aws-cloudfront-origins';

const bucket = new s3.Bucket(this, 'Destination');

// Handles buckets whether or not they are configured for website hosting.
const distribution = new cloudfront.Distribution(this, 'Distribution', {
  defaultBehavior: { origin: new origins.S3Origin(bucket) },
});

new s3deploy.BucketDeployment(this, 'DeployWithInvalidation', {
  sources: [s3deploy.Source.asset('./website-dist')],
  destinationBucket: bucket,
  distribution,
  distributionPaths: ['/images/*.png'],
});
```

## 大小限制

部署资源的默认内存限制为128MiB. 如果你需要的话 复制更大的文件,您可以使用 `memoryLimit` 用于增加 aWS Lambda 资源处理器大小.

部署资源的默认麻黄存储大小为512MiB. 狦 需要上传更大的文件,您可能达到此限制 。 你可以用这个 `ephemeralStorageSize` 用于增加 AWS Lambda 存储大小的配置 资源处理器.

> 注意: 您的堆栈中将新建 AWS Lambda 处理器, 用于每种组合 内存和存储大小.

## EFS 支持

如果工作流程比默认的(512 MB)磁盘空间需要更多的磁盘空间,您可以附加一个 EFS 存储到下面 羊肉达功能. 启用 EFS 支持集 `efs` 财务报告和审定财务报表 `vpc` 巴克特部署的道具.

检查下方的样本使用情况 . 请注意,创建 VPC 内含可能导致堆栈删除失败. 为简洁起见,现将其列于下. 为了避免这种状况,您的网络在下方(VPC)保持单独堆放,并作为道具通过.

```ts
declare const destinationBucket: s3.Bucket;
declare const vpc: ec2.Vpc;

new s3deploy.BucketDeployment(this, 'DeployMeWithEfsStorage', {
  sources: [s3deploy.Source.asset(path.join(__dirname, 'my-website'))],
  destinationBucket,
  destinationKeyPrefix: 'efs/',
  useEfs: true,
  vpc,
  retainOnDelete: false,
});
```

## 有部署时间值的数据

内容转至 `Source.data()` 或者说 `Source.jsonData()` 可包含 只有在部署期间才能解决的参考文献.

例如:

```ts
import * as sns from '@aws-cdk/aws-sns';

declare const destinationBucket: s3.Bucket;
declare const topic: sns.Topic;

const appConfig = {
  topic_arn: topic.topicArn,
  base_url: 'https://my-endpoint',
};

new s3deploy.BucketDeployment(this, 'BucketDeployment', {
  sources: [s3deploy.Source.jsonData('config.json', appConfig)],
  destinationBucket,
});
```

数值在 `topic.topicArn` 是一个部署时间值。 只有解决 通过在生成的源文件中放置标记来进行部署,以及 以实际价值代替其部署到目的地.

## 页:1

-   此库使用一个 AWS CloudFormation 自定义资源, 大约是 10MiB in 尺寸。 此资源的代码与此库相捆绑 .
-   AWS Lambda的执行时间限于15min. 这限制了数据的数量 它可以部署在桶 在这个暂停.
-   当 `BucketDeployment` 从堆栈中取出,保留内容 在目的地桶内([952号](https://github.com/aws/aws-cdk/issues/952)) (中文(简体) ).
-   使用时 `s3deploy.Source.bucket()` 以获取文件源 另一桶: 只有在密钥( 文件名) 时才会更新已部署的文件 更改源桶中的文件。 正在更改文件不会到位 足够好: 如果属性不运行, 自定义资源将不会运行 变化.
    -   如果使用资产(`s3deploy.Source.asset()`你不用担心 关于这一点:资产系统将确保如果文件有变化, 文件名称是独一无二的,部署将运行.

## 发展

自定义资源在 Python 3.7 中被执行,以便杠杆化 用于"aws s3同步"的 AWS CLI. 密码在下面 [`lib/lambda`](https://github.com/aws/aws-cdk/tree/master/packages/%40aws-cdk/aws-s3-deployment/lib/lambda) 财务报告和审定财务报表 单位测试正在进行中 [`test/lambda`](https://github.com/aws/aws-cdk/tree/master/packages/%40aws-cdk/aws-s3-deployment/test/lambda)。 。 。 .

此软件包在构建时间需要 Python 3. 7 才能创建自定义 资源Lambda捆绑并测试. 还要靠几部剧本 所以 可能很难在Windows上发展.

## 路线图

-   [ ] 支持“蓝色/绿色”部署([954号](https://github.com/aws/aws-cdk/issues/954)(中文(简体) )

## 常见问题

### @aws-cdk/aws-s3-deployment 是什么？

用于向 S3 桶部署内容的构造注意：该包已被作者标记为弃用——AWS CDK v1 has reached End-of-Support on 2023-06-01\. This package is no longer being updated, and users should migrate to AWS CDK v2\. For more information on how to migrate, see https://docs\.aws\.amazon\.com/cdk/v2/guide/migrating-v2\.html

### 如何安装 @aws-cdk/aws-s3-deployment？

在项目目录运行 npm install @aws-cdk/aws-s3-deployment，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@aws-cdk/aws-cloudfront（1\.204\.0）、@aws-cdk/aws-ec2（1\.204\.0）、@aws-cdk/aws-efs（1\.204\.0）、@aws-cdk/aws-iam（1\.204\.0）、@aws-cdk/aws-lambda（1\.204\.0）、@aws-cdk/aws-logs（1\.204\.0）、@aws-cdk/aws-s3（1\.204\.0）、@aws-cdk/aws-s3-assets（1\.204\.0）、@aws-cdk/core（1\.204\.0）、@aws-cdk/lambda-layer-awscli（1\.204\.0）、constructs（^3\.3\.69）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws-cdk/aws-s3-deployment 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aws-cdk/aws-s3-deployment 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @aws-cdk/aws-s3-deployment 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 14\.15\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @aws-cdk/aws-s3-deployment 可以商用吗？

@aws-cdk/aws-s3-deployment 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aws-cdk/aws-s3-deployment 的下载量有多少？

根据 npm 官方下载统计，@aws-cdk/aws-s3-deployment 在 2026/10/08 – 2026/11/06 这 30 天内被下载 18,761 次，日均约 625 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aws-cdk/aws-s3-deployment 还在维护吗？

最新版本 1\.204\.0 发布于 2023/06/20（3 年前）；至今共发布 280 个版本，其中过去 12 个月发布了 0 个；首次发布于 2018/10/19。作者已将其标记为弃用，新项目建议寻找替代方案。