这是 AWS CDK v2 开发者指南。旧版 CDK v1 于 2022 年 6 月 1 日进入维护阶段，并于 2023 年 6 月 1 日终止支持。
本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 配置 CDK 工具包实例
了解如何使用消息处理、AWS 配置文件选择和堆栈选择策略相关的选项来自定义 AWS CDK 工具包库实例。本指南介绍了可用的配置选项以及如何有效地实施这些选项来满足特定部署要求。
## 配置 AWS 配置文件
当您使用 CDK 工具包库时，它会使用 SDK 对 AWS 进行 API 调用。虽然身份验证会自动从您的环境中加载，但您可以显式指定要使用的配置文件：
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Create a toolkit instance with a specific AWS profile
const toolkit = new Toolkit({
sdkConfig: { profile: "my-profile" },
});
```
## 配置堆栈选择
大多数 CDK 工具包操作都要求您指定要对其执行操作的堆栈。` [StackSelector](https://docs.aws.amazon.com/cdk/api/toolkit-lib/Package/toolkit-lib/Interface/StackSelector/) ` 配置控制此选择。
### 选择所有堆栈
当您需要对 CDK 应用程序中的每个堆栈进行操作时，请使用这种方法：
```
import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';
// Select all stacks in the cloud assembly
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.ALL_STACKS
}
});
```
### 仅选择主程序集堆栈
使用此选项可仅选择主程序集中的顶层堆栈：
```
// Select only top-level stacks
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.MAIN_ASSEMBLY
}
});
```
### 选择单个堆栈
当您的程序集仅包含一个堆栈并且您想要断言此条件时，请使用这种方法。如果程序集包含单个堆栈，则会返回该堆栈。否则，将引发异常：
```
// Ensure there's exactly one stack and select it
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.ONLY_SINGLE
}
});
```
### 按模式选择堆栈
使用这种方法可按名称模式选择特定堆栈：
```
// Select stacks matching specific patterns
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
patterns: ["Dev-*", "Test-Backend"], // Supports wildcards
}
});
```
**提示**
使用 `PATTERN_MUST_MATCH_SINGLE` 可确保只有一个堆栈与您的模式匹配，而使用 `PATTERN_MATCH` 可允许没有堆栈匹配。模式匹配支持通配符，例如“\$1”可用于匹配名称相似的多个堆栈。
## 配置错误处理
CDK 工具包使用结构化错误来帮助您识别和处理问题。每个错误包括：
+ 指示错误来源的**来源**（工具包或用户）。
+ 特定**错误类型**（身份验证、验证等）。
+ 描述性**消息**。
### 处理错误
使用 CDK 工具包提供的辅助方法来检测和处理特定类型的错误：
```
import { ToolkitError } from '@aws-cdk/toolkit-lib';
try {
// Attempt a CDK Toolkit operation
await toolkit.deploy(cloudAssemblySource, {
stacks: { strategy: StackSelectionStrategy.ALL_STACKS }
});
} catch (error) {
// Handle specific error types
if (ToolkitError.isAuthenticationError(error)) {
// Example: AWS credentials are missing or invalid
console.error('Authentication failed. Check your AWS credentials.');
} else if (ToolkitError.isAssemblyError(error)) {
// Example: Your CDK app has errors in stack definitions
console.error('CDK app error:', error.message);
} else if (ToolkitError.isDeploymentError(error)) {
// Example: CloudFormation deployment failed
console.error('Deployment failed:', error.message);
} else if (ToolkitError.isToolkitError(error)) {
// Handle all other Toolkit errors
console.error('CDK Toolkit error:', error.message);
} else {
// Handle unexpected errors
console.error('Unexpected error:', error);
}
}
```
**重要**
不要依赖 `instanceof` 检查来确定错误类型，因为在处理同一包的多个副本时，它们可能会出现意外行为。请始终使用提供的辅助方法（例如 `ToolkitError.isAuthenticationError()`）。
## 配置工具包操作
每个 CDK 工具包操作（deploy、synth、list 等）都有自己的特定配置选项。这些操作使您能够管理 CDK 基础设施的完整生命周期。有关配置单个操作的详细信息，请参阅[配置 CDK 工具包编程操作](toolkit-library-actions.md)。
**提示**
构建自动化工作流时，请考虑按顺序组合多个操作。例如，您可能需要 `synth` 您的应用程序，`list` 堆栈以验证将要部署的内容，然后 `deploy` 基础设施。