# @cdklabs/deploy-time-build 中文文档

规范地址：https://npmcn.com/package/%40cdklabs/deploy-time-build/

版本：0\.1\.16
npm 元数据更新时间：2026-11-04T08:29:47.540Z
中文译文更新时间：2026-11-09T06:20:07.293Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40cdklabs/deploy-time-build
原文对照：https://npmcn.com/package/%40cdklabs/deploy-time-build/?lang=original
项目主页：https://github.com/cdklabs/deploy-time-build#readme
源码仓库：https://github.com/cdklabs/deploy-time-build

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

- 包体积（解压后）：642 kB，27 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 18\.12\.0
- 运行依赖：0 个
- peer 依赖：constructs ^10\.5\.1，aws-cdk-lib ^2\.38\.0
- 首次发布：2026-01-16T13:45:20.409Z
- 最新版本发布：2026-11-04T08:29:47.139Z
- 近 30 天下载量：39497（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 27 个）

## 中文简介

根据 CDK 部署时间运行 .

## 安装

```sh
npm install @cdklabs/deploy-time-build
```

也可以使用：`pnpm add @cdklabs/deploy-time-build`、`yarn add @cdklabs/deploy-time-build`、`bun add @cdklabs/deploy-time-build`

## README

# 部署时间构建

AWS CDK L3 构造允许您为特定目的运行一个构建任务 。 目前,该图书馆支持下列使用案例:

-   构建网络前端静态文件
-   构建容器图像
-   为容器图像构建可搜索OCI(SOCI)索引

[![View on Construct Hub](https://constructs.dev/badge?package=%40cdklabs%2Fdeploy-time-build)](https://constructs.dev/packages/@cdklabs/deploy-time-build)

## 使用量

从 npm 安装 :

```sh
npm i @cdklabs/deploy-time-build
```

这个库定义了几种用于特定用途的L3构造. 以下是每个案例的用法.

### 构建节点js 应用程序

您可以在部署时间前构建一个节点. js app, 如 React 前端 app `NodejsBuild` 构造.

![architecture](https://npmcn.com/package/%40cdklabs/deploy-time-build/imgs/architecture.png)

以下代码是使用构造的实例 :

```ts
import { NodejsBuild } from '@cdklabs/deploy-time-build';

new NodejsBuild(this, 'ExampleBuild', {
    assets: [
        {
            path: 'example-app',
            exclude: ['dist', 'node_modules'],
        },
    ],
    destinationBucket,
    distribution,
    outputSourceDirectory: 'dist',
    buildCommands: ['npm ci', 'npm run build'],
    buildEnvironment: {
        VITE_API_ENDPOINT: api.url,
    },
    nodejsVersion: 24,
});
```

请注意,有可能通过环境变量 `VITE_API_ENDPOINT: api.url` ,并注入建筑环境(在此情况下是一个活化过程) 由此产生的建筑文物将部署到 `destinationBucket` 从代码构建.

您可以通过 `assets` 属性。 这些资产被提取到相应的子目录. 例如,假设您指定的资产如下:

```ts
new NodejsBuild(this, 'ExampleBuild', {
    assets: [
        {
            // directory containing source code and package.json
            path: 'example-app',
            exclude: ['dist', 'node_modules'],
            commands: ['npm install'],
        },
        {
            // directory that is also required for the build
            path: 'module1',
        },
    ],
    destinationBucket,
    distribution,
    outputSourceDirectory: 'dist',
    nodejsVersion: 24,
});
```

然后,所取目录将定位如下:

```sh
.                         # a temporary directory (automatically created)
├── example-app           # extracted example-app assets
│   ├── src/              # dist or node_modules directories are excluded even if they exist locally.
│   ├── package.json      # npm install will be executed since its specified in `commands` property.
│   └── package-lock.json
└── module1               # extracted module1 assets
```

您也可以覆盖通过 `extractPath` 每个资产的财产.

与 `outputEnvFile` 属性启用, a `.env` 文件会自动生成并上传到您的 S3 桶。 此文件可以在本地运行您的前端工程 。 通过运行堆栈输出中添加的命令,您可以将文件下载到您的本地机器.

请检查 [示例目录](https://npmcn.com/package/%40cdklabs/deploy-time-build/example/) 一个完整的例子.

#### 允许从建筑环境进入其他AWS资源

自兹 `NodejsBuild` 构造工具 [`iam.IGrantable`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IGrantable.html) 界面,您可以使用 `grant*` 允许从建筑环境进入的其他构造方法.

```ts
declare const someBucket: s3.IBucket;
declare const build: NodejsBuild;
someBucket.grantReadWrite(build);
```

您还可以使用 [`iam.Grant`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Grant.html) 允许任何行动和资源.

```ts
declare const build: NodejsBuild;
iam.Grant.addToPrincipal({ grantee: build, actions: ['s3:ListBucket'], resourceArns:['*'] })
```

#### 动机 - 为什么我们需要 `NodejsBuild` 构造?

在2023年的CDK日, 见下文录制或幻灯片:

[记录](https://www.youtube.com/live/b-nSH18gFQk?si=ogEZ2x1NixOj6J6j&t=373) | [幻灯片](https://speakerdeck.com/tmokmss/deploy-web-frontend-apps-with-aws-cdk)

#### 缓存

您可以启用 npm 缓存以加速使用 `cache` 属性 :

```ts
new NodejsBuild(this, 'ExampleBuild', {
    assets: [
        {
            path: 'example-app',
            exclude: ['dist', 'node_modules'],
        },
    ],
    destinationBucket,
    outputSourceDirectory: 'dist',
    cache: CacheType.S3, // or CacheType.LOCAL
    nodejsVersion: 24,
});
```

有两种缓存类型:

-   `CacheType.S3`: 将 npm 缓存目录存储在 S3 桶中 。 在不同的主机上运行的不经常.
-   `CacheType.LOCAL`:将 npm 缓存目录存储在构建主机上. 速度比S3快,但只有在相同的主机上运行才有效.

#### 计算类型

您可以使用 `computeType` 属性 :

```ts
new NodejsBuild(this, 'ExampleBuild', {
    assets: [
        {
            path: 'example-app',
            exclude: ['dist', 'node_modules'],
        },
    ],
    destinationBucket,
    outputSourceDirectory: 'dist',
    computeType: ComputeType.MEDIUM,
    nodejsVersion: 24,
});
```

#### 考虑因素

由于此构建每次您部署堆栈时都会构建您前端的应用程序, 并且输入资产有任何变化( 而目前 Lambda 函数中甚至没有构建缓存 !) , 部署的时间往往会更长( 例如, 即使是简单的应用程序, 也只有几分钟 ) `example` 目录。 ) 如果您想要频繁部署更改( magine ) , 可能会导致开发者经历更糟糕 `cdk watch` 部署总是重建你的前端应用程序.

为了缓解这个问题,你可以将前端构造的堆栈与其他堆栈分开,特别是为了一个 dev 环境. 另一种解决办法是将固定字符串设为资产散列,并避免在每次部署的基础上继续使用.

```ts
new NodejsBuild(this, 'ExampleBuild', {
    assets: [
        {
            path: '../frontend',
            exclude: ['node_modules', 'dist'],
            commands: ['npm ci'],
            // Set a fixed string as a asset hash to prevent deploying changes.
            // This can be useful for an environment you use to develop locally.
            assetHash: 'frontend_asset',
        },
    ],
    destinationBucket,
    distribution,
    outputSourceDirectory: 'dist',
    nodejsVersion: 24,
});
```

### 构建容器图像

您可以在部署时使用以下代码构建容器图像:

```ts
import { ContainerImageBuild } from '@cdklabs/deploy-time-build';

const image = new ContainerImageBuild(this, 'Build', { 
    directory: 'example-image', 
    buildArgs: { DUMMY_FILE_SIZE_MB: '15' },
    tag: 'my-image-tag',
});
new DockerImageFunction(this, 'Function', {
    code: image.toLambdaDockerImageCode(),
});
const armImage = new ContainerImageBuild(this, 'BuildArm', {
    directory: 'example-image',
    platform: Platform.LINUX_ARM64,
    repository: image.repository,
    zstdCompression: true,
});
new FargateTaskDefinition(this, 'TaskDefinition', { 
    runtimePlatform: { cpuArchitecture: CpuArchitecture.ARM64 } 
}).addContainer('main', {
    image: armImage.toEcsDockerImageCode(),
});
```

第三个参数(props)是多克-伊玛格-阿塞特属性的超集. 您可以设置一些额外的属性, 如 `tag`, (中文(简体) ), `repository`,以及 `zstdCompression`。 。 。 .

### 为容器图像构建 SOCI 索引

[可搜索 OCI (SOCI)](https://aws.amazon.com/about-aws/whats-new/2022/09/introducing-seekable-oci-lazy-loading-container-images/) 是帮助在远门 1. 4.0 上更快地启动亚马逊ECS任务的方法. 您可以使用 `SociIndexV2Build` 构造.

![soci-architecture](https://npmcn.com/package/%40cdklabs/deploy-time-build/imgs/soci-architecture.png)

以下代码是使用构造的实例 :

```ts
import { SociIndexV2Build } from '@cdklabs/deploy-time-build';

const asset = new DockerImageAsset(this, 'Image', { directory: 'example-image' });
const sociIndex = new SociIndexV2Build(this, 'SociV2Index', {
  repository: asset.repository,
  inputImageTag: asset.assetHash,
  outputImageTag: `${asset.assetHash}-soci`,
});

// Use with ECS Fargate
const taskDefinition = new FargateTaskDefinition(this, 'TaskDefinition');
taskDefinition.addContainer('main', {
  image: sociIndex.toEcsDockerImageCode(),
});

// Or create from DockerImageAsset using utility method
const sociIndexFromAsset = SociIndexV2Build.fromDockerImageAsset(this, 'SociV2Index2', asset);
```

这个 `SociIndexV2Build` 构造 :

-   使用输入容器图像并构建 SOCI v2 索引
-   使用嵌入的 SOCI 索引输出新图像标签
-   提供 `toEcsDockerImageCode()` 易与ECS任务使用的方法
-   在输入和输出图像时使用相同的ECR寄存器

我们目前使用 [`soci-wrapper`](https://github.com/tmokmss/soci-wrapper) 建立和推动SCI指数.

> \[尖叫声\] 前一个 `SocideIndexBuild` 构造现已贬值。 AWS Fargate上的SOCI新客户只能使用SOCI指数表 v2. 见 [本条](https://aws.amazon.com/blogs/containers/improving-amazon-ecs-deployment-consistency-with-soci-index-manifest-v2/) 更多细节.

#### 动机 - 为什么我们需要 `SociIndexBuild` 构造?

目前还有其他几种方法来构建SICI指数; 1. 使用 `soci-snapshotter` CLI,或作 2. 使用 [cfn-ecr-aws-soci-index-建设者](https://github.com/aws-ia/cfn-ecr-aws-soci-index-builder) 溶液,其中无一能从AWS CDK直接被使用. 熟悉CDK的,应当经常将容器图像作为CDK资产来部署,这是与ECS等其他L2构造融合的理想方式. 为了使SOCI的开发者经验与普通容器图像相近 `SociIndexBuild` 允许您直接从 CDK 中部署 SOCI 索引,而不在 CDK 上下文之外设置任何依赖性.

## 发展

维护者的命令 :

```sh
# run test locally
npx tsc -p tsconfig.dev.json
npx integ-runner
npx integ-runner --update-on-failed
```

## 常见问题

### @cdklabs/deploy-time-build 是什么？

根据 CDK 部署时间运行 \.

### 如何安装 @cdklabs/deploy-time-build？

在项目目录运行 npm install @cdklabs/deploy-time-build，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：constructs（^10\.5\.1）、aws-cdk-lib（^2\.38\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cdklabs/deploy-time-build 支持 TypeScript 吗？

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

### @cdklabs/deploy-time-build 支持 ESM 还是 CommonJS？

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

### @cdklabs/deploy-time-build 需要什么版本的 Node\.js？

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

### @cdklabs/deploy-time-build 可以商用吗？

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

### @cdklabs/deploy-time-build 的下载量有多少？

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

### @cdklabs/deploy-time-build 还在维护吗？

最新版本 0\.1\.16 发布于 2026/11/04（5 天前）；至今共发布 27 个版本，其中过去 12 个月发布了 27 个；首次发布于 2026/01/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。