这是 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 配置控制此选择。

选择所有堆栈

当您需要对 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 工具包操作（deploy、synth、list 等）都有自己的特定配置选项。这些操作使您能够管理 CDK 基础设施的完整生命周期。有关配置单个操作的详细信息，请参阅配置 CDK 工具包编程操作。