这是 AWS CDK v2 开发者指南。旧版 CDK v1 于 2022 年 6 月 1 日进入维护阶段，并于 2023 年 6 月 1 日终止支持。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

配置 CDK 工具包实例

了解如何使用消息处理、 AWS 配置文件选择和堆栈选择策略选项来自定义 AWS CDK Toolkit 库实例。本指南介绍了可用的配置选项以及如何有效地实施这些选项以满足您的特定部署要求。

配置您的 AWS 个人资料

当你使用 CDK 工具包库时，它会 AWS 使用 SDK 调用 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 Toolkit 操作都要求您指定要对哪些堆栈进行操作。 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
  }
});

配置错误处理

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);
  }
}

配置工具包操作

每个 CDK Toolkit 操作（部署、合成、列表等）都有自己的特定配置选项。这些操作允许您管理 CDK 基础设施的整个生命周期。有关配置单个操作的详细信息，请参阅配置 CDK Toolkit 编程操作。