# @aws-cdk/toolkit-lib 中文文档

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

版本：1\.46\.0
npm 元数据更新时间：2026-11-05T16:22:28.349Z
中文译文更新时间：2026-11-07T09:28:03.495Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：11.8 MB，546 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 18\.0\.0
- 运行依赖：46 个
- peer 依赖：@aws-cdk/cli-plugin-contract ^2
- 首次发布：2025-02-24T19:51:54.263Z
- 最新版本发布：2026-11-05T16:22:27.962Z
- 近 30 天下载量：1356198（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：113（近 12 个月 68 个）

## 中文简介

AWS CDK 程序工具包库

## 安装

```sh
npm install @aws-cdk/toolkit-lib
```

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

## README

# AWS CDK 工具包库

AWS Cloud Development Kit(AWS CDK)工具包库使您能够执行需要AWS程序访问的CDK动作. 您可以使用 AWS CDK 工具包库来实施诸如靴子绑定,合成等动作,并通过代码而不是命令行界面(CLI)命令来部署. 通过这个库,您可以创建自定义工具,构建专门的CLI应用程序,并将CDK程序访问能力整合到您的开发工作流程中.

## 启动 AWS CDK 工具包库

### 步骤1:安装 CDK 工具包库

添加数据 `@aws-cdk/toolkit-lib` 代码基础的软件包 :

```console
npm install --save @aws-cdk/toolkit-lib
```

### 第2步:创建并配置新的 CDK 工具包实例

您将使用 CDK 工具包实例来定义要在您的 CDK 应用程序上执行的动作 . 以下是创建CDK工具包新实例的例子:

```ts
import { Toolkit } from '@aws-cdk/toolkit-lib';

const cdk = new Toolkit({
   // Optional configuration options go here
});
```

您可以在创建期间选择自定义 CDK 工具包实例 . 关于说明,见 [配置您的 CDK 工具包实例](https://npmcn.com/package/%40aws-cdk/toolkit-lib/#readme-configure-your-cdk-toolkit-instance)。 。 。 .

### 步骤 3: 为您的 CDK 应用程序创建云组装源

A 类 _云团_ 代表由 CDK app 生成的 AWS CloudFormation 模板和部署文物. 利用CDK, 云会是在合成过程中产生的, 是用来提供你的基础设施的. CDK 工具包创建 _云团_ 从a _云组源_。 。 。 .

这个 _云组源_ cDK工具箱的一个基本组成部分,它界定了创建一个 _云团_ 从你的应用程序. 例如,CDK应用程序在准备就绪之前可能需要用额外的上下文值进行多次合成. 一旦创建,你就可以使用你的 _云组源_ 用 CDK 工具箱执行动作.

下面是创建一个 _云组源_ 使用 _组装构建器功能_数字 :

```ts
import * as core from 'aws-cdk-lib/core';

declare const cdk: Toolkit;

const cx = await cdk.fromAssemblyBuilder(async (props) => {
  const app = new core.App({
    outdir: props.outdir,
    context: props.context,
  });

  // Define your stacks here
  new MyStack(app, 'MyStack', {
    env: {
      account: props.CDK_DEFAULT_ACCOUNT,
      region: props.CDK_DEFAULT_REGION,
    },
  });

  return app.synth();
});
```

详情见 [云组源](https://npmcn.com/package/%40aws-cdk/toolkit-lib/#readme-cloud-assembly-sources)。 。 。 .

### 步骤 4: 为您的 CDK 应用程序定义方案行动

现在您已经创建了 CDK 工具包实例和 Cloud Assembly Source, 您可以开始定义方案行动 . 下面是一个基本例子,可以部署 `MyStack` 堆栈 :

```ts
declare const cdk: Toolkit;
declare const cx: ICloudAssemblySource;

await cdk.deploy(cx, {
  stacks: {
    strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
    patterns: ["MyStack"],
  },
});
```

### 第5步:进一步定制光盘工具包

您可以为您的需要进一步配置和定制 CDK 工具包 :

-   **信件和请求** - CDK工具包提供有条理的信息流,并向客户请求,例如使用CDK工具包的人类行为者或应用程序。 关于说明,见 [信件交互( M)](https://npmcn.com/package/%40aws-cdk/toolkit-lib/#readme-messages--interaction)。 。 。 .
-   **处理错误** - CDK工具箱使用结构化错误帮助您在工具箱操作中识别和处理问题。 您可以将错误处理整合到您的应用程序中, 或者根据您的需要进一步定制它们 。 关于说明,见 [处理错误](https://npmcn.com/package/%40aws-cdk/toolkit-lib/#readme-error-handling)。 。 。 .

## 行动

CDK工具包库为下列生命周期行动提供方案接口. 对进一步行动的支持将逐步扩大.

### 合成

合成是生产AWS CloudFormation模板和从CDK应用中部署文物的过程. 综合介绍见 [配置并进行 CDK 堆栈合成](https://docs.aws.amazon.com/cdk/v2/guide/configure-synth.html)。 。 。 . 在 CDK 工具包库中,您可以使用合成生成一个可重复使用的快照 _云组源_。 。 。 . 如果同一来源将被用于多个工具包行动,这将是有益的, 因为 _云团_ 无需多次生产.

```ts
declare const cdk: Toolkit;
declare const source: ICloudAssemblySource;

// Will run the CDK app defined in the Cloud Assembly Source
// This is an expensive and slow operation
// But its result can be stored and re-used
const cx = await cdk.synth(source, {
  validateStacks: true, // set to `false` to not throw an error if stacks in the assembly contain error annotations
})

// Will use the previously synthesized Cloud Assembly
// This is now a cheap and fast operation
const appDetails = await cdk.list(cx);
```

您也可以查询关于已合成的信息 _云团_数字 :

```ts
const cloudAssembly = await cx.produce();
const template = cloudAssembly.getStackByName("my-stack").template;
```

### 列表

列表操作在一个 CDK 应用程序中提供有关堆栈及其依赖的高级信息.

```ts
declare const cdk: Toolkit;
declare const cx: ICloudAssemblySource;

const details = await cdk.list(cx, {
  // optionally provide a stack selector to control which stacks are returned
  stacks: {
    strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
    patterns: ["my-stack"],
  }
});
```

### 微调

您可以创建一个应用程序的 diff 来详细了解下个部署中将会发生什么变化.

```ts
declare const cdk: Toolkit;
declare const cx: ICloudAssemblySource;

const stackDiffs = await cdk.diff(cx, {
  // optionally provide a stack selector to control which stacks you want to create a diff for
  stacks: {
    strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
    patterns: ["my-stack"],
  }
});
```

### 部署

部署是使用在合成过程中生成的CloudFormation模板和资产在AWS提供或更新基础设施的过程. 关于部署的介绍,见 [部署 AWS CDK 应用程序](https://docs.aws.amazon.com/cdk/v2/guide/deploy.html)。 。 。 . 有了CDK工具包库,可以程序控制部署,包括堆栈选择,回滚行为,部署监测.

```ts
declare const cdk: Toolkit;
declare const cx: ICloudAssemblySource;

await cdk.deploy(cx, {
  deploymentMethod: { method: "direct " }, // use direct deployments instead of change-sets
  parameters: StackParameters.exactly({ /* ... */ }), // provide new values for stack parameters
})
```

### 倒滚

当部署失败或需要倒转时,回滚返回堆栈到其最后一个稳定状态. CDK工具包库允许您在程序上滚动失败的部署 .

```ts
declare const cdk: Toolkit;
declare const cx: ICloudAssemblySource;

await cdk.rollback(cx, {
  orphanFailedResources: false, // set to `true` to automatically orphan all failed resources
})
```

### 监视

使用手表特性来持续监视您的 CDK 应用程序用于本地修改并自动执行部署或热浪. 这将创建一个文件监视器, 一旦您的代码退出, 文件监视器就会终止 .

```ts
declare const cdk: Toolkit;
declare const cx: ICloudAssemblySource;

await cdk.watch(cx, {
  include: [], // optionally provide a list of file path patterns to watch
  exclude: [], // or exclude files by file path patterns
})
```

### 漂移

漂流探测对维持基础设施的可靠性至关重要. 它识别您部署的资源在您的 CDK 代码之外被修改的时间 . 这使得您可以快速处理未经授权的更改 . 这些变化可能导致安全漏洞,合规问题,或者你云层环境中出人意料的行为.

使用漂移操作检测您的 CDK 应用程序中的漂移 :

```ts
declare const cdk: Toolkit;
declare const cx: ICloudAssemblySource;

const stackDrifts = await cdk.drift(cx, {
  // optionally provide a stack selector to control which stacks are checked for drift
  stacks: {
    strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
    patterns: ["my-stack"],
  }
});
```

### 销毁

使用销毁特性从 AWS 中删除 CDK 堆栈及其相关资源 :

```ts
declare const cdk: Toolkit;
declare const cx: ICloudAssemblySource;

await cdk.destroy(cx, {
  // optionally provide a stack selector to control which stacks are destroyed
  stacks: {
    strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
    patterns: ["my-stack"],
  }
})
```

## 配置您的 CDK 工具包实例

### 信件交互( M)

CDK工具包提供了结构化流程: _信件_ 财务报告和审定财务报表 _请求_ 回到客户端 与工具包整合.

-   **信件** - 向客户通报行动的进展和状况。 不需要回应.
-   **请求** - 允许客户端回复的特别信息。 如果没有答复,工具包将使用默认答复.

CDK工具包图书馆通过一个 `IoHost`。 。 。 . 考虑一下 `IoHost` 作为确定CDK工具包的通信工作方式的蓝图. 对于每条信息或请求,工具包称为: `notify` 或者说 `requestResponse` 方法 `IoHost`。 。 。 .

#### 自定义IoHost

您可以配置自定义 `IoHost` 控制信息流动,并将其纳入工作流程和自动化. 以下为简单记录所有消息对象的 stdout 实例执行 :

```ts
const toolkit = new toolkitLib.Toolkit({
  ioHost: {
    notify: async function (msg) {
      console.log(msg);
    },
    requestResponse: async function (msg) {
      console.log(msg);
      return msg.defaultResponse;
    }
  }
})
```

CDK工具包等待每个呼叫完成,允许客户端在处理消息或请求时进行HTTP请求等同步操作. 当你执行一个 `IoHost` 界面,您可以处理这些通信(例如记录到 Cloud Watch 或提示用户输入),也可以不采取行动立即返回. 如果您的执行无法对请求做出回应, CDK 工具包会以默认值进行.

#### 默认 `NonInteractiveIoHost`

默认情况下, CDK 工具包库将使用 `NonInteractiveIoHost` 执行模仿 AWS CDK 工具包 CLI 的行为. 这个 `NonInteractiveIoHost` 可供您使用,作为可延长的基础.

### 配置您的 AWS 配置文件

工具包内部使用AWS SDK客户端,向AWS发出必要的API呼叫. 认证配置从环境中自动加载, 但您可以明确指定要使用的基础证书 :

```ts
import { Toolkit, BaseCredentials } from '@aws-cdk/toolkit-lib';

const cdk = new Toolkit({
  sdkConfig: {
    baseCredentials: BaseCredentials.awsCliCompatible({ profile: "my-profile" })
  },
});
```

### 配置 SDK 调用代理

工具包内部使用AWS SDK客户端,向AWS发出必要的API呼叫. 您可以指定一个节点.js代理来配置 SDK 调用 . 这使得您可以配置第三方软件包 [`proxy-agent`](https://www.npmjs.com/package/proxy-agent) 到代理所有 SDK 调用 :

```ts
import { ProxyAgent } from 'proxy-agent';
import { Toolkit } from '@aws-cdk/toolkit-lib';

const cdk = new Toolkit({
  sdkConfig: {
    httpOptions: {
      agent: new ProxyAgent(),
    },
  },
});
```

## 配置工具箱动作

CDK工具包库提供的每一个动作都有自己的选项. 然而,在多种行动之间有一些论点和选择.

## 云组源

这个 _云组源_ cDK工具箱的一个基本组成部分,它界定了创建一个 _云团_ 从你的应用程序. 例如,CDK应用程序在准备就绪之前可能需要用额外的上下文值进行多次合成. 一旦创建,你就可以使用你的 _云组源_ 用 CDK 工具箱执行动作.

每个 _云组源_ 必须执行 `ICloudAssemblySource` 接口。 这使得您可以定义自己的自定义源 .

```ts
interface ICloudAssemblySource {
  produce(): Promise<cxapi.CloudAssembly>;
}
```

为方便起见,CDK工具包库提供了一系列标准来源,可以使用 `fromXyz()` 工具箱实例上的帮助方法 .

大多数已存在的 CCDK app 被写成 JavaScript app 或使用 jsii 语言. 使用 CDK 工具包库,您可以通过提供 CDK 应用程序 `app` 字符串在 a 中找到 `cdk.json` 文件 :

```ts
declare const cdk: Toolkit;

// TypeScript
await cdk.fromCdkApp("tsx app.ts");

// Python
await cdk.fromCdkApp("python app.py");
```

这个 `AssemblyBuilder` 函数提供了Lookups等基本工具包功能,但除此之外,允许您执行任何自定义源. 例如,您在飞行上构建了内置的 CDK 应用程序 。 通常传递给运行中的 CDK 框架的合成操作参数 在通过环境变量的子进程中,通过参数对象传递,您需要将它们明确传递到框架中:

```ts
declare const cdk: Toolkit;

const cx = await cdk.fromAssemblyBuilder(async (props) => {
  const app = new core.App({
    outdir: props.outdir,
    context: props.context,
  });

  // Define your stacks here
  new MyStack(app, 'MyStack', {
    env: {
      account: props.CDK_DEFAULT_ACCOUNT,
      region: props.CDK_DEFAULT_REGION,
    },
  });

  return app.synth();
});
```

> 注意: `AssemblyBuilder` 无法安全执行 同时,因为它改变了全球共享的 `process.env`设置 `clobberEnv: false` 来避免这种情况,但您的构建者功能需要做一个 多一点工作。 见文件 `clobberEnv` 举个例子.

现有 _云团_ 目录可用作此类源 :

```ts
declare const cdk: Toolkit;

const cx = await cdk.fromAssemblyDirectory("cdk.out");
```

## 堆栈选择

CDK工具包的大多数行动都采用 `StackSelector` 要配置堆栈,该操作应当使用. A 类 `StackSelector` 和一些可选的额外值.

要选择所有堆栈,请使用 `ALL_STACKS` 战略:

```ts
const allStacks = { strategy: StackSelectionStrategy.ALL_STACKS };
```

要从主组件中选择顶级堆栈,请使用 `MAIN_ASSEMBLY` 战略:

```ts
const mainStacks = { strategy: StackSelectionStrategy.MAIN_ASSEMBLY };
```

这个 `ONLY_SINGLE` 策略允许您确保给定的集合包含完全一个堆栈,并选择它:

```ts
const mainStacks = { strategy: StackSelectionStrategy.ONLY_SINGLE };
```

要通过 ID 选择堆栈,请使用 `PATTERN_MUST_MATCH` 增加一个 `patterns` 属性. 如果没有匹配的堆栈,此策略会出错 .

```ts
const matchStacks = {
  strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
  patterns: ["MyStack"],
};
```

您可以选择声明, 通过使用 : `PATTERN_MUST_MATCH_SINGLE`, (中文(简体) ), 或通过使用完全无法匹配 `PATTERN_MATCH`。 。 。 .

## 处理错误

CDK工具包使用结构化错误帮助您在CDK工具包操作中识别和处理问题. 这些错误提供了详细的信息,说明出错的原因.

每个出错都包括以下来源之一,代表出错来源: 1

-   工具包 - 出自 CDK 工具包出错.
-   用户 - 出自用户的错误,例如配置或用户输入错误.

每个出错还包含一个特定的出错类型,如认证或验证,以及一个描述性消息. 您可以在应用程序中捕捉和处理这些错误,以给出适当的响应或倒置行为. 如果 CDK 工具包抛出其他例外, 它们是错误, 您应该通过提出问题来报告

### 如何处理错误

在CDK工具包库中,所有出错都会被抛出作为常规例外.

使用由 CDK 工具包提供的帮助方法来检测出错误类型. 即使输入了错误,也不要依赖检查的例子,因为它们在使用同一个包的多份副本时可以出乎意料地表现.

下面是一个基本的例子:

```ts
declare const cdk: Toolkit;
declare const cx: ICloudAssemblySource;

try {
  // Attempt a CDK Toolkit operation
  const deployment = await cdk.deploy(cx, {
    stacks: ['MyStack']
  });

} catch (error) {
  // Handle user error
  if (ToolkitError.isToolkitError(error) && error.source === 'user') {
    console.error('Hey, something is wrong with your app!', error.message);
  } else {
    throw error;
  }
}
```

## 常见问题

### @aws-cdk/toolkit-lib 是什么？

AWS CDK 程序工具包库

### 如何安装 @aws-cdk/toolkit-lib？

在项目目录运行 npm install @aws-cdk/toolkit-lib，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@aws-cdk/cli-plugin-contract（^2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws-cdk/toolkit-lib 支持 TypeScript 吗？

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

### @aws-cdk/toolkit-lib 支持 ESM 还是 CommonJS？

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

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

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

### @aws-cdk/toolkit-lib 可以商用吗？

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

### @aws-cdk/toolkit-lib 的下载量有多少？

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

### @aws-cdk/toolkit-lib 还在维护吗？

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