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

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

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

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

原始 npm 页面：https://www.npmjs.com/package/%40aws-cdk/aws-s3-assets
原文对照：https://npmcn.com/package/%40aws-cdk/aws-s3-assets/?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 元数据）

- 包体积（解压后）：119 kB，15 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 14\.15\.0
- 运行依赖：7 个
- peer 依赖：@aws-cdk/assets 1\.204\.0，@aws-cdk/aws-iam 1\.204\.0，@aws-cdk/aws-kms 1\.204\.0，@aws-cdk/aws-s3 1\.204\.0，@aws-cdk/core 1\.204\.0，@aws-cdk/cx-api 1\.204\.0，constructs ^3\.3\.69
- 首次发布：2019-06-19T17:19:30.991Z
- 最新版本发布：2023-06-19T21:06:04.104Z
- 近 30 天下载量：368822（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：249（近 12 个月 0 个）

## 中文简介

向 S3 部署本地文件和目录

## 安装

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

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

## README

# AWS CDK 资产

* * *

![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)。 。 。 .

* * *

资产是一个 CDK 应用程序所需要的本地文件或目录 。 常见 示例是一个包含Lambda函数处理器代码的目录, 但资产可以代表应用程序操作所需的任何文物.

当部署包含资产构建的 CDK 应用程序时, CDK 工具包 将首先将全部资产上传到 S3 , 然后再部署堆栈 。 S3号 上传资产位置将作为 CloudFormation 参数传送 到相关的堆栈.

下面的 JavaScript 示例定义了存档的目录资产 a.zip文件并上传到部署期间的S3.

[Zip Directory Asset 实例](https://npmcn.com/package/%40aws-cdk/aws-s3-assets/test/integ.assets.directory.lit.ts)

下面的 JavaScript 示例定义了文件资产, 它被上传为- is 在部署时,到一个S3桶.

[文件集示例](https://npmcn.com/package/%40aws-cdk/aws-s3-assets/test/integ.assets.file.lit.ts)

## 属性

`Asset` 构造显示以下部署时间属性:

-   `s3BucketName` - 资产名称S3桶.
-   `s3ObjectKey` - 资产文件的S3对象密钥(无论是文件还是zip归档)
-   `s3ObjectUrl` - 资产S3对象URL(即s3://mybucket/mykey.zip)
-   `httpUrl` - 资产S3 HTTP URL(即:. [https://s3.us-east-1.amazonaws.com/mybucket/mykey.zip 页面存档备份,存于互联网档案馆](https://s3.us-east-1.amazonaws.com/mybucket/mykey.zip)(中文(简体) )

在下面的例子中,各种资产属性作为堆栈输出:

[资产参考实例](https://npmcn.com/package/%40aws-cdk/aws-s3-assets/test/integ.assets.refs.lit.ts)

## 权限

需要能够在运行时间读取资产的IAM角色、用户或团体应为: 获得IAM许可. 用这个 `asset.grantRead(principal)` 方法 :

以下实例赋予一个IAM组读取资产权限:

[准予读取资产的例子](https://npmcn.com/package/%40aws-cdk/aws-s3-assets/test/integ.assets.permissions.lit.ts)

## 怎么会这样

当在构建中定义资产时, 构建元数据条目 `aws:cdk:asset` 发出指示,说明在哪里找到资产和什么 拟使用的包装类型(`zip` 或者说 `file`) (中文(简体) ). 此外,综合的 CloudFormation模板还将包括两个CloudFormation参数:一个用于 资产桶和一个资产S3键。 这些参数用于 引用资产的部署时间值(使用 `{ Ref: "Param" }`) (中文(简体) ).

然后,当堆栈部署时,工具包将包装资产(即zip) ),计算内容的 MD5 散列,并将生成 S3 键 在工具包资产库内为这一资产提供资产。 如果文件不存在 资产存储器,在部署时上传.

> 工具箱的资产库是工具包为每个工具箱创建的S3桶 该工具包在环境中运作(环境=账户+区域).

现在,当工具包部署堆栈时,它会设置相关的"云阵" 指每个资产的实际桶和钥匙的参数.

## 资产

在定义资产时,您可以使用 `bundling` 选项以指定命令 在一个容器内运行。 命令可以读取资产的内容 来源 `/asset-input` 并预计将在 `/asset-output` (在容器内绘制的指南). 下方的文件 `/asset-output` 将 作为资产被拉链并上传到 S3 .

以下示例使用自定义资产捆绑将标记下的文件转换为html:

[使用资产捆绑的例子](https://npmcn.com/package/%40aws-cdk/aws-s3-assets/test/integ.assets.bundling.lit.ts)。 。 。 .

捆绑的嵌入器图像( E)`image`要么来自登记处(`DockerImage.fromRegistry`(中文(简体) ) 也可以从 `Dockerfile` 位于您的项目内( e)`DockerImage.fromBuild`) (中文(简体) ).

你可以设置 `CDK_DOCKER` 提供自定义的环境变量 要执行的多克程序 。 这在建于 无法执行标准嵌入符的环境(参见 [https://github.com/aws/aws-cdk/issues/8460 (英语)](https://github.com/aws/aws-cdk/issues/8460) 详细情况请查阅.

使用 `local` 指定本地捆绑提供者。 提供者执行 方法 `tryBundle()` 应返回的 `true` 如果进行了局部捆绑. 若为 `false` 返回时,将进行嵌入:

```ts
class MyBundle implements ILocalBundling {
  public tryBundle(outputDir: string, options: BundlingOptions) {
    const canRunLocally = true // replace with actual logic
    if (canRunLocally) {
      // perform local bundling here
      return true;
    }
    return false; 
  }
}

new assets.Asset(this, 'BundledAsset', {
  path: '/path/to/asset',
  bundling: {
    local: new MyBundle(),
    // Docker bundling fallback
    image: DockerImage.fromRegistry('alpine'),
    entrypoint: ['/bin/sh', '-c'],
    command: ['bundle'],
  },
});
```

虽然是可选的,但建议提供一种当地捆绑方法,可以 大大提高了业绩.

如果捆绑输出包含单个归档文件( zip 或 罐子) , 将会是 上传到 S3 状态, 将不会被拉链 。 否则,内容 输出目录会被拉链并上传到 S3 。 这个 是默认行为 `bundling.outputType` (单位:千美元)`BundlingOutput.AUTO_DISCOVER`) (中文(简体) ).

使用 `BundlingOutput.NOT_ARCHIVED` 如果捆绑输出必须总是被拉链:

```ts
const asset = new assets.Asset(this, 'BundledAsset', {
  path: '/path/to/asset',
  bundling: {
    image: DockerImage.fromRegistry('alpine'),
    command: ['command-that-produces-an-archive.sh'],
    outputType: BundlingOutput.NOT_ARCHIVED, // Bundling output will be zipped even though it produces a single archive file.
  },
});
```

使用 `BundlingOutput.ARCHIVED` 如果捆绑输出包含单个归档文件 你不希望它被拉开.

## 云格式资源元数据

> 注:本节与AWS资源构造的作者相关.

在某些情况下,工具应该能够知道某种云形 资源正在使用本地资产。 例如,SAM CLI可用于引用AWS Lambda函数 用于本地调试目的.

为方便此类使用,外部工具将查阅AWS CloudFormation上的一组元数据条目 资源:

-   `aws:asset:path` 指资产的地方路径.
-   `aws:asset:property` 是使用该资产的资源财产的名称

使用这两个元数据条目,工具将能够识别资产是否被使用 利用某种资源,并促成先进的当地经验.

要将这些元数据条目添加到资源中,请使用 `asset.addResourceMetadata(resource, property)` 方法.

见 [https://github.com/aws/aws-cdk/issues/1432 (中文(简体) )](https://github.com/aws/aws-cdk/issues/1432) 详情

## 常见问题

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

向 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-assets？

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

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

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

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

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

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

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

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

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

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

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

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

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