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

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

# AWS CDK CLI 命令参考
<a name="ref-cli-cmd"></a>

本节包含 AWS 云开发工具包 (AWS CDK) 命令行界面 (CLI) 的命令参考信息。CDK CLI 也称为 CDK 工具包。

## 使用量
<a name="ref-cli-cmd-usage"></a>

```
$ cdk <command> <arguments> <options>
```

## 命令
<a name="ref-cli-cmd-commands"></a><a name="ref-cli-cmd-commands-acknowledge"></a>

 ` acknowledge ack `   
按问题编号确认通知，并将其隐藏，以免再次显示。<a name="ref-cli-cmd-commands-bootstrap"></a>

 ` bootstrap `   
将名为 `CDKToolkit` 的 CDK 引导堆栈部署到 AWS 环境中，从而为 CDK 部署准备 AWS 环境。<a name="ref-cli-cmd-commands-context"></a>

 ` context `   
管理 CDK 应用程序的缓存上下文值。<a name="ref-cli-cmd-commands-deploy"></a>

 ` deploy `   
将一个或多个 CDK 堆栈部署到您的 AWS 环境中。<a name="ref-cli-cmd-commands-destroy"></a>

 ` destroy `   
从您的 AWS 环境中删除一个或多个 CDK 堆栈。<a name="ref-cli-cmd-commands-diff"></a>

 ` diff `   
执行 diff 以查看 CDK 堆栈之间的基础设施更改。<a name="ref-cli-cmd-commands-docs"></a>

 ` docs doc `   
在浏览器中打开 CDK 文档。<a name="ref-cli-cmd-commands-doctor"></a>

 ` doctor `   
检查并显示有关您本地 CDK 项目和开发环境的有用信息。<a name="ref-cli-cmd-commands-drift"></a>

 ` drift `   
检测您使用 CDK 定义、管理和部署的资源的配置偏差。<a name="ref-cli-cmd-commands-flags"></a>

 ` flags `   
查看和修改 CDK CLI 的功能标志配置。<a name="ref-cli-cmd-commands-import"></a>

 ` import `   
使用 AWS CloudFormation 资源导入将现有 AWS 资源导入 CDK 堆栈。<a name="ref-cli-cmd-commands-init"></a>

 ` init `   
从模板中创建新的 CDK 项目。<a name="ref-cli-cmd-commands-list"></a>

 ` list, ls `   
列出 CDK 应用程序中的所有 CDK 堆栈及其依赖项。<a name="ref-cli-cmd-commands-metadata"></a>

 ` metadata `   
显示与 CDK 堆栈关联的元数据。<a name="ref-cli-cmd-commands-migrate"></a>

 ` migrate `   
将 AWS 资源、AWS CloudFormation 堆栈和 CloudFormation 模板迁移到新的 AWS CDK 项目中。<a name="ref-cli-cmd-commands-notices"></a>

 ` notices `   
显示您 CDK 应用程序的通知。<a name="ref-cli-cmd-commands-refactor"></a>

 ` refactor `   
在 CDK 应用程序中重构代码时，请保留已部署的资源。<a name="ref-cli-cmd-commands-synthesize"></a>

 ` synthesize, synth `   
合成 CDK 应用程序以生成云程序集，包括每个堆栈的 AWS CloudFormation 模板。<a name="ref-cli-cmd-commands-watch"></a>

 ` watch `   
持续关注本地 CDK 项目的变更，以执行部署和热交换。

## 全局选项
<a name="ref-cli-cmd-options"></a>

以下选项与所有 CDK CLI 命令都兼容。<a name="ref-cli-cmd-options-app"></a>

 `--app, -a <STRING>`   
提供运行应用程序或云程序集目录的命令。  
 *必需*：是<a name="ref-cli-cmd-options-asset-metadata"></a>

 `--asset-metadata <BOOLEAN>`   
包括使用资产的资源的 `aws:asset:*` AWS CloudFormation 元数据。  
 *必需*：否  
 *默认值*：`true`<a name="ref-cli-cmd-options-build"></a>

 `--build <STRING>`   
用于运行合成前版本的命令。  
 *必需*：否<a name="ref-cli-cmd-options-ca-bundle-path"></a>

 `--ca-bundle-path <STRING>`   
验证 HTTPS 请求时要使用的 CA 证书的路径。  
如果未提供此选项，则 CDK CLI 将从 `AWS_CA_BUNDLE` 环境变量中读取。  
 *必需*：是<a name="ref-cli-cmd-options-ci"></a>

 `--ci <BOOLEAN>`   
表明 CDK CLI 命令正在持续集成 (CI) 环境中运行。  
此选项可修改 CDK CLI 的行为，以更好地适应 CI 管线中常见的自动化操作。  
当提供此选项时，日志将发送到 `stdout` 而非 `stderr`。  
 *必需*：否  
 *默认值*：`false`<a name="ref-cli-cmd-options-context"></a>

 `--context, -c <ARRAY>`   
将上下文字符串添加为键值对。<a name="ref-cli-cmd-options-debug"></a>

 `--debug <BOOLEAN>`   
启用详细调试信息功能。此选项会生成详细输出，其中包含有关 CDK CLI 在后台所执行操作的更多详细信息。  
 *必需*：否  
 *默认值*：`false`<a name="ref-cli-cmd-options-ec2creds"></a>

 `--ec2creds, -i <BOOLEAN>`   
强制 CDK CLI 尝试获取 Amazon EC2 实例凭证。  
默认情况下，CDK CLI 会猜测 Amazon EC2 实例状态。  
 *必需*：否  
 *默认值*：`false`<a name="ref-cli-cmd-options-help"></a>

 `--help, -h <BOOLEAN>`   
显示 CDK CLI 的命令参考信息。  
 *必需*：否  
 *默认值*：`false`<a name="ref-cli-cmd-options-ignore-errors"></a>

 `--ignore-errors <BOOLEAN>`   
忽略合成错误，这可能会产生无效的输出。  
 *必需*：否  
 *默认值*：`false`<a name="ref-cli-cmd-options-json"></a>

 `--json, -j <BOOLEAN>`   
对于打印到标准输出 (`stdout`) 的 AWS CloudFormation 模板，请使用 JSON 而非 YAML。  
 *必需*：否  
 *默认值*：`false`<a name="ref-cli-cmd-options-lookups"></a>

 `--lookups <BOOLEAN>`   
执行上下文查找。  
如果此值为 `false`，并且需要执行上下文查找，则合成将失败。  
 *必需*：否  
 *默认值*：`true`<a name="ref-cli-cmd-options-no-color"></a>

 `--no-color <BOOLEAN>`   
从控制台输出中删除颜色和其他样式。  
 *必需*：否  
 *默认值*：`false`<a name="ref-cli-cmd-options-notices"></a>

 `--notices <BOOLEAN>`   
显示相关通知。  
 *必需*：否  
 *默认值*：`false`<a name="ref-cli-cmd-options-output"></a>

 `--output, -o <STRING>`   
指定输出合成云程序集的目录。  
 *必需*：是  
 *默认值*：`cdk.out`<a name="ref-cli-cmd-options-path-metadata"></a>

 `--path-metadata <BOOLEAN>`   
包括每种资源的 `aws::cdk::path` AWS CloudFormation 元数据。  
 *必需*：否  
 *默认值*：`true`<a name="ref-cli-cmd-options-plugin"></a>

 `--plugin, -p <ARRAY>`   
扩展 CDK 功能的 node 软件包的名称或路径。可以在单个命令中多次提供此选项。  
您可以在项目的 `cdk.json` 文件中或本地开发计算机上的 `~/.cdk.json` 中配置此选项：  

```
{
   // ...
   "plugin": [
      "module_1",
      "module_2"
   ],
   // ...
}
```
 *必需*：否<a name="ref-cli-cmd-options-profile"></a>

 `--profile <STRING>`   
指定要与 CDK CLI 一起使用的 AWS 配置文件的名称，其中包含您的 AWS 环境信息。  
 *必需*：是<a name="ref-cli-cmd-options-proxy"></a>

 `--proxy <STRING>`   
使用指定的代理。  
如果未提供此选项，则 CDK CLI 将从 `HTTPS_PROXY` 环境变量中读取。  
 *必需*：是  
 *默认值*：从 `HTTPS_PROXY` 环境变量读取。<a name="ref-cli-cmd-options-role-arn"></a>

 `--role-arn, -r <STRING>`   
CDK CLI 在与 AWS CloudFormation 交互时将代入的 IAM 角色的 ARN。  
 *必需*：否<a name="ref-cli-cmd-options-staging"></a>

 `--staging <BOOLEAN>`   
将资产复制到输出目录。  
指定 `false`，以防止将资产复制到输出目录。这允许 AWS SAM CLI 在执行本地调试时引用原始源文件。  
 *必需*：否  
 *默认值*：`true`<a name="ref-cli-cmd-options-strict"></a>

 `--strict <BOOLEAN>`   
不要构造包含警告的堆栈。  
 *必需*：否  
 *默认值*：`false`<a name="ref-cli-cmd-options-trace"></a>

 `--trace <BOOLEAN>`   
打印堆栈警告的跟踪。  
 *必需*：否  
 *默认值*：`false`<a name="ref-cli-cmd-options-verbose"></a>

 `--verbose, -v <COUNT>`   
显示调试日志。您可以多次指定该选项以增加详细程度。  
 *必需*：否<a name="ref-cli-cmd-options-version"></a>

 `--version <BOOLEAN>`   
显示 CDK CLI 版本号。  
 *必需*：否  
 *默认值*：`false`<a name="ref-cli-cmd-options-version-reporting"></a>

 `--version-reporting <BOOLEAN>`   
将 ` AWS::CDK::Metadata` 资源包含在合成的 AWS CloudFormation 模板中。  
 *必需*：否  
 *默认值*：`true`

## 提供和配置选项
<a name="ref-cli-cmd-configure"></a>

您可以通过命令行参数传递选项。对于大多数选项，您可以在 `cdk.json` 配置文件中对其进行配置。当您使用多个配置源时，CDK CLI 会遵循以下优先级：

1.  **命令行值**：命令行中提供的任何选项都会覆盖 `cdk.json` 文件中配置的选项。

1.  **项目配置文件**：CDK 项目目录中的 `cdk.json` 文件。

1.  **用户配置文件**：位于本地计算机 `~/.cdk.json` 中的 `cdk.json` 文件。

## 在命令行传递选项
<a name="ref-cli-cmd-pass"></a><a name="ref-cli-cmd-pass-bool"></a>

 **传递布尔值**   
对于接受布尔值的选项，通过以下方式进行指定：  
+ 使用 `true` 和 `false` 值：使用命令提供布尔值。以下是示例：

  ```
  $ cdk deploy --watch=true
  $ cdk deploy --watch=false
  ```
+ 提供选项的对应项：通过添加 `no` 来修改选项名称，以指定 `false` 值。以下是示例：

  ```
  $ cdk deploy --watch
  $ cdk deploy --no-watch
  ```
+ 对于默认为 `true` 或 `false` 的选项，除非要更改默认值，否则不必提供该选项。

# `cdk acknowledge`
<a name="ref-cli-cmd-ack"></a>

按问题编号确认通知，并将其隐藏，以免再次显示。

这有助于隐藏已处理或不适用于您的通知。

确认信息将保存在 CDK 项目级别。如果您在一个 CDK 项目中确认了某条通知，其仍会显示在其他项目中，直到在其他项目中得到确认。

## 使用量
<a name="ref-cli-cmd-ack-usage"></a>

```
$ cdk acknowledge <arguments> <options>
```

## 参数
<a name="ref-cli-cmd-ack-args"></a><a name="ref-cli-cmd-ack-args-notice-id"></a>

 **通知 ID**   
通知的 ID。  
 *类型*：字符串  
 *必需*：否

## 选项
<a name="ref-cli-cmd-ack-options"></a>

有关适用于所有 CDK CLI 命令的全局选项的列表，请参阅[全局选项](ref-cli-cmd.md#ref-cli-cmd-options)。<a name="ref-cli-cmd-ack-options-help"></a>

 `--help, -h <BOOLEAN>`   
显示 `cdk acknowledge` 命令的命令参考信息。

## 示例
<a name="ref-cli-cmd-ack-examples"></a>

### 确认并隐藏运行另一个 CDK CLI 命令时显示的通知
<a name="ref-cli-cmd-ack-examples-1"></a>

```
$ cdk deploy
... # Normal output of the command

NOTICES

16603   Toggling off auto_delete_objects for Bucket empties the bucket

        Overview: If a stack is deployed with an S3 bucket with
                  auto_delete_objects=True, and then re-deployed with
                  auto_delete_objects=False, all the objects in the bucket
                  will be deleted.

        Affected versions: <1.126.0.

        More information at: https://github.com/aws/aws-cdk/issues/16603


17061   Error when building EKS cluster with monocdk import

        Overview: When using monocdk/aws-eks to build a stack containing
                  an EKS cluster, error is thrown about missing
                  lambda-layer-node-proxy-agent/layer/package.json.

        Affected versions: >=1.126.0 <=1.130.0.

        More information at: https://github.com/aws/aws-cdk/issues/17061

$ cdk acknowledge 16603
```

# `cdk bootstrap`
<a name="ref-cli-cmd-bootstrap"></a>

将名为 `CDKToolkit` 的 CDK 引导堆栈部署到 AWS 环境中，从而为 CDK 部署准备 AWS 环境。

引导堆栈是一个 CloudFormation 堆栈，用于在 AWS 环境中预置 Amazon S3 存储桶和 Amazon ECR 存储库。在部署期间，AWS CDK CLI 使用这些资源来存储合成的模板和相关资产。

## 使用量
<a name="ref-cli-cmd-bootstrap-usage"></a>

```
$ cdk bootstrap <arguments> <options>
```

## 参数
<a name="ref-cli-cmd-bootstrap-args"></a><a name="ref-cli-cmd-bootstrap-args-env"></a>

 **AWS 环境**   
将引导堆栈部署到的目标 AWS 环境，格式如下：`aws://<account-id>/<region>`。  
示例：`aws://123456789012/us-east-1`  
可以在单个命令中多次提供此参数，以便将引导堆栈部署到多个环境中。  
默认情况下，CDK CLI 将引导 CDK 应用程序中引用的所有环境，或者根据默认源来确定环境。这可以是使用 `--profile` 选项从环境变量指定的环境，也可以是默认 AWS CLI 源指定的环境。

## 选项
<a name="ref-cli-cmd-bootstrap-options"></a>

有关适用于所有 CDK CLI 命令的全局选项的列表，请参阅[全局选项](ref-cli-cmd.md#ref-cli-cmd-options)。<a name="ref-cli-cmd-bootstrap-options-bootstrap-bucket-name"></a>

 `--bootstrap-bucket-name, --toolkit-bucket-name, -b <STRING>`   
CDK CLI 将使用的 Amazon S3 存储桶的名称。将创建此存储桶，且当前一定不存在此存储桶。  
提供此选项可覆盖 Amazon S3 存储桶的默认名称。  
使用此选项时，可能需要自定义合成。要了解更多信息，请参阅[自定义 CDK 堆栈合成](configure-synth.md#bootstrapping-custom-synth)。  
 *默认值*：未定义<a name="ref-cli-cmd-bootstrap-options-bootstrap-customer-key"></a>

 `--bootstrap-customer-key <BOOLEAN>`   
为引导存储桶创建客户主密钥（CMK）（您需要付费，但可以自定义权限，仅限现代引导）。  
此选项与 `--bootstrap-kms-key-id` 不兼容。  
 *默认值*：未定义<a name="ref-cli-cmd-bootstrap-options-bootstrap-kms-key-id"></a>

 `--bootstrap-kms-key-id <STRING>`   
用于 `SSE-KMS` 加密的 AWS KMS 主密钥 ID。  
提供此选项可覆盖用于加密 Amazon S3 存储桶的默认 AWS KMS 密钥。  
此选项与 `--bootstrap-customer-key` 不兼容。  
 *默认值*：未定义<a name="ref-cli-cmd-bootstrap-options-cloudformation-execution-policies"></a>

 `--cloudformation-execution-policies <ARRAY>`   
在部署堆栈期间，应附加到 AWS CloudFormation 所担任的部署角色的托管 IAM 策略 ARN。  
默认情况下，使用 `AdministratorAccess` 策略以完整管理员权限来部署堆栈。  
您可以在单个命令中多次提供此选项。您还可以将多个 ARN 作为单个字符串提供，各个 ARN 之间用逗号分隔。以下是示例：  

```
$ cdk bootstrap --cloudformation-execution-policies "arn:aws:iam::aws:policy/AWSLambda_FullAccess,arn:aws:iam::aws:policy/AWSCodeDeployFullAccess"
```
为避免部署失败，请确保您指定的策略足以满足将在引导的环境中执行的任何部署。  
此选项仅适用于现代引导。  
现代引导模板可以有效地向 `--trust` 列表中的任何 AWS 账户授予 `--cloudformation-execution-policies` 隐含的权限。默认情况下，这会扩展对引导账户中任何资源的读取和写入权限。请务必使用您熟悉的策略和可信账户来[配置引导堆栈](bootstrapping-customizing.md)。
 *默认值*：`[]`<a name="ref-cli-cmd-bootstrap-options-custom-permissions-boundary"></a>

 `--custom-permissions-boundary, -cpb <STRING>`   
指定要使用的权限边界的名称。  
此选项与 `--example-permissions-boundary` 不兼容。  
 *默认值*：未定义<a name="ref-cli-cmd-bootstrap-options-example-permissions-boundary"></a>

 `--example-permissions-boundary, -epb <BOOLEAN>`   
使用 AWS CDK 提供的示例权限边界。  
此选项与 `--custom-permissions-boundary` 不兼容。  
CDK 提供的权限边界策略应视为示例。如果您正在测试该功能，请编辑内容并参考示例策略。将其转换为实际部署的新策略（如果尚不存在）。需要关注的是避免出现偏差。最有可能的是，权限边界得以维护，并有专门的约定，其中包括命名。  
有关配置权限（包括使用权限边界）的更多信息，请参阅《[Security and Safety Dev Guide](https://github.com/aws/aws-cdk/wiki/Security-And-Safety-Dev-Guide)》。  
 *默认值*：未定义<a name="ref-cli-cmd-bootstrap-options-execute"></a>

 `--execute <BOOLEAN>`   
配置是否执行更改集。  
 *默认值*：`true`<a name="ref-cli-cmd-bootstrap-options-force"></a>

 `--force, -f <BOOLEAN>`   
应始终进行引导，即使会导致引导模板版本降级。  
 *默认值*：`false`<a name="ref-cli-cmd-bootstrap-options-help"></a>

 `--help, -h <BOOLEAN>`   
显示 `cdk bootstrap` 命令的命令参考信息。<a name="ref-cli-cmd-bootstrap-options-previous-parameters"></a>

 `--previous-parameters <BOOLEAN>`   
对现有参数使用以前的值。  
使用一组参数部署了引导模板后，必须将此选项设置为 `false`，才能在将来的部署中更改任何参数。当为 `false` 时，必须重新提供之前提供的所有参数。  
 *默认值*：`true`<a name="ref-cli-cmd-bootstrap-options-public-access-block-configuration"></a>

 `--public-access-block-configuration <BOOLEAN>`   
Amazon S3 存储桶上的屏蔽公共访问权限配置，由 CDK CLI 创建和使用。  
 *默认值*：`true`<a name="ref-cli-cmd-bootstrap-options-qualifier"></a>

 `--qualifier <STRING>`   
九位字符串值，对于每个引导堆栈都是唯一的。将添加此值到引导堆栈中资源的物理 ID 中。  
通过提供限定符，可以避免在同一环境中预置多个引导堆栈时资源名称冲突。  
更改限定符时，CDK 应用程序必须将更改后的值传递给堆栈合成器。有关更多信息，请参阅[自定义 CDK 堆栈合成](configure-synth.md#bootstrapping-custom-synth)。  
 *默认值*：`hnb659fds`。此值没有任何意义。<a name="ref-cli-cmd-bootstrap-options-show-template"></a>

 `--show-template <BOOLEAN>`   
不进行引导，而是将当前的引导模板打印到标准输出 (`stdout`)。然后，您就可以根据需要复制和自定义模板。  
 *默认值*：`false`<a name="ref-cli-cmd-bootstrap-options-tags"></a>

 `--tags, -t <ARRAY>`   
要添加到引导堆栈的标签，格式为 `KEY=VALUE`。  
 *默认值*：`[]`<a name="ref-cli-cmd-bootstrap-options-template"></a>

 `--template <STRING>`   
使用给定文件中的模板，而不是内置模板。<a name="ref-cli-cmd-bootstrap-options-termination-protection"></a>

 `--termination-protection <BOOLEAN>`   
在引导堆栈上切换 AWS CloudFormation 终止保护。  
当为 `true` 时，表示已启用终止保护。这可以防止意外删除引导堆栈。  
要了解有关终止保护的更多信息，请参阅《AWS CloudFormation 用户指南》**中的[防止堆栈被删除](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-protect-stacks.html)。  
 *默认值*：未定义<a name="ref-cli-cmd-bootstrap-options-toolkit-stack-name"></a>

 `--toolkit-stack-name <STRING>`   
要创建的引导堆栈的名称。  
默认情况下，`cdk bootstrap` 会将名为 `CDKToolkit` 的堆栈部署到指定的 AWS 环境中。使用此选项可为引导堆栈提供不同的名称。  
CDK CLI 使用此值来验证引导堆栈版本。  
 *默认值*：`CDKToolkit`  
 *必需*：是<a name="ref-cli-cmd-bootstrap-options-trust"></a>

 `--trust <ARRAY>`   
应信任的 AWS 账户 ID，以便在此环境中执行部署。  
执行引导的账户将始终受到信任。  
此选项还要求您提供 `--cloudformation-execution-policies`。  
您可以在单个命令中多次提供此选项。  
此选项仅适用于现代引导。  
要将可信账户添加到现有的引导程序堆栈，您必须指定所有要信任的账户，包括您之前提供的账户。如果您只提供新的可信账户，则之前的可信账户将被移除。  
以下是信任两个账户的示例：  

```
$ cdk bootstrap aws://123456789012/us-west-2 --trust 234567890123 --trust 987654321098 --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess
 ⏳  Bootstrapping environment aws://123456789012/us-west-2...
Trusted accounts for deployment: 234567890123, 987654321098
Trusted accounts for lookup: (none)
Execution policies: arn:aws:iam::aws:policy/AdministratorAccess
CDKToolkit: creating CloudFormation changeset...
 ✅  Environment aws://123456789012/us-west-2 bootstrapped.
```
现代引导模板可以有效地向 `--trust` 列表中的任何 AWS 账户授予 `--cloudformation-execution-policies` 隐含的权限。默认情况下，这会扩展对引导账户中任何资源的读取和写入权限。请务必使用您熟悉的策略和可信账户来[配置引导堆栈](bootstrapping-customizing.md)。
 *默认值*：`[]`<a name="ref-cli-cmd-bootstrap-options-trust-for-lookup"></a>

 `--trust-for-lookup <ARRAY>`   
应信任的 AWS 账户 ID，以便在此环境中查找值。  
使用此选项可以向账户授予合成堆栈的权限（这些堆栈将部署到环境中），而无需实际向其授予直接部署这些堆栈的权限。  
您可以在单个命令中多次提供此选项。  
此选项仅适用于现代引导。  
 *默认值*：`[]`

## 示例
<a name="ref-cli-cmd-bootstrap-examples"></a>

### 引导 prod 配置文件中指定的 AWS 环境
<a name="ref-cli-cmd-bootstrap-examples-1"></a>

```
$ cdk bootstrap --profile prod
```

### 将引导堆栈部署到环境 foo 和 bar
<a name="ref-cli-cmd-bootstrap-examples-2"></a>

```
$ cdk bootstrap --app='node bin/main.js' foo bar
```

### 导出引导模板以进行自定义
<a name="ref-cli-cmd-bootstrap-examples-3"></a>

如果引导模板无法满足您的特定要求，可以对其进行自定义以满足您的需求。

您可以使用 AWS CloudFormation 导出引导模板、对其进行修改并进行部署。以下是导出现有模板的示例：

```
$ cdk bootstrap --show-template > bootstrap-template.yaml
```

您也可以让 CDK CLI 使用自定义模板。以下是示例：

```
$ cdk bootstrap --template my-bootstrap-template.yaml
```

### 使用权限边界进行引导。然后删除该权限边界
<a name="ref-cli-cmd-bootstrap-examples-4"></a>

要使用自定义权限边界进行引导，我们运行以下命令：

```
$ cdk bootstrap --custom-permissions-boundary my-permissions-boundary
```

要删除权限边界，我们运行以下命令：

```
$ cdk bootstrap --no-previous-parameters
```

### 使用限定符来区分为开发环境创建的资源
<a name="ref-cli-cmd-bootstrap-examples-5"></a>

```
$ cdk bootstrap --qualifier dev2024
```

# `cdk context`
<a name="ref-cli-cmd-context"></a>

管理 AWS CDK 应用程序的缓存上下文值。

 *上下文*表示可以影响堆栈合成和部署方式的配置和环境信息。使用 `cdk context` 执行以下操作：
+ 查看已配置的上下文值。
+ 设置和管理上下文值。
+ 删除上下文值。

## 使用量
<a name="ref-cli-cmd-context-usage"></a>

```
$ cdk context <options>
```

## 选项
<a name="ref-cli-cmd-context-options"></a>

有关适用于所有 CDK CLI 命令的全局选项的列表，请参阅[全局选项](ref-cli-cmd.md#ref-cli-cmd-options)。<a name="ref-cli-cmd-context-options-clear"></a>

 `--clear <BOOLEAN>`   
清除所有上下文。<a name="ref-cli-cmd-context-options-force"></a>

 `--force, -f <BOOLEAN>`   
忽略密钥缺失错误。  
 *默认值*：`false`<a name="ref-cli-cmd-context-options-help"></a>

 `--help, -h <BOOLEAN>`   
显示 `cdk context` 命令的命令参考信息。<a name="ref-cli-cmd-context-options-reset"></a>

 `--reset, -e <STRING>`   
要重置的上下文键或其索引。

# `cdk deploy`
<a name="ref-cli-cmd-deploy"></a>

将一个或多个 AWS CDK 堆栈部署到您的 AWS 环境中。

在部署期间，CDK CLI 将输出进度指示器，类似于从 AWS CloudFormation 控制台中观察到的内容。

如果未引导 AWS 环境，则只有没有资产且合成模板小于 51200 字节的堆栈才能成功部署。

## 使用量
<a name="ref-cli-cmd-deploy-usage"></a>

```
$ cdk deploy <arguments> <options>
```

## 参数
<a name="ref-cli-cmd-deploy-args"></a><a name="ref-cli-cmd-deploy-args-stack-name"></a>

 **CDK 堆栈 ID**   
应用程序中要部署的 CDK 堆栈的构造 ID。  
 *类型*：字符串  
 *必需*：否

## 选项
<a name="ref-cli-cmd-deploy-options"></a>

有关适用于所有 CDK CLI 命令的全局选项的列表，请参阅[全局选项](ref-cli-cmd.md#ref-cli-cmd-options)。<a name="ref-cli-cmd-deploy-options-all"></a>

 `--all <BOOLEAN>`   
部署 CDK 应用程序中的所有堆栈。  
 *默认值*：`false`<a name="ref-cli-cmd-deploy-options-asset-parallelism"></a>

 `--asset-parallelism <BOOLEAN>`   
指定是否并行构建和发布资产。<a name="ref-cli-cmd-deploy-options-asset-prebuild"></a>

 `--asset-prebuild <BOOLEAN>`   
指定是否在部署第一个堆栈之前构建所有资产。此选项对于 Docker 构建失败很有用。  
 *默认值*：`true`<a name="ref-cli-cmd-deploy-options-build-exclude"></a>

 `--build-exclude, -E <ARRAY>`   
请勿使用给定 ID 重建资产。  
可以在单个命令中多次指定此选项。  
 *默认值*：`[]`<a name="ref-cli-cmd-deploy-options-change-set-name"></a>

 `--change-set-name <STRING>`   
要创建的 AWS CloudFormation 更改集的名称。  
此选项与 `--method='direct'` 不兼容。<a name="ref-cli-cmd-deploy-options-concurrency"></a>

 `--concurrency <NUMBER>`   
并行部署多个堆栈，同时考虑堆栈间的依赖项。使用此选项可以加快部署速度。您仍然必须将 AWS CloudFormation 和其他 AWS 速率限制考虑在内。  
提供一个数字来指定要执行的最大同时部署数（依赖项允许）。  
 *默认值*：`1`<a name="ref-cli-cmd-deploy-options-exclusively"></a>

 `--exclusively, -e <BOOLEAN>`   
仅部署请求的堆栈，不包括依赖项。<a name="ref-cli-cmd-deploy-options-force"></a>

 `--force, -f <BOOLEAN>`   
当您部署以更新现有堆栈时，CDK CLI 会将已部署堆栈的模板和标签与即将部署的堆栈进行比较。如果未检测到更改，则 CDK CLI 将跳过部署。  
要覆盖此行为并始终部署堆栈，即使未检测到任何更改，也请使用此选项。  
 *默认值*：`false`<a name="ref-cli-cmd-deploy-options-help"></a>

 `--help, -h <BOOLEAN>`   
显示 `cdk deploy` 命令的命令参考信息。<a name="ref-cli-cmd-deploy-options-hotswap"></a>

 `--hotswap <BOOLEAN>`   
热交换部署，用于加快开发速度。如果可能，此选项会尝试执行更快的热交换部署。例如，如果您在 CDK 应用程序中修改 Lambda 函数的代码，CDK CLI 将直接通过服务 API 更新资源，而不是执行 CloudFormation 部署来更新。  
如果 CDK CLI 检测到不支持热交换的更改，则将忽略这些更改并显示一条消息。如果您偏好执行完整的 CloudFormation 部署作为后备方案，请改用 `--hotswap-fallback`。  
CDK CLI 使用您当前的 AWS 凭证来执行 API 调用。即使 `@aws-cdk/core:newStyleStackSynthesis` 功能标志设置为 `true`，其也不会承担引导堆栈中的角色。如果不使用 CloudFormation，这些角色就没有直接更新 AWS 资源所需的权限。因此，请确保您的凭证与正在对其执行热交换部署的堆栈属于同一 AWS 账户，并且它们具有更新资源所必需的 IAM 权限。  
热交换目前支持以下更改：  
+ Lambda 函数的代码资产（包括 Docker 映像和内联代码）、标签更改和配置更改（仅支持描述和环境变量）。
+ Lambda 版本和别名更改。
+ AWS Step Functions 状态机的定义更改。
+ Amazon ECS 服务的容器资产更改。
+ Amazon S3 存储桶部署的网站资产更改。
+ AWS CodeBuild 项目的来源和环境更改。
+ AWS AppSync 解析器和函数的 VTL 映射模板更改。
+ AWS AppSync GraphQL API 的架构更改。
作为热交换部署的一部分，支持使用某些 CloudFormation 内置函数。这些指令包括：  
+  `Ref` 
+  `Fn::GetAtt`：仅部分支持。有关支持的资源和属性，请参阅[此实现](https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk/lib/api/evaluate-cloudformation-template.ts#L477-L492)。
+  `Fn::ImportValue` 
+  `Fn::Join` 
+  `Fn::Select` 
+  `Fn::Split` 
+  `Fn::Sub` 
此选项还与嵌套堆栈兼容。  
+ 此选项有意在 CloudFormation 堆栈中引入偏差，以加快部署速度。因此，仅将其用于开发目的。请勿将该选项用于生产部署。
+ 此选项被视为实验性质，将来可能会发生重大更改。
+ 某些参数的默认值可能与热交换参数不同。例如，Amazon ECS 服务的最低运行正常百分比目前将设置为 `0`。如果发生这种情况，请相应地检查来源。
 *默认值*：`false`<a name="ref-cli-cmd-deploy-options-hotswap-fallback"></a>

 `--hotswap-fallback <BOOLEAN>`   
此选项类似于 `--hotswap`。不同之处在于，如果检测到需要的更改，则 `--hotswap-fallback` 将回退以执行完整的 CloudFormation 部署。  
有关此选项的更多信息，请参阅 `--hotswap`。  
 *默认值*：`false`<a name="ref-cli-cmd-deploy-options-ignore-no-stacks"></a>

 `--ignore-no-stacks <BOOLEAN>`   
即使 CDK 应用程序不包含任何堆栈，也要执行部署。  
此选项在以下情况中很有用：应用程序可能具有多个环境，例如 `dev` 和 `prod`。开始开发时，您的 prod 应用程序可能没有任何资源，或者资源可能被注释掉。这将导致部署错误，并显示一条消息，指示该应用程序没有堆栈。使用 `--ignore-no-stacks` 来绕过此错误。  
 *默认值*：`false`<a name="ref-cli-cmd-deploy-options-import-existing-resources"></a>

 `--import-existing-resources <BOOLEAN>`   
从您的 AWS 账户导入现有非托管的 AWS CloudFormation 资源。  
当您使用此选项时，会将合成的 AWS CloudFormation 模板中与同一账户中现有非托管资源自定义名称相同的资源导入到您的堆栈中。  
您可以使用此选项将现有资源导入到新堆栈中，也可以导入到现有堆栈中。  
您可以在同一 `cdk deploy` 命令中导入现有资源并部署新资源。  
要了解有关自定义名称的更多信息，请参阅《AWS CloudFormation 用户指南》**中的[名称类型](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-name.html)。  
要了解有关 `ImportExistingResources` CloudFormation 参数的更多信息，请参阅 [AWS CloudFormation 通过为更改集使用新参数简化了资源导入](https://aws.amazon.com/about-aws/whats-new/2023/11/aws-cloudformation-import-parameter-changesets/)。  
有关使用此选项的更多信息，请参阅 *aws-cdk-cli GitHub 存储库*中的 [Import existing resources](https://github.com/aws/aws-cdk-cli/tree/main/packages/aws-cdk#import-existing-resources)。<a name="ref-cli-cmd-deploy-options-logs"></a>

 `--logs <BOOLEAN>`   
在标准输出 (`stdout`) 中显示选定堆栈中所有资源的所有事件的 Amazon CloudWatch 日志。  
此选项仅与 `--watch` 兼容。  
 *默认值*：`true`<a name="ref-cli-cmd-deploy-options-method"></a>

 `--method, -m <STRING>`   
配置执行部署的方法。  
+  `change-set`：默认方法。CDK CLI 会创建一个 CloudFormation 变更集，其中包含将要部署的更改，然后执行部署。
+  `direct`：不创建更改集。相反，立即应用更改。这通常比创建更改集更快，但 CLI 输出中会丢失部署进度详细信息。
+  `prepare-change-set`：创建更改集但不执行部署。如果您有检查更改集的外部工具，或者您有更改集的审批流程，则此方法会非常有用。
 *有效值*: `change-set`, `direct`, `prepare-change-set`   
 *默认值*：`change-set`<a name="ref-cli-cmd-deploy-options-notification-arns"></a>

 `--notification-arns <ARRAY>`   
Amazon SNS 主题的 ARN，CloudFormation 将通知堆栈相关事件。<a name="ref-cli-cmd-deploy-options-outputs-file"></a>

 `--outputs-file, -O <STRING>`   
部署中堆栈输出的写入路径。  
部署后，堆栈输出将以 JSON 格式写入指定的输出文件。  
您可以在项目的 `cdk.json` 文件中或本地开发计算机上的 `~/.cdk.json` 中配置此选项：  

```
{
   "app": "npx ts-node bin/myproject.ts",
   // ...
   "outputsFile": "outputs.json"
}
```
如果部署了多个堆栈，则输出将写入同一个输出文件，并按表示堆栈名称的键进行组织。<a name="ref-cli-cmd-deploy-options-parameters"></a>

 `--parameters <ARRAY>`   
在部署期间向 CloudFormation 传递其他参数。  
该选项接受以下格式的数组：`STACK:KEY=VALUE`。  
+  `STACK`：与参数关联的堆栈名称。
+  `KEY`：堆栈中的参数名称。
+  `VALUE`：部署时要传递的值。
如果未提供堆栈名称，或者如果提供 `*` 作为堆栈名称，则参数将应用于所有正在部署的堆栈。如果堆栈未使用该参数，则部署将失败。  
参数不会传播到嵌套堆栈。要将参数传递给嵌套堆栈，请使用 ` [NestedStack](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.NestedStack.html) ` 构造。  
 *默认值*：`{}`<a name="ref-cli-cmd-deploy-options-previous-parameters"></a>

 `--previous-parameters <BOOLEAN>`   
对现有参数使用以前的值。  
当此选项设置为 `false` 时，必须在每次部署中指定所有参数。  
 *默认值*：`true`<a name="ref-cli-cmd-deploy-options-progress"></a>

 `--progress <STRING>`   
配置 CDK CLI 显示部署进度的方式。  
+  `bar`：以进度条的形式显示堆栈部署事件，其中包含当前正在部署的资源的事件。
+  `events`：提供完整的历史记录，包括所有 CloudFormation 事件。
您也可以在项目的 `cdk.json` 文件中或本地开发计算机上的 `~/.cdk.json` 中配置此选项：  

```
{
   "progress": "events"
}
```
 *有效值*：`bar`、`events`  
 *默认值*：`bar`<a name="ref-cli-cmd-deploy-options-require-approval"></a>

 `--require-approval <STRING>`   
指定哪些安全敏感型更改需要手动批准。  
+  `any-change`：对堆栈进行任何更改都需要手动批准。
+  `broadening`：如果更改涉及扩大权限或安全组规则，则需要手动批准。
+  `never`：无需批准。
 *有效值*: `any-change`, `broadening`, `never`   
 *默认值*：`broadening`<a name="ref-cli-cmd-deploy-options-rollback"></a>

 `--rollback` \$1 `--no-rollback`, `-R`   
在部署期间，如果资源创建或更新失败，则部署将在 CDK CLI 返回之前回滚到最新的稳定状态。在此之前所做的所有更改都将被撤消。将删除已创建的资源，并且将回滚所做的更新。  
指定 `--no-rollback` 可以关闭这种行为。如果资源创建或更新失败，则 CDK CLI 将保留在此之前所做的更改并返回。这会导致部署处于失败、暂停状态。在这里，您可以更新代码并再次尝试部署。在快速迭代的开发环境中，这可能会有所帮助。  
如果使用 `--no-rollback` 执行的部署失败，并且您决定要回滚该部署，则可以使用 `cdk rollback` 命令。有关更多信息，请参阅 [cdk rollback](ref-cli-cmd-rollback.md)。  
使用 `--no-rollback`，引起资源替换的部署将始终失败。您只能将此选项值用于更新或创建新资源的部署。
 *默认值*：`--rollback`<a name="ref-cli-cmd-deploy-options-toolkit-stack-name"></a>

 `--toolkit-stack-name <STRING>`   
现有 CDK Toolkit 堆栈的名称。  
默认情况下，`cdk bootstrap` 会将名为 `CDKToolkit` 的堆栈部署到指定的 AWS 环境中。使用此选项可为引导堆栈提供不同的名称。  
CDK CLI 使用此值来验证引导堆栈版本。<a name="ref-cli-cmd-deploy-options-watch"></a>

 `--watch <BOOLEAN>`   
持续观察 CDK 项目文件，当在检测到更改时自动部署指定的堆栈。  
默认情况下，此选项为 `--hotswap`。  
此选项具有等效的 CDK CLI 命令。有关更多信息，请参阅 [cdk watch](ref-cli-cmd-watch.md)。

## 示例
<a name="ref-cli-cmd-deploy-examples"></a>

### 部署名为 MyStackName 的堆栈
<a name="ref-cli-cmd-deploy-examples-1"></a>

```
$ cdk deploy MyStackName --app='node bin/main.js'
```

### 在应用程序中部署多个堆栈
<a name="ref-cli-cmd-deploy-examples-2"></a>

使用 `cdk list` 列出您的堆栈：

```
$ cdk list
CdkHelloWorldStack
CdkStack2
CdkStack3
```

要部署所有堆栈，请使用 `--all` 选项：

```
$ cdk deploy --all
```

要选择部署哪些堆栈，请提供堆栈名称作为参数：

```
$ cdk deploy CdkHelloWorldStack CdkStack3
```

### 部署管线堆栈
<a name="ref-cli-cmd-deploy-examples-3"></a>

使用 `cdk list` 将堆栈名称显示为路径，显示它们在管线层次结构中的位置：

```
$ cdk list
PipelineStack
PiplelineStack/Prod
PipelineStack/Prod/MyService
```

使用 `--all` 选项或通配符 `*` 来部署所有堆栈。如果您有如上所述的堆栈层次结构，则 `--all` 和 `*` 将仅匹配顶层的堆栈。要匹配层次结构中的所有堆栈，请使用 `**`。

您可以将这些模式结合起来。以下示例部署了 `Prod` 阶段的所有堆栈：

```
$ cdk deploy PipelineStack/Prod/**
```

### 部署时传递参数
<a name="ref-cli-cmd-deploy-examples-4"></a>

在 CDK 堆栈中定义参数。以下是为 Amazon SNS 主题创建名为 `TopicNameParam` 的参数的示例：

```
new sns.Topic(this, 'TopicParameter', {
    topicName: new cdk.CfnParameter(this, 'TopicNameParam').value.toString()
});
```

要提供参数值 `parameterized`，请运行以下命令：

```
$ cdk deploy --parameters "MyStackName:TopicNameParam=parameterized"
```

您可以使用 `--force` 选项来覆盖参数值。以下是覆盖以前部署中主题名称的示例：

```
$ cdk deploy --parameters "MyStackName:TopicNameParam=parameterName" --force
```

### 部署后将堆栈输出写入文件
<a name="ref-cli-cmd-deploy-examples-5"></a>

在 CDK 堆栈文件中定义输出。以下是为函数 ARN 创建输出的示例：

```
const fn = new lambda.Function(this, "fn", {
  handler: "index.handler",
  code: lambda.Code.fromInline(`exports.handler = \${handler.toString()}`),
  runtime: lambda.Runtime.NODEJS_LATEST
});

new cdk.CfnOutput(this, 'FunctionArn', {
  value: fn.functionArn,
});
```

部署堆栈并将输出写入 `outputs.json`：

```
$ cdk deploy --outputs-file outputs.json
```

以下是部署后 `outputs.json` 的示例：

```
{
  "MyStack": {
    "FunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:MyStack-fn5FF616E3-G632ITHSP5HK"
  }
}
```

在此示例中，键 `FunctionArn` 对应于 `CfnOutput` 实例的逻辑 ID。

以下是部署多个堆栈时，部署后的 `outputs.json` 示例：

```
{
  "MyStack": {
    "FunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:MyStack-fn5FF616E3-G632ITHSP5HK"
  },
  "AnotherStack": {
    "VPCId": "vpc-z0mg270fee16693f"
  }
}
```

### 修改部署方法
<a name="ref-cli-cmd-deploy-examples-6"></a>

要在不使用更改集的情况下更快地部署，请使用 `--method='direct'`：

```
$ cdk deploy --method='direct'
```

要创建更改集但不进行部署，请使用 `--method='prepare-change-set'`。默认情况下，将创建一个名为 `cdk-deploy-change-set` 的更改集。如果先前存使用此名称的更改集，则将覆盖该更改集。如果未检测到任何更改，仍会创建一个空的更改集。

您也可以为更改集命名。以下是示例：

```
$ cdk deploy --method='prepare-change-set' --change-set-name='MyChangeSetName'
```

# `cdk destroy`
<a name="ref-cli-cmd-destroy"></a>

从您的 AWS 环境中删除一个或多个 AWS CDK 堆栈。

删除堆栈时，堆栈中的资源将被销毁，除非这些资源配置为 `Retain` 的 `DeletionPolicy`。

在堆栈删除期间，此命令将输出类似于 `cdk deploy` 行为的进度信息。

## 使用量
<a name="ref-cli-cmd-destroy-usage"></a>

```
$ cdk destroy <arguments> <options>
```

## 参数
<a name="ref-cli-cmd-destroy-args"></a><a name="ref-cli-cmd-destroy-args-stack-name"></a>

 **CDK 堆栈 ID**   
应用程序中要删除的 CDK 堆栈的构造 ID。  
 *类型*：字符串  
 *必需*：否

## 选项
<a name="ref-cli-cmd-destroy-options"></a>

有关适用于所有 CDK CLI 命令的全局选项的列表，请参阅[全局选项](ref-cli-cmd.md#ref-cli-cmd-options)。<a name="ref-cli-cmd-destroy-options-all"></a>

 `--all <BOOLEAN>`   
销毁所有可用的堆栈。  
 *默认值*：`false`<a name="ref-cli-cmd-destroy-options-exclusively"></a>

 `--exclusively, -e <BOOLEAN>`   
仅销毁请求的堆栈，不包括依赖项。<a name="ref-cli-cmd-destroy-options-force"></a>

 `--force, -f <BOOLEAN>`   
在销毁堆栈之前，请勿要求进行确认。<a name="ref-cli-cmd-destroy-options-help"></a>

 `--help, -h <BOOLEAN>`   
显示 `cdk destroy` 命令的命令参考信息。

## 示例
<a name="ref-cli-cmd-destroy-examples"></a>

### 删除名为 MyStackName 的堆栈
<a name="ref-cli-cmd-destroy-examples-1"></a>

```
$ cdk destroy --app='node bin/main.js' <MyStackName>
```

# `cdk diff`
<a name="ref-cli-cmd-diff"></a>

执行 diff 以查看 AWS CDK 堆栈之间的基础设施更改。

此命令通常用于比较本地 CDK 应用程序中堆栈的当前状态与已部署堆栈之间的差异。但是，您也可以将已部署的堆栈与任何本地 AWS CloudFormation 模板进行比较。

## 使用量
<a name="ref-cli-cmd-diff-usage"></a>

```
$ cdk diff <arguments> <options>
```

## 参数
<a name="ref-cli-cmd-diff-args"></a><a name="ref-cli-cmd-diff-args-stack-name"></a>

 **CDK 堆栈 ID**   
应用程序中执行 diff 的 CDK 堆栈的构造 ID。  
 *类型*：字符串  
 *必需*：否

## 选项
<a name="ref-cli-cmd-diff-options"></a>

有关适用于所有 CDK CLI 命令的全局选项的列表，请参阅[全局选项](ref-cli-cmd.md#ref-cli-cmd-options)。<a name="ref-cli-cmd-diff-options-change-set"></a>

 `--change-set <BOOLEAN>`   
指定是否创建更改集来分析资源替换。  
当为 `true` 时，CDK CLI 将创建一个 AWS CloudFormation 更改集，以显示将对堆栈所做的确切更改。此输出包括是否更新或替换资源。CDK CLI 使用部署角色而非查找角色来执行此操作。  
当为 `false` 时，通过比较 CloudFormation 模板来执行更快但不太准确的 diff。检测到的任何需要资源替换的属性更改都将显示为资源替换，即使纯粹是表面更改，例如用硬编码的 ARN 替换资源引用。  
 *默认值*：`true`<a name="ref-cli-cmd-diff-options-context-lines"></a>

 `--context-lines <NUMBER>`   
任意 JSON diff 渲染中包含的上下文行数。  
 *默认值*：`3`<a name="ref-cli-cmd-diff-options-exclusively"></a>

 `--exclusively, -e <BOOLEAN>`   
仅对请求的堆栈执行 diff，不包括依赖项。<a name="ref-cli-cmd-diff-options-fail"></a>

 `--fail <BOOLEAN>`   
如果检测到差异，则失败并退出，显示代码 `1`。<a name="ref-cli-cmd-diff-options-help"></a>

 `--help, -h <BOOLEAN>`   
显示 `cdk diff` 命令的命令参考信息。<a name="ref-cli-cmd-diff-options-processed"></a>

 `--processed <BOOLEAN>`   
指定是否与已处理 CloudFormation 转换的模板进行比较。  
 *默认值*：`false`<a name="ref-cli-cmd-diff-options-quiet"></a>

 `--quiet, -q <BOOLEAN>`   
当未检测到任何更改时，请勿将 CDK 堆栈名称和默认 `cdk diff` 消息打印到 `stdout`。  
 *默认值*：`false`<a name="ref-cli-cmd-diff-options-security-only"></a>

 `--security-only <BOOLEAN>`   
仅在安全更改范围扩大时才执行 diff。  
 *默认值*：`false`<a name="ref-cli-cmd-diff-options-strict"></a>

 `--strict <BOOLEAN>`   
修改 `cdk diff` 行为，使其更加精确或严格。当为 true 时，CDK CLI 将不会过滤掉 ` AWS::CDK::Metadata` 资源或不可读的非 ASCII 字符。  
 *默认值*：`false`<a name="ref-cli-cmd-diff-options-template"></a>

 `--template <STRING>`   
CloudFormation 模板路径，用于与 CDK 堆栈进行比较。

## 示例
<a name="ref-cli-cmd-diff-examples"></a>

### 对当前部署的名为 MyStackName 的堆栈执行 diff
<a name="ref-cli-cmd-diff-examples-1"></a>

CDK CLI 在 diff 输出中使用以下符号：
+  `[+]` – 标识在部署您的更改时将添加的代码或资源。
+  `[-]` – 标识在部署您的更改时将移除的代码或资源。
+  `[~]` – 标识在部署您的更改时将修改的资源或属性。

以下示例显示了 Lambda 函数的本地更改的 diff：

```
$ cdk diff MyStackName
start: Building <asset-hash>:<account:Region>
success: Built <asset-hash>:<account:Region>
start: Publishing <asset-hash>:<account:Region>
success: Published <asset-hash>:<account:Region>
Hold on while we create a read-only change set to get a diff with accurate replacement information (use --no-change-set to use a less accurate but faster template-only diff)
Stack MyStackName
Resources
[~] AWS::Lambda::Function HelloWorldFunction <resource-logical-ID>
 └─ [~] Code
     └─ [~] .ZipFile:
         ├─ [-]
        exports.handler = async function(event) {
          return {
            statusCode: 200,
            body: JSON.stringify('Hello World!'),
          };
        };

         └─ [+]
        exports.handler = async function(event) {
          return {
            statusCode: 200,
            body: JSON.stringify('Hello from CDK!'),
          };
        };



✨  Number of stacks with differences: 1
```

要修改的资源的 `[~]` 指示器并不总是意味着资源将被完全替换：
+ 某些资源属性（例如 `Code`）将更新资源。
+ 某些资源属性（例如 `FunctionName`）可能导致资源被完全替换。

### 对特定的 CloudFormation 模板执行 diff
<a name="ref-cli-cmd-diff-examples-2"></a>

```
$ cdk diff MyStackName --app='node bin/main.js' --template-path='./MyStackNameTemplate.yaml'
```

### 对本地堆栈及其已部署的堆栈执行 diff。如果未检测到任何更改，请勿打印到 stdout
<a name="ref-cli-cmd-diff-examples-3"></a>

```
$ cdk diff MyStackName --app='node bin/main.js' --quiet
```

# `cdk docs`
<a name="ref-cli-cmd-docs"></a>

在浏览器中打开 AWS CDK 文档。

## 使用量
<a name="ref-cli-cmd-docs-usage"></a>

```
$ cdk docs <options>
```

## 选项
<a name="ref-cli-cmd-docs-options"></a>

有关适用于所有 CDK CLI 命令的全局选项的列表，请参阅[全局选项](ref-cli-cmd.md#ref-cli-cmd-options)。<a name="ref-cli-cmd-docs-options-browser"></a>

 `--browser, -b <STRING>`   
用于打开浏览器的命令，使用 `%u` 作为要打开的文件路径的占位符。  
 *默认值*：`open %u`<a name="ref-cli-cmd-docs-options-help"></a>

 `--help, -h <BOOLEAN>`   
显示 `cdk docs` 命令的命令参考信息。

## 示例
<a name="ref-cli-cmd-docs-examples"></a>

### 在 Google Chrome 中打开 AWS CDK 文档
<a name="ref-cli-cmd-docs-examples-1"></a>

```
$ cdk docs --browser='chrome %u'
```

# `cdk doctor`
<a name="ref-cli-cmd-doctor"></a>

检查并显示有关您的本地 AWS CDK 项目和开发环境的有用信息。

这些信息有助于排除 CDK 问题，应在提交错误报告时提供这些信息。

## 使用量
<a name="ref-cli-cmd-doctor-usage"></a>

```
$ cdk doctor <options>
```

## 选项
<a name="ref-cli-cmd-doctor-options"></a>

有关适用于所有 CDK CLI 命令的全局选项的列表，请参阅[全局选项](ref-cli-cmd.md#ref-cli-cmd-options)。<a name="ref-cli-cmd-doctor-options-help"></a>

 `--help, -h <BOOLEAN>`   
显示 `cdk doctor` 命令的命令参考信息。

## 示例
<a name="ref-cli-cmd-doctor-examples"></a>

### `cdk doctor` 命令的简单示例
<a name="ref-cli-cmd-doctor-examples-1"></a>

```
$ cdk doctor
ℹ️ CDK Version: 1.0.0 (build e64993a)
ℹ️ AWS environment variables:
  - AWS_EC2_METADATA_DISABLED = 1
  - AWS_SDK_LOAD_CONFIG = 1
```

# `cdk drift`
<a name="ref-cli-cmd-drift"></a>

检测您使用 AWS 云开发工具包 (AWS CDK) 定义、管理和部署的资源的配置偏差。当堆栈的实际配置与其预期配置不同时，就会发生偏差，在 AWS CloudFormation 之外修改资源时会发生这种情况。

此命令通过将资源的当前状态与其预期配置进行比较来识别已修改的资源（例如，通过 AWS 管理控制台或 AWS CLI 修改的资源）。这些修改可能会导致您的基础设施出现意外行为。

在偏差检测期间，CDK CLI 将输出进度指示器和结果，显示以下内容：
+ 偏离预期配置的资源。
+ 出现偏差的资源总数。
+ 指示是否在堆栈中检测到偏差的摘要。

**重要**  
`cdk drift` 和 `cdk diff` 命令的工作方式不同：  
 `cdk drift` 调用 CloudFormation 的偏差检测操作，将 AWS 中资源的实际状态（“现实”）与其在 CloudFormation 中的预期配置进行比较。并非所有 AWS 资源都支持偏差检测。有关支持的资源列表，请参阅《AWS CloudFormation 用户指南》**中的[资源类型支持](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resource-import-supported-resources.html)。
 `cdk diff` 将从本地 CDK 代码合成的 CloudFormation 模板与已部署的 CloudFormation 堆栈的模板进行比较。
当您需要验证资源是否在 CloudFormation 之外（例如，通过 AWS 管理控制台或 AWS CLI）进行了修改时，请使用 `cdk drift`。当您想要在部署之前预览您的本地代码更改如何影响基础设施时，请使用 `cdk diff`。

## 使用量
<a name="ref-cli-cmd-drift-usage"></a>

```
$ cdk drift <arguments> <options>
```

## 参数
<a name="ref-cli-cmd-drift-args"></a><a name="ref-cli-cmd-drift-args-stack-name"></a>

 **堆栈名称**：  
要检查是否存在偏差的堆栈的名称。必须事先将该堆栈部署到 CloudFormation 才能执行偏差检测。  
 *类型*：字符串  
 *必需*：否  
如果没有指定任何堆栈，则会对您的 CDK 应用程序中定义的所有堆栈执行偏差检测。

## 选项
<a name="ref-cli-cmd-drift-options"></a>

有关适用于所有 CDK CLI 命令的全局选项的列表，请参阅[全局选项](ref-cli-cmd.md#ref-cli-cmd-options)。<a name="ref-cli-cmd-drift-options-fail"></a>

 `--fail <BOOLEAN>`   
如果检测到偏差，则返回退出代码 1。  
 *默认值*：`false`<a name="ref-cli-cmd-drift-options-help"></a>

 `--help, -h <BOOLEAN>`   
显示 `cdk drift` 命令的命令参考信息。

## 示例
<a name="ref-cli-cmd-drift-examples"></a>

### 检查特定堆栈的偏差
<a name="ref-cli-cmd-drift-examples-stack"></a>

```
$ cdk drift MyStackName
```

该命令将输出类似以下内容的结果：

```
Stack MyStackName
Modified Resources
[~] AWS::Lambda::Function MyFunction MyLambdaFunc1234ABCD
 └─ [~] /Description
     ├─ [-] My original hello world Lambda function
     └─ [+] My drifted hello world Lambda function

1 resource has drifted from their expected configuration

✨  Number of resources with drift: 1
```

### 检查删除资源后的偏差
<a name="ref-cli-cmd-drift-examples-deleted"></a>

以下示例显示了修改和删除资源后的输出：

```
Stack MyStackName
Modified Resources
[~] AWS::Lambda::Function MyFunction MyLambdaFunc1234ABCD
 └─ [~] /Description
     ├─ [-] My original hello world Lambda function
     └─ [+] My drifted hello world Lambda function
Deleted Resources
[-] AWS::CloudWatch::Alarm MyAlarm MyCWAlarmABCD1234

2 resources have drifted from their expected configuration

✨  Number of resources with drift: 2
```

### 使用退出代码检查偏差
<a name="ref-cli-cmd-drift-examples-fail"></a>

要让命令在检测到偏差时返回非零退出代码，请运行以下命令：

```
$ cdk drift MyStackName --fail
```

这在 CI/CD 管线中非常有用，可以自动检测和响应基础设施偏差。

# `cdk flags`
<a name="ref-cli-cmd-flags"></a>

查看和修改 CDK CLI 的功能标志配置。

功能标志控制 CDK CLI 的行为，您可以使用它们来启用或禁用特定功能。请使用 `cdk flags` 命令查看您当前的功能标志配置并根据需要对其进行修改。

**警告**  
正在为 AWS CDK 开发 `cdk flags` 命令。此命令的当前功能被视为生产就绪，可以安全使用。但是，此命令的范围和功能可能会发生变化。因此，您必须通过提供 `unstable=flags` 命令选择加入来使用此命令。

## 使用量
<a name="ref-cli-cmd-flags-usage"></a>

```
$ cdk flags <arguments> <options>
```

## 参数
<a name="ref-cli-cmd-flags-args"></a><a name="ref-cli-cmd-flags-args-flagname"></a>

 **FLAGNAME**   
您要查看或修改的特定功能标志的名称。  
 *类型*：字符串  
 *必需*：否

## 选项
<a name="ref-cli-cmd-flags-options"></a>

有关适用于所有 CDK CLI 命令的全局选项的列表，请参阅[全局选项](ref-cli-cmd.md#ref-cli-cmd-options)。<a name="ref-cli-cmd-flags-options-set"></a>

 `--set <BOOLEAN>`   
修改功能标志配置。<a name="ref-cli-cmd-flags-options-all"></a>

 `--all <BOOLEAN>`   
修改或查看所有功能标志。<a name="ref-cli-cmd-flags-options-recommended"></a>

 `--recommended <BOOLEAN>`   
将标志更改为推荐的状态。<a name="ref-cli-cmd-flags-options-default"></a>

 `--default <BOOLEAN>`   
将标志更改为默认状态。<a name="ref-cli-cmd-flags-options-unconfigured"></a>

 `--unconfigured <BOOLEAN>`   
修改未配置的功能标志。<a name="ref-cli-cmd-flags-options-value"></a>

 `--value <STRING>`   
要将功能标志配置设置为的值。  
 *requiresArg*：true<a name="ref-cli-cmd-flags-options-safe"></a>

 `--safe <BOOLEAN>`   
启用所有不会影响应用程序的功能标志。<a name="ref-cli-cmd-flags-options-interactive"></a>

 `--interactive, -i <BOOLEAN>`   
flags 命令的交互式选项。

## 示例
<a name="ref-cli-cmd-flags-examples"></a>

### 查看功能标志配置
<a name="ref-cli-cmd-flags-examples-1"></a>

运行 `cdk flags` 以查看与推荐状态不同的功能标志配置的报告。未配置的标志标有 `<unset>`，表示该标志当前没有值。标志会按以下顺序显示：
+ 将标记设置为与建议值不匹配的值
+ 尚未配置的标志

```
$ cdk flags --unstable=flags
Feature Flag                           Recommended                       User
* @aws-cdk/...                              true                         false
* @aws-cdk/...                              true                         false
* @aws-cdk/...                              true                         <unset>
```

您还可以运行 `cdk flags --all` 来按以下顺序查看所有功能标志的报告：
+ 将标记设置为与建议值匹配的值
+ 将标记设置为与建议值不匹配的值
+ 尚未配置的标志

```
$ cdk flags --unstable=flags --all
Feature Flag                              Recommended                     User
@aws-cdk/...                                true                         true
* @aws-cdk/...                              true                         false
* @aws-cdk/...                              true                         false
* @aws-cdk/...                              true                         <unset>
```

### 修改功能标志值
<a name="ref-cli-cmd-flags-examples-2"></a>

要以交互方式修改功能标志，请运行 `cdk flags --interactive`（或 `cdk flags -i`）查看菜单选项列表。

要将每个功能标志更改为建议值，请运行 `cdk flags --set --recommended --all`。此命令可使您的功能标志配置与最新的 CDK 功能标志配置保持同步。请注意，运行此命令可能会覆盖现有的配置值。

```
$ cdk flags --unstable=flags --set --recommended --all
Feature Flag                              Recommended Value            User Value
* @aws-cdk/...                              true                         false
* @aws-cdk/...                              true                         false
* @aws-cdk/...                              true                         <unset>
  Synthesizing...
    Resources
    [~] AWS::S3::Bucket MyBucket
    └─ [~] Properties
        └─ [~] Encryption
                ...
    Number of stacks with differences: 2
  Do you want to accept these changes? (y/n) y
  Resynthesizing...
```

如果您想要保留现有已配置标志的状态，请运行 `cdk flags --set --recommended --unconfigured`。此选项仅将未配置的功能标志更改为推荐值。

```
$ cdk flags --unstable=flags --set --recommended --unconfigured
Feature Flag                              Recommended Value            User Value
* @aws-cdk/...                              true                         <unset>
* @aws-cdk/...                              true                         <unset>
  Synthesizing...
    Resources
    [~] AWS::S3::Bucket MyBucket
    └─ [~] Properties
        └─ [~] Encryption
            ├─ [-] None
            └─ [+] ServerSideEncryptionConfiguration:
                    - ...
            ...
    Number of stacks with differences: 2
  Do you want to accept these changes? (y/n) y
  Resynthesizing...
```

如果想要确保任何未配置的功能标志不会干扰您的应用程序，请运行 `cdk flags --set --default --unconfigured` 命令来将未配置的标志更改为其默认值。例如，如果未配置 `@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021`，则在运行 `cdk synth` 后会显示一条通知。但是，如果将该标志设置为其默认状态 (false)，则将对其进行配置和关闭，而不会影响您的应用程序。

```
$ cdk flags --unstable=flags --set --default --unconfigured
Feature Flag                              Recommended Value            User Value
* @aws-cdk/...                              true                         <unset>
* @aws-cdk/...                              true                         <unset>
  Synthesizing...

  Do you want to accept these changes? (y/n) y
  Resynthesizing...
```

### 检查特定功能标志
<a name="ref-cli-cmd-flags-examples-3"></a>

#### 查看有关标志的更多信息
<a name="_view_more_information_about_a_flag"></a>

除了运行 `cdk flags` 和 `cdk flags --all` 查看功能标志配置之外，您还可以使用 `cdk flags "FLAGNAME"` 来检查特定功能标志，并了解该标志的作用。这在您想要了解某个特定标志及其对应用程序的影响时非常有用。

```
$ cdk flags --unstable=flags "@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021"
    Description: Enable this feature flag to have cloudfront distributions use the security policy TLSv1.2_2021 by default.
    Recommended Value: true
    User Value: true
```

#### 按子字符串筛选标志
<a name="_filter_flags_by_substring"></a>

您还可以运行 `cdk flags substring` 来查看所有匹配的功能标志。如果只有一个功能标志与该子字符串匹配，则会显示具体的详细信息。

```
$ cdk flags --unstable=flags ebs
@aws-cdk/aws-ec2:ebsDefaultGp3Volume
    Description: When enabled, the default volume type of the EBS volume will be GP3
    Recommended Value: true
    User Value: true
```

如果多个标志与子字符串匹配，则所有匹配标志都会显示在表格中。如果输入多个子字符串，则会返回包含其中任意一个子字符串的所有匹配标志。

```
$ cdk flags --unstable=flags s3 lambda
Feature Flag                              Recommended                     User
* @aws-cdk/s3...                            true                         false
* @aws-cdk/lambda...                        true                         false
* @aws-cdk/lambda...                        true                         <unset>
```

#### 修改特定标志
<a name="_modify_a_specific_flag"></a>

如果您需要修改某个标志的值，并希望确保将其设置为正确且受支持的状态，请运行 `cdk flags --set "FLAGNAME" --value="state"`。

```
$ cdk flags --unstable=flags --set "@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021" --value="true"
  Synthesizing...
    Resources
    [~] AWS::CloudFront::Distribution MyDistribution
    └─ [~] Properties
        └─ [~] DefaultSecurityPolicy
            ├─ [-] TLSv1.0
            └─ [+] TLSv1.2_2021
                    - ...
    Number of stacks with differences: 2
  Do you want to accept these changes? (y/n) y
  Resynthesizing...
```

# `cdk gc`
<a name="ref-cli-cmd-gc"></a>

使用 AWS 云开发工具包 (AWS CDK) 命令行界面 (CLI) `cdk gc` 命令对存储在引导堆栈资源中的未使用资产执行垃圾回收。使用此命令查看、管理和删除不再需要的资产。

对于 Amazon Simple Storage Service (Amazon S3) 资产，CDK CLI 会检查同一环境中现有的 AWS CloudFormation 模板，查看它们是否被引用。如果未被引用，则这些模板将被视为未使用，并符合垃圾回收条件。

**警告**  
正在为 AWS CDK 开发 `cdk gc` 命令。此命令的当前功能被视为生产就绪，可以安全使用。但是，此命令的范围和功能可能会发生变化。因此，您必须通过提供 `unstable=gc` 命令选择加入来使用此命令。

## 使用量
<a name="ref-cli-cmd-gc-usage"></a>

```
$ cdk gc <arguments> <options>
```

## 参数
<a name="ref-cli-cmd-gc-args"></a><a name="ref-cli-cmd-gc-args-env"></a>

 **AWS 环境**   
要对其执行垃圾回收操作的目标 AWS 环境。  
提供环境时，请使用以下格式：`aws://<account-id>/<region>`。例如 `aws://<123456789012>/<us-east-1>`。  
在单个命令中可以多次提供此参数，以便在多个环境中执行垃圾回收操作。  
默认情况下，CDK CLI 将对您在 CDK 应用程序中引用或作为参数提供的所有环境执行垃圾回收操作。如果您未提供环境，CDK CLI 将根据默认源确定环境。这些源包括您使用 `--profile` 选项、环境变量或默认 AWS CLI 源指定的环境。

## 选项
<a name="ref-cli-cmd-gc-options"></a>

有关适用于所有 CDK CLI 命令的全局选项的列表，请参阅[全局选项](ref-cli-cmd.md#ref-cli-cmd-options)。<a name="ref-cli-cmd-gc-options-action"></a>

 `--action <STRING>`   
垃圾回收期间 `cdk gc` 对您的资产执行的操作。  
+  `delete-tagged` – 删除所标记日期在您提供的缓冲天数范围内的资产，但不会标记新识别的未使用资产。
+  `full` – 执行所有垃圾回收操作。这包括删除您提供的缓冲天数范围内的资产，以及标记新识别的未使用资产。
+  `print` – 在命令提示符下输出未使用的资产数量，但不会对您的 AWS 环境进行任何实际更改。
+  `tag` – 标记任何新识别的未使用资产，但不会删除您提供的缓冲天数范围内的任何资产。
 *接受的值*：`delete-tagged`、`full`、`print`、`tag`  
 *默认值*：`full`<a name="ref-cli-cmd-gc-options-bootstrap-stack-name"></a>

 `--bootstrap-stack-name <STRING>`   
您的 AWS 环境中 CDK 引导堆栈的名称。如果您自定义了引导堆栈名称，请提供此选项。如果您使用的是默认 `CDKToolkit` 堆栈名称，则无需提供此选项。  
 *默认值*：`CDKToolkit`<a name="ref-cli-cmd-gc-options-confirm"></a>

 `--confirm <BOOLEAN>`   
指定 CDK CLI 在删除任何资产之前是否会请求您手动确认。  
指定 `false` 会自动删除资产而不提示您手动确认。  
 *默认值*：`true`<a name="ref-cli-cmd-gc-options-created-buffer-days"></a>

 `--created-buffer-days <NUMBER>`   
资产在符合垃圾回收操作条件之前必须存在的天数。  
当您提供一个数字时，在指定天数之外不存在的资产将从垃圾回收操作中筛选出来。  
 *默认值*：`1`<a name="ref-cli-cmd-gc-options-help"></a>

 `--help, -h <BOOLEAN>`   
显示 `cdk gc` 命令的命令参考信息。<a name="ref-cli-cmd-gc-options-rollback-buffer-days"></a>

 `--rollback-buffer-days <NUMBER>`   
资产在符合垃圾回收操作条件之前必须标记为隔离的天数。  
当您提供一个数字时，CDK CLI 会将未使用的资产标记为当前日期，而不是将其删除。CDK CLI 还会检查之前运行 `cdk gc` 命令时是否已标记任何资产。之前标记过的在您提供的缓冲天数范围内的资产将被删除。  
 *默认值*：`0`<a name="ref-cli-cmd-gc-options-type"></a>

 `--type <STRING>`   
引导堆栈中要执行垃圾回收操作的引导资源类型。  
+  `all` – 对引导的所有资源执行垃圾回收操作。
+  `ecr` – 对引导堆栈的 Amazon Elastic Container Registry (Amazon ECR) 存储库中的资产执行垃圾回收操作。
+  `s3` – 对引导堆栈的 Amazon S3 存储桶中的资产执行垃圾回收操作。
 *接受的值*：`all`、`ecr`、`s3`  
 *默认值*：`all`<a name="ref-cli-cmd-gc-options-unstable"></a>

 `--unstable <STRING>`   
允许使用仍在开发中的 CDK CLI 命令。  
要使用任何仍在开发中且可能发生变化的 CDK CLI 命令，需要此选项。  
可以在单个命令中多次提供此选项。  
要使用 `cdk gc`，请提供 `--unstable=gc`。

## 示例
<a name="ref-cli-cmd-gc-examples"></a>

### 基本示例
<a name="ref-cli-cmd-gc-examples-basic"></a>

以下示例提示您手动确认对引导堆栈的 Amazon S3 存储桶中的资产执行默认垃圾回收操作：

```
$ cdk gc --unstable=gc --type=s3

 ⏳  Garbage Collecting environment aws://<account-id>/<region>...
Found 99 assets to delete based off of the following criteria:
- assets have been isolated for > 0 days
- assets were created > 1 days ago

Delete this batch (yes/no/delete-all)?
```

以下示例对引导堆栈的 Amazon S3 存储桶中的一系列资产执行垃圾回收操作。此范围包括已被 `cdk gc` 标记超过 30 天且创建时间超过 10 天的资产。此命令会在删除任何资产之前提示手动确认：

```
$ cdk gc --unstable=gc --type=s3 --rollback-buffer-days=30 --created-buffer-days=10
```

以下示例执行的操作是删除引导堆栈的 Amazon S3 存储桶中之前已标记且超过 30 天未使用的资产：

```
$ cdk gc --unstable=gc --type=s3 --action=delete-tagged --rollback-buffer-days=30
```

# `cdk import`
<a name="ref-cli-cmd-import"></a>

使用 [AWS CloudFormation 资源导入](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resource-import.html)将现有 AWS 资源导入 CDK 堆栈。

使用此命令，您可以获取使用其他方法创建的现有资源，并开始使用 AWS CDK 管理这些资源。

在考虑将资源移动到 CDK 管理时，有时可以创建新资源，例如使用 IAM 角色、Lambda 函数和事件规则来创建。对于其他资源，例如 Amazon S3 存储桶和 DynamoDB 表等有状态资源，创建新资源可能会对您的服务产生影响。您可以使用 `cdk import` 导入现有资源，同时最大限度地减少对服务的干扰。有关支持的 AWS 资源列表，请参阅《AWS CloudFormation 用户指南》**中的[资源类型支持](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resource-import-supported-resources.html)。

 **将现有资源导入 CDK 堆栈**   

1. 运行 `cdk diff` 以确保 CDK 堆栈没有待处理的更改。执行 `cdk import` 时，导入操作中唯一允许的更改是添加正在导入的新资源。

1. 为要导入到堆栈的资源添加构造。例如，为 Amazon S3 存储桶添加以下内容：

   ```
   new s3.Bucket(this, 'ImportedS3Bucket', {});
   ```

   请勿添加任何其他更改。您还必须确保对资源当前具有状态进行准确建模。以存储桶为例，请务必包含 AWS KMS 密钥、生命周期策略以及与存储桶相关的任何其他内容。否则，后续更新操作可能无法达到您的预期。

1. 运行 `cdk import`。如果 CDK 应用程序中有多个堆栈，请传递一个特定的堆栈名称作为参数。

1. CDK CLI 将提示您传入正在导入的资源的实际名称。提供此信息后，将开始导入。

1. `cdk import` 报告成功后，该资源将由 CDK 管理。构造配置中的任何后续更改都将反映在资源上。

目前，此功能具有以下限制：
+ 无法将资源导入嵌套堆栈。
+ 不会检查您为导入的资源指定的属性是否正确和完整。导入后尝试启动偏差检测操作。
+ 依赖其他资源的资源必须按正确的顺序一起或单独导入。否则，CloudFormation 部署将因引用未解析而失败。
+ 此命令使用部署角色凭证，这是读取加密暂存存储桶所必需的。这需要版本 12 的引导模板，其中包括部署角色所必需的 IAM 权限。

## 使用量
<a name="ref-cli-cmd-import-usage"></a>

```
$ cdk import <arguments> <options>
```

## 参数
<a name="ref-cli-cmd-import-args"></a><a name="ref-cli-cmd-import-args-stack-name"></a>

 **CDK 堆栈 ID**   
应用程序中要向其中导入资源的 CDK 堆栈的构造 ID。可以在单个命令中多次提供此参数。  
 *类型*：字符串  
 *必需*：否

## 选项
<a name="ref-cli-cmd-import-options"></a>

有关适用于所有 CDK CLI 命令的全局选项的列表，请参阅[全局选项](ref-cli-cmd.md#ref-cli-cmd-options)。<a name="ref-cli-cmd-import-options-change-set-name"></a>

 `--change-set-name <STRING>`   
要创建的 CloudFormation 更改集的名称。<a name="ref-cli-cmd-import-options-execute"></a>

 `--execute <BOOLEAN>`   
指定是否执行更改集。  
 *默认值*：`true`<a name="ref-cli-cmd-import-options-force"></a>

 `--force, -f <BOOLEAN>`   
默认情况下，如果模板差异包含更新或删除，CDK CLI 将退出该进程。指定为 `true` 以覆盖此行为，并始终继续导入。<a name="ref-cli-cmd-import-options-help"></a>

 `--help, -h <BOOLEAN>`   
显示 `cdk import` 命令的命令参考信息。<a name="ref-cli-cmd-import-options-record-resource-mapping"></a>

 `--record-resource-mapping, -r <STRING>`   
使用此选项生成现有物理资源到将要导入的 CDK 资源的映射。该映射将写入您提供的文件路径。不会执行任何实际的导入操作。<a name="ref-cli-cmd-import-options-resource-mapping"></a>

 `--resource-mapping, -m <STRING>`   
使用此选项来指定用于定义资源映射的文件。CDK CLI 将使用此文件将物理资源映射到要导入的资源，而不是以交互方式询问您。  
此选项可以从脚本运行。<a name="ref-cli-cmd-import-options-rollback"></a>

 `--rollback <BOOLEAN>`   
失败时将堆栈回滚到稳定状态。  
要指定 `false`，您可以使用 `--no-rollback` 或 `-R`。  
指定 `false` 以更快地进行迭代。包含资源替换的部署将始终失败。  
 *默认值*：`true`<a name="ref-cli-cmd-import-options-toolkit-stack-name"></a>

 `--toolkit-stack-name <STRING>`   
要创建的 CDK Toolkit 堆栈的名称。  
默认情况下，`cdk bootstrap` 会将名为 `CDKToolkit` 的堆栈部署到指定的 AWS 环境中。使用此选项可为引导堆栈提供不同的名称。  
CDK CLI 使用此值来验证引导堆栈版本。

# `cdk init`
<a name="ref-cli-cmd-init"></a>

从模板中创建新的 AWS CDK 项目。

## 使用量
<a name="ref-cli-cmd-init-usage"></a>

```
$ cdk init <arguments> <options>
```

## 参数
<a name="ref-cli-cmd-init-args"></a><a name="ref-cli-cmd-init-args-template-type"></a>

 **模板类型**   
用于从中初始化新 CDK 项目的 CDK 模板类型。  
+  `app`：CDK 应用程序的模板。
+  `lib`：AWS 构造库的模板。
+  `sample-app`：CDK 应用程序示例，其中包含某些构造。
 *有效值*: `app`, `lib`, `sample-app` 

## 选项
<a name="ref-cli-cmd-init-options"></a>

有关适用于所有 CDK CLI 命令的全局选项的列表，请参阅[全局选项](ref-cli-cmd.md#ref-cli-cmd-options)。<a name="ref-cli-cmd-init-options-generate-only"></a>

 `--generate-only <BOOLEAN>`   
指定此选项可生成项目文件，而无需启动其他操作，例如设置 git 存储库、安装依赖项或编译项目。  
 *默认值*：`false`<a name="ref-cli-cmd-init-options-help"></a>

 `--help, -h <BOOLEAN>`   
显示 `cdk init` 命令的命令参考信息。<a name="ref-cli-cmd-init-options-language"></a>

 `--language, -l <STRING>`   
新项目将使用的语言。可以在项目的 `cdk.json` 配置文件中或本地开发计算机上的 `~/.cdk.json` 中配置此选项。  
 *有效值*：`csharp`、`fsharp`、`go`、`java`、`javascript`、`python`、`typescript`<a name="ref-cli-cmd-init-options-list"></a>

 `--list <BOOLEAN>`   
列出可用的模板类型和语言。

## 示例
<a name="ref-cli-cmd-init-examples"></a>

### 列出可用的模板类型和语言
<a name="ref-cli-cmd-init-examples-1"></a>

```
$ cdk init --list
Available templates:
* app: Template for a CDK Application
   └─ cdk init app --language=[csharp|fsharp|go|java|javascript|python|typescript]
* lib: Template for a CDK Construct Library
   └─ cdk init lib --language=typescript
* sample-app: Example CDK Application with some constructs
   └─ cdk init sample-app --language=[csharp|fsharp|go|java|javascript|python|typescript]
```

### 用 TypeScript 从库模板创建新的 CDK 应用程序
<a name="ref-cli-cmd-init-examples-2"></a>

```
$ cdk init lib --language=typescript
```

# `cdk list`
<a name="ref-cli-cmd-list"></a>

列出 CDK 应用程序中的所有 AWS CDK 堆栈及其依赖项。

## 使用量
<a name="ref-cli-cmd-list-usage"></a>

```
$ cdk list <arguments> <options>
```

## 参数
<a name="ref-cli-cmd-list-args"></a><a name="ref-cli-cmd-list-args-stack-name"></a>

 **CDK 堆栈 ID**   
应用程序中执行此命令的 CDK 堆栈的构造 ID。  
 *类型*：字符串  
 *必需*：否

## 选项
<a name="ref-cli-cmd-list-options"></a>

有关适用于所有 CDK CLI 命令的全局选项的列表，请参阅[全局选项](ref-cli-cmd.md#ref-cli-cmd-options)。<a name="ref-cli-cmd-list-options-help"></a>

 `--help, -h <BOOLEAN>`   
显示 `cdk list` 命令的命令参考信息。<a name="ref-cli-cmd-list-options-long"></a>

 `--long, -l <BOOLEAN>`   
显示每个堆栈的 AWS 环境信息。  
 *默认值*：`false`<a name="ref-cli-cmd-list-options-show-dependencies"></a>

 `--show-dependencies, -d <BOOLEAN>`   
显示每个堆栈的堆栈依赖项信息。  
 *默认值*：`false`

## 示例
<a name="ref-cli-cmd-list-examples"></a>

### 列出 CDK 应用程序“node bin/main.js”中的所有堆栈
<a name="ref-cli-cmd-list-examples-1"></a>

```
$ cdk list --app='node bin/main.js'
Foo
Bar
Baz
```

### 列出所有堆栈，包括每个堆栈的 AWS 环境详细信息
<a name="ref-cli-cmd-list-examples-"></a>

```
$ cdk list --app='node bin/main.js' --long
-
    name: Foo
    environment:
        name: 000000000000/bermuda-triangle-1
        account: '000000000000'
        region: bermuda-triangle-1
-
    name: Bar
    environment:
        name: 111111111111/bermuda-triangle-2
        account: '111111111111'
        region: bermuda-triangle-2
-
    name: Baz
    environment:
        name: 333333333333/bermuda-triangle-3
        account: '333333333333'
        region: bermuda-triangle-3
```

# `cdk metadata`
<a name="ref-cli-cmd-metadata"></a>

显示与 CDK 堆栈关联的元数据。

## 使用量
<a name="ref-cli-cmd-metadata-usage"></a>

```
$ cdk metadata <arguments> <options>
```

## 参数
<a name="ref-cli-cmd-metadata-args"></a><a name="ref-cli-cmd-metadata-args-stack-name"></a>

 **CDK 堆栈 ID**   
应用程序中显示元数据的 CDK 堆栈的构造 ID。  
 *类型*：字符串  
 *必需*：否

## 选项
<a name="ref-cli-cmd-metadata-options"></a>

有关适用于所有 CDK CLI 命令的全局选项的列表，请参阅[全局选项](ref-cli-cmd.md#ref-cli-cmd-options)。<a name="ref-cli-cmd-metadata-options-help"></a>

 `--help, -h <BOOLEAN>`   
显示 `cdk metadata` 命令的命令参考信息。

# `cdk migrate`
<a name="ref-cli-cdk-migrate"></a>

将已部署的 AWS 资源、AWS CloudFormation 堆栈和 CloudFormation 模板迁移到新的 AWS CDK 项目中。

此命令会创建一个新的 CDK 应用程序，其中包含单个堆栈，该堆栈以您使用 `--stack-name` 提供的值命名。您可以使用 `--from-scan`、`--from-stack` 或 `--from-path` 来配置迁移源。

有关使用 `cdk migrate` 的更多信息，请参阅[将现有资源和 AWS CloudFormation 模板迁移到 AWS CDK](migrate.md)。

**注意**  
`cdk migrate` 命令处于试验阶段，将来可能会发生重大更改。

## 使用量
<a name="ref-cli-cdk-migrate-usage"></a>

```
$ cdk migrate <options>
```

## 选项
<a name="ref-cli-cdk-migrate-options"></a>

有关适用于所有 CDK CLI 命令的全局选项的列表，请参阅[全局选项](ref-cli-cmd.md#ref-cli-cmd-options)。

### 必需选项
<a name="ref-cli-cdk-migrate-options-required"></a><a name="ref-cli-cdk-migrate-options-stack-name"></a>

 `--stack-name <STRING>`   
AWS CloudFormation 堆栈的名称，迁移后将在 CDK 应用程序中进行创建。  
 *必需*：是

### 条件选项
<a name="ref-cli-cdk-migrate-options-conditional"></a><a name="ref-cli-cdk-migrate-options-from-path"></a>

 `--from-path <PATH>`   
要迁移的 AWS CloudFormation 模板的路径。提供此选项可指定本地模板。  
 *必填*：条件性。如果从本地 AWS CloudFormation 模板迁移，则为必需项。<a name="ref-cli-cdk-migrate-options-from-scan"></a>

 `--from-scan <STRING>`   
从 AWS 环境迁移已部署的资源时，请使用此选项来指定是否应启动新的扫描，或 AWS CDK CLI 是否应使用上次成功的扫描。  
 *必填*：条件性。如果从已部署的 AWS 资源迁移，则为必需项。  
 *接受的值*：`most-recent`、`new`<a name="ref-cli-cdk-migrate-options-from-stack"></a>

 `--from-stack <BOOLEAN>`   
提供此选项可从已部署的 AWS CloudFormation 堆栈迁移。使用 `--stack-name` 来指定已部署的 AWS CloudFormation 堆栈名称。  
 *必填*：条件性。如果从已部署的 AWS CloudFormation 堆栈迁移，则为必需项。

### 可选选项
<a name="ref-cli-cdk-migrate-options-optional"></a><a name="ref-cli-cdk-migrate-options-account"></a>

 `--account <STRING>`   
要从中检索 AWS CloudFormation 堆栈模板的账户。  
 *必需*：否  
 *默认*：AWS CDK CLI 从默认源获取账户信息。<a name="ref-cli-cdk-migrate-options-compress"></a>

 `--compress <BOOLEAN>`   
提供此选项可将生成的 CDK 项目压缩成 `ZIP` 文件。  
 *必需*：否<a name="ref-cli-cdk-migrate-options-filter"></a>

 `--filter <ARRAY>`   
从 AWS 账户和 AWS 区域迁移已部署资源时使用。此选项指定筛选条件来确定要迁移哪些已部署的资源。  
此选项接受键值对数组，其中**键**表示筛选条件类型，**值**表示要筛选的值。  
以下是可接受的键：  
+  `resource-identifier`：资源的标识符。值可以是资源逻辑或物理 ID。例如 `resource-identifier="ClusterName"`。
+  `resource-type-prefix` – AWS CloudFormation 资源类型前缀。例如，指定 `resource-type-prefix="AWS::DynamoDB::"` 以筛选所有 Amazon DynamoDB 资源。
+  `tag-key`：资源标签的键。例如 `tag-key="myTagKey"`。
+  `tag-value`：资源标签的值。例如 `tag-value="myTagValue"`。
为 `AND` 条件逻辑提供多个键值对。以下示例筛选了使用 `myTagKey` 作为标签键的所有 DynamoDB 资源：`--filter resource-type-prefix="AWS::DynamoDB::", tag-key="myTagKey"`。  
在单个命令中多次提供 `--filter` 选项，用于 `OR` 条件逻辑。以下示例筛选了所有属于 DynamoDB 资源或使用 `myTagKey` 标记为标签键的资源：`--filter resource-type-prefix="AWS::DynamoDB::" --filter tag-key="myTagKey"`。  
 *必需*：否<a name="ref-cli-cdk-migrate-options-help"></a>

 `--help, -h <BOOLEAN>`   
显示 `cdk migrate` 命令的命令参考信息。<a name="ref-cli-cdk-migrate-options-language"></a>

 `--language <STRING>`   
迁移期间创建的 CDK 项目使用的编程语言。  
 *必需*：否  
 *有效值*：`typescript`、`python`、`java`、`csharp`、`go`。  
 *默认值*：`typescript`<a name="ref-cli-cdk-migrate-options-output-path"></a>

 `--output-path <PATH>`   
已迁移的 CDK 项目的输出路径。  
 *必需*：否  
 *默认*：默认情况下，AWS CDK CLI 将使用您当前的工作目录。<a name="ref-cli-cdk-migrate-options-region"></a>

 `--region <STRING>`   
要从中检索 AWS CloudFormation 堆栈模板的 AWS 区域。  
 *必需*：否  
 *默认*：AWS CDK CLI 从默认源获取 AWS 区域信息。

## 示例
<a name="ref-cli-cdk-migrate-examples"></a>

### 从 CloudFormation 堆栈迁移的简单示例
<a name="ref-cli-cdk-migrate-examples-1"></a>

使用 `--from-stack` 从特定 AWS 环境中已部署的 CloudFormation 堆栈迁移。提供 `--stack-name` 来命名新的 CDK 堆栈。以下是将 `myCloudFormationStack` 迁移到使用 TypeScript: 的新 CDK 应用程序的示例：

```
$ cdk migrate --language typescript --from-stack --stack-name 'myCloudFormationStack'
```

### 从本地 CloudFormation 模板迁移的简单示例
<a name="ref-cli-cdk-migrate-examples-2"></a>

使用 `--from-path` 从本地 JSON 或 YAML CloudFormation 模板迁移。提供 `--stack-name` 来命名新的 CDK 堆栈。以下是在 TypeScript 中创建新 CDK 应用程序的示例，其中包含来自本地 `template.json` 文件的 `myCloudFormationStack` 堆栈：

```
$ cdk migrate --stack-name "myCloudFormationStack" --language typescript --from-path "./template.json"
```

### 从已部署的 AWS 资源迁移的简单示例
<a name="ref-cli-cdk-migrate-examples-3"></a>

使用 `--from-scan` 从未与 CloudFormation 堆栈关联的特定 AWS 环境中迁移已部署的 AWS 资源。CDK CLI 利用 IaC generator 服务来扫描资源并生成模板。然后，CDK CLI 引用该模板来创建新的 CDK 应用程序。以下是在 TypeScript 中创建新 CDK 应用程序的示例，其中包含新 `myCloudFormationStack` 堆栈，包含已迁移的 AWS 资源：

```
$ cdk migrate --language typescript --from-scan --stack-name "myCloudFormationStack"
```

# `cdk notices`
<a name="ref-cli-cmd-notices"></a>

显示您 CDK 应用程序的通知。

通知可能包括有关安全漏洞、回归和使用不支持版本的重要消息。

无论相关通知是否已确认，此命令都会显示这些通知。默认情况下，每个命令之后也可能出现相关通知。

您可以使用以下方式隐藏通知：
+ 通过命令选项。以下是示例：

  ```
  $ cdk deploy --no-notices
  ```
+ 通过项目 `cdk.json` 文件中的上下文无限期地隐藏所有通知：

  ```
  {
    "notices": false,
    "context": {
      // ...
    }
  }
  ```
+ 使用 `cdk acknowledge` 命令确认每条通知。

## 使用量
<a name="ref-cli-cmd-notices-usage"></a>

```
$ cdk notices <options>
```

## 选项
<a name="ref-cli-cmd-notices-options"></a>

有关适用于所有 CDK CLI 命令的全局选项的列表，请参阅[全局选项](ref-cli-cmd.md#ref-cli-cmd-options)。<a name="ref-cli-cmd-notices-options-help"></a>

 `--help, -h <BOOLEAN>`   
显示 `cdk notices` 命令的命令参考信息。

## 示例
<a name="ref-cli-cmd-notices-examples"></a>

### 运行 cdk deploy 命令后显示的默认通知示例
<a name="ref-cli-cmd-notices-examples-1"></a>

```
$ cdk deploy

... # Normal output of the command

NOTICES

16603   Toggling off auto_delete_objects for Bucket empties the bucket

        Overview: If a stack is deployed with an S3 bucket with
                  auto_delete_objects=True, and then re-deployed with
                  auto_delete_objects=False, all the objects in the bucket
                  will be deleted.

        Affected versions: <1.126.0.

        More information at: https://github.com/aws/aws-cdk/issues/16603


17061   Error when building EKS cluster with monocdk import

        Overview: When using monocdk/aws-eks to build a stack containing
                  an EKS cluster, error is thrown about missing
                  lambda-layer-node-proxy-agent/layer/package.json.

        Affected versions: >=1.126.0 <=1.130.0.

        More information at: https://github.com/aws/aws-cdk/issues/17061


If you don’t want to see an notice anymore, use "cdk acknowledge ID". For example, "cdk acknowledge 16603"
```

### 运行 cdk notices 命令的简单示例
<a name="ref-cli-cmd-notices-examples-2"></a>

```
$ cdk notices

NOTICES

16603   Toggling off auto_delete_objects for Bucket empties the bucket

        Overview: if a stack is deployed with an S3 bucket with
                  auto_delete_objects=True, and then re-deployed with
                  auto_delete_objects=False, all the objects in the bucket
                  will be deleted.

        Affected versions: framework: <=2.15.0 >=2.10.0

        More information at: https://github.com/aws/aws-cdk/issues/16603


If you don’t want to see a notice anymore, use "cdk acknowledge <id>". For example, "cdk acknowledge 16603"
```

# `cdk refactor`
<a name="ref-cli-cmd-refactor"></a>

**重要**  
`cdk refactor` 命令目前为预览版，可能会发生变化。  
使用此命令时必须提供 `--unstable=refactor` 选项。

在 AWS 云开发工具包 (AWS CDK) 应用程序中重构代码时，请保留已部署的资源。

当您在 CDK 代码中重命名构造或将其跨堆栈移动时，CloudFormation 通常会将这些构造视为新资源，导致可能引起服务中断或数据丢失的替换。`cdk refactor` 命令会智能地检测这些更改，并与 CloudFormation 的重构 API 配合使用，以便在更新资源的逻辑 ID 时保留资源。

通过使用 `cdk refactor`，您可以：
+ 重命名构造以提高代码库的清晰度，而不会导致资源替换。
+ 在堆栈之间移动资源，以改善问题的组织和分离。
+ 重组构造层次结构（例如，将 AWS 资源分组到新的 L3 构造下），同时保留底层云资源。
+ 安全地升级或切换构造库（包括第三方依赖项），而不会在版本之间的逻辑 ID 更改时触发资源替换。

此命令会分析您的更改，向您显示将更改位置的资源列表（堆栈和逻辑 ID），并处理更新 CloudFormation 资源的复杂过程，同时保持其身份和状态。

运行该命令时，它会将当前代码与已部署状态进行比较，从而自动计算映射。它验证您的 CDK 应用程序是否包含与已部署状态完全相同的资源集，只是它们在构造树中的位置不同。如果该命令检测到任何资源添加、删除或修改，重构操作将被拒绝并显示错误消息。

映射计算完成后，该命令会显示建议的更改，并在用户确认后应用重构。如果检测到歧义（存在多个有效映射），您可以提供一个包含显式映射的覆盖文件来解决这些情况。

有关介绍，请参阅[重构 CDK 代码时保留已部署的资源](refactor.md)。

## 使用量
<a name="ref-cli-cmd-refactor-usage"></a>

```
$ cdk refactor <arguments> <options>
```

## 参数
<a name="ref-cli-cmd-refactor-args"></a><a name="ref-cli-cmd-refactor-args-stack-id"></a>

 **CDK 堆栈 ID**   
应用中要重构的 CDK 堆栈的构造 ID。  
您可以指定多个堆栈 ID，以便将重构操作集中在这些堆栈上。如果资源在堆栈之间移动，并且其中一个堆栈没有明确包含，则重构命令会自动在操作中包含额外的堆栈。  
如果您不提供任何堆栈 ID，则将考虑对应用程序中的所有堆栈进行重构。  
 *类型*：字符串  
 *必需*：否

## 选项
<a name="ref-cli-cmd-refactor-options"></a>

有关适用于所有 CDK CLI 命令的全局选项的列表，请参阅[全局选项](ref-cli-cmd.md#ref-cli-cmd-options)。<a name="ref-cli-cmd-refactor-options-dry-run"></a>

 `--dry-run`   
将映射打印到控制台，但不应用该映射。  
此选项对于在实际执行重构之前验证更改非常有用，尤其是在使用复杂的应用程序时。它会在不修改任何资源的情况下，准确地显示将要进行的更改。<a name="ref-cli-cmd-refactor-options-force"></a>

 `--force`   
继续进行重构，但在不提示用户确认。  
在交互式环境中，如果您对更改充满信心，这非常有用。在 CI/CD 管线等非交互式环境中，CDK CLI 会在不提示的情况下自动继续运行，因此不需要此选项。<a name="ref-cli-cmd-refactor-options-help"></a>

 `--help, -h <BOOLEAN>`   
显示 `cdk refactor` 命令的命令参考信息。<a name="ref-cli-cmd-refactor-options-override-file"></a>

 `--override-file <FILE>`   
当 CDK CLI 无法确定资源的重构解析时，提供替换。此文件包含 JSON 格式的资源映射。以下是示例：  

```
{
    "environments": [
        {
            "account": "123456789012",
            "region": "us-east-2",
            "resources": {
                "StackA.OldName": "StackB.NewName",
                "StackC.Foo": "StackC.Bar"
            }
        }
    ]
}
```<a name="ref-cli-cmd-refactor-options-revert"></a>

 `--revert <FILE>`   
恢复以前的重构。您必须提供包含资源映射的覆盖文件。  
这不会完全撤消以前的重构操作。要完全恢复重构，您需要将应用程序回滚到以前的状态，然后再次运行重构过程。

# `cdk rollback`
<a name="ref-cli-cmd-rollback"></a>

使用 AWS 云开发工具包 (AWS CDK) 命令行界面 (CLI) `cdk rollback` 命令将失败或暂停的堆栈从 AWS CloudFormation 部署回滚到其最后的稳定状态。

**注意**  
要使用此命令，环境中必须部署了 v23 引导模板。有关更多信息，请参阅[引导模板版本历史记录](bootstrapping-env.md#bootstrap-template-history)。

使用 `cdk deploy` 部署时，默认情况下，CDK CLI 将回滚失败的部署。如果使用 `cdk deploy` 来指定 `--no-rollback`，则可以使用 `cdk rollback` 命令手动回滚失败的部署。这将启动回滚到堆栈的最后稳定状态。

## 使用量
<a name="ref-cli-cmd-rollback-usage"></a>

```
$ cdk rollback <arguments> <options>
```

## 参数
<a name="ref-cli-cmd-rollback-args"></a><a name="ref-cli-cmd-rollback-args-stack-name"></a>

 **CDK 堆栈 ID**   
应用程序中要回滚的 CDK 堆栈的构造 ID。  
 *类型*：字符串  
 *必需*：否

## 选项
<a name="ref-cli-cmd-rollback-options"></a>

有关适用于所有 CDK CLI 命令的全局选项的列表，请参阅[全局选项](ref-cli-cmd.md#ref-cli-cmd-options)。<a name="ref-cli-cmd-rollback-options-all"></a>

 `--all <BOOLEAN>`   
回滚 CDK 应用程序中的所有堆栈。  
 *默认值*：`false`<a name="ref-cli-cmd-rollback-options-force"></a>

 `--force, -f <BOOLEAN>`   
使用 `cdk rollback` 时，某些资源可能无法回滚。提供此选项可强制回滚所有资源。这与为堆栈中的每个资源提供 `--orphan` 选项的行为相同。  
 *默认值*：`false`<a name="ref-cli-cmd-rollback-options-help"></a>

 `--help, -h <BOOLEAN>`   
显示 `cdk rollback` 命令的命令参考信息。<a name="ref-cli-cmd-rollback-options-orphan"></a>

 `--orphan <LogicalId>`   
使用 `cdk rollback` 时，某些资源可能无法回滚。发生这种情况时，您可以使用此选项并提供回滚失败的资源的逻辑 ID 来尝试强制回滚资源。  
可以在单个命令中多次提供此选项。以下是示例：  

```
$ cdk rollback MyStack --orphan MyLambdaFunction --orphan MyLambdaFunction2
```
要强制回滚所有资源，请改用 `--force` 选项。<a name="ref-cli-cmd-rollback-options-toolkit-stack-name"></a>

 `--toolkit-stack-name <STRING>`   
用于引导环境的现有 CDK Toolkit 堆栈的名称。  
默认情况下，`cdk bootstrap` 会将名为 `CDKToolkit` 的堆栈部署到指定的 AWS 环境中。使用此选项可为引导堆栈提供不同的名称。  
CDK CLI 使用此值来验证引导堆栈版本。<a name="ref-cli-cmd-rollback-options-validate-bootstrap-version"></a>

 `--validate-bootstrap-version <BOOLEAN>`   
指定是否验证引导堆栈版本。提供 `--validate-bootstrap-version=false` 或 `--no-validate-bootsrap-version` 来关闭这种行为。  
 *默认值*：`true`

# `cdk synthesize`
<a name="ref-cli-cmd-synth"></a>

合成 CDK 应用程序以生成云程序集，包括每个堆栈的 AWS CloudFormation 模板。

云程序集是包含将应用程序部署到 AWS 环境所需的所有内容的文件。例如，它包括应用程序中每个堆栈的 CloudFormation 模板，以及在应用程序中引用的文件资产或 Docker 映像的副本。

如果您的应用程序包含单个堆栈或提供单个堆栈作为参数，则 CloudFormation 模板也将以 YAML 格式显示在标准输出 (`stdout`) 中。

如果您的应用程序包含多个堆栈，则 `cdk synth` 会将云程序集合成为 `cdk.out`。

## 使用量
<a name="ref-cli-cmd-synth-usage"></a>

```
cdk synthesize <arguments> <options>
```

## 参数
<a name="ref-cli-cmd-synth-args"></a><a name="ref-cli-cmd-synth-args-stack-name"></a>

 **CDK 堆栈 ID**   
应用中要合成的 CDK 堆栈的构造 ID。  
 *类型*：字符串  
 *必需*：否

## 选项
<a name="ref-cli-cmd-synth-options"></a>

有关适用于所有 CDK CLI 命令的全局选项的列表，请参阅[全局选项](ref-cli-cmd.md#ref-cli-cmd-options)。<a name="ref-cli-cmd-synth-options-exclusively"></a>

 `--exclusively, -e <BOOLEAN>`   
仅合成请求的堆栈，不包括依赖项。<a name="ref-cli-cmd-synth-options-help"></a>

 `--help, -h <BOOLEAN>`   
显示 `cdk synthesize` 命令的命令参考信息。<a name="ref-cli-cmd-synth-options-quiet"></a>

 `--quiet, -q <BOOLEAN>`   
请勿将 CloudFormation 模板输出到 `stdout`。  
可以在 CDK 项目的 `cdk.json` 文件中配置此选项。以下是示例：  

```
{
   "quiet": true
}
```
 *默认值*：`false`<a name="ref-cli-cmd-synth-options-validation"></a>

 `--validation <BOOLEAN>`   
通过执行其他检查来验证合成后生成的 CloudFormation 模板。  
您也可以通过 `validateOnSynth` 属性或 `CDK_VALIDATION` 环境变量来配置此选项。  
 *默认值*：`true`

## 示例
<a name="ref-cli-cmd-synth-examples"></a>

### 合成逻辑 ID 为 MyStackName 的 CDK 堆栈的云程序集，然后将 CloudFormation 模板输出到 stdout
<a name="ref-cli-cmd-synth-examples-1"></a>

```
$ cdk synth MyStackName
```

### 合成 CDK 应用程序中的所有堆栈的云程序集，并将其保存到 cdk.out
<a name="ref-cli-cmd-synth-examples-2"></a>

```
$ cdk synth
```

### 合成 MyStackName 的云程序集，但不包括依赖项
<a name="ref-cli-cmd-synth-examples-3"></a>

```
$ cdk synth MyStackName --exclusively
```

### 合成 MyStackName 的云程序集，但请勿将 CloudFormation 模板输出到 stdout
<a name="ref-cli-cmd-synth-examples-4"></a>

```
$ cdk synth MyStackName --quiet
```

# `cdk watch`
<a name="ref-cli-cmd-watch"></a>

持续关注本地 AWS CDK 项目是否有更改以执行部署和热交换。

此命令与 `cdk deploy` 类似，不同之处在于其可以通过单个命令执行连续部署和热交换。

此命令是 `cdk deploy --watch` 的快捷方式。

要结束 `cdk watch` 会话，请按下 `Ctrl+C` 中断进程。

观察到的文件由 `cdk.json` 文件中的 `"watch"` 设置决定。其有两个子键，`"include"` 和 `"exclude"`，接受单个字符串或字符串数组。每个条目都被解释为相对于 `cdk.json` 文件位置的路径。`*` 和 `**` 均可接受。

如果您使用 `cdk init` 命令创建项目，则会在项目的 `cdk.json` 文件 中为 `cdk watch` 配置以下默认行为：
+  `"include"` 设置为 `"**/*"`，其中包括项目根目录中的所有文件和目录。
+  `"exclude"` 为可选项，但默认忽略的文件和文件夹除外。这包括以 `.` 开头的文件和目录、CDK 输出目录和 `node_modules` 目录。

配置 `watch` 的最小设置为 `"watch": {}`。

如果您的 CDK 代码或应用程序代码需要在部署之前执行构建步骤，则 `cdk watch` 与 `cdk.json` 文件中的 `"build"` 键协同工作。

**重要**  
此命令用于在 CDK Apps 的开发阶段进行快速部署，不建议用于生产部署。

`cdk deploy --hotswap` 的相同限制也适用于 `cdk watch`。有关更多信息，请参阅 ` cdk deploy --hotswap `。

## 用法
<a name="ref-cli-cmd-watch-usage"></a>

```
$ cdk watch <arguments> <options>
```

## 参数
<a name="ref-cli-cmd-watch-args"></a><a name="ref-cli-cmd-watch-args-stack-name"></a>

 **CDK 堆栈 ID**   
应用中要监视的 CDK 堆栈的构造 ID。  
 *类型*：字符串  
 *必需*：否

## 选项
<a name="ref-cli-cmd-watch-options"></a>

有关适用于所有 CDK CLI 命令的全局选项的列表，请参阅[全局选项](ref-cli-cmd.md#ref-cli-cmd-options)。<a name="ref-cli-cmd-watch-options-build-exclude"></a>

 `--build-exclude, -E <ARRAY>`   
请勿使用给定 ID 重建资产。  
可以在单个命令中多次指定此选项。  
 *默认值*：`[]`<a name="ref-cli-cmd-watch-options-change-set-name"></a>

 `--change-set-name <STRING>`   
要创建的 CloudFormation 更改集的名称。<a name="ref-cli-cmd-watch-options-concurrency"></a>

 `--concurrency <NUMBER>`   
并行部署和热交换多个堆栈，同时考虑堆栈间的依赖项。使用此选项可以加快部署速度。您仍必须 AWS 考虑 CloudFormation 和其他账户费率限制。  
提供一个数字来指定要执行的最大同时部署数（依赖项允许）。  
 *默认值*：`1`<a name="ref-cli-cmd-watch-options-exclusively"></a>

 `--exclusively, -e <BOOLEAN>`   
仅部署请求的堆栈，不包括依赖项。<a name="ref-cli-cmd-watch-options-force"></a>

 `--force, -f <BOOLEAN>`   
即使模板相同，也始终部署堆栈。  
 *默认值*：`false`<a name="ref-cli-cmd-watch-options-help"></a>

 `--help, -h <BOOLEAN>`   
显示 `cdk watch` 命令的命令参考信息。<a name="ref-cli-cmd-watch-options-hotswap"></a>

 `--hotswap <BOOLEAN>`   
默认情况下，`cdk watch` 尽可能使用热交换部署来更新您的资源。CDK CLI 将尝试执行热交换部署，如果不成功，则不会回退到完全 CloudFormation 部署。检测到的任何无法通过热交换更新的更改都将被忽略。  
 *默认值*：`true`<a name="ref-cli-cmd-watch-options-hotswap-fallback"></a>

 `--hotswap-fallback <BOOLEAN>`   
默认情况下，`cdk watch`会尝试执行 hotswap 部署并忽略需要部署的更改。 CloudFormation 如果 hotswap CloudFormation 部署不成功，则提供`--hotswap-fallback`回退并执行完整部署。<a name="ref-cli-cmd-watch-options-logs"></a>

 `--logs <BOOLEAN>`   
默认情况下，`cdk watch`监视应用程序中的所有 CloudWatch 日志组，并将日志事件流式传输到本地`stdout`。  
 *默认值*：`true`<a name="ref-cli-cmd-watch-options-progress"></a>

 `--progress <STRING>`   
配置 CDK CLI 显示部署进度的方式。  
+  `bar`：以进度条的形式显示堆栈部署事件，其中包含当前正在部署的资源的事件。
+  `events`— 提供完整的历史记录，包括所有 CloudFormation 事件。
您也可以在项目的 `cdk.json` 文件中或本地开发计算机上的 `~/.cdk.json` 中配置此选项：  

```
{
   "progress": "events"
}
```
 *有效值*：`bar`、`events`  
 *默认值*：`bar`<a name="ref-cli-cmd-watch-options-rollback"></a>

 `--rollback <BOOLEAN>`   
在部署期间，如果资源创建或更新失败，则部署将在 CDK CLI 返回之前回滚到最新的稳定状态。在此之前所做的所有更改都将被撤消。将删除已创建的资源，并且将回滚所做的更新。  
使用 `--no-rollback` 或 `-R` 停用此行为。如果资源创建或更新失败，则 CDK CLI 将保留在此之前所做的更改并返回。在快速迭代的开发环境中，这可能会有所帮助。  
当为 `false` 时，引起资源替换的部署将始终失败。您只能将此值用于更新或创建新资源的部署。
 *默认值*：`true`<a name="ref-cli-cmd-watch-options-toolkit-stack-name"></a>

 `--toolkit-stack-name <STRING>`   
现有 CDK Toolkit 堆栈的名称。  
默认情况下，`CDKToolkit`将名为的堆栈`cdk bootstrap`部署到指定 AWS 环境中。使用此选项可为引导堆栈提供不同的名称。  
CDK CLI 使用此值来验证引导堆栈版本。

## 示例
<a name="ref-cli-cmd-watch-examples"></a>

### 查看带有逻辑 ID 的 CDK 堆栈是否有 DevelopmentStack 更改
<a name="ref-cli-cmd-watch-examples-1"></a>

```
$ cdk watch DevelopmentStack
Detected change to 'lambda-code/index.js' (type: change). Triggering 'cdk deploy'
DevelopmentStack: deploying...

 ✅  DevelopmentStack
```

### 配置 cdk.json 文件，以确定要包含和排除的监视更改内容
<a name="ref-cli-cmd-watch-examples-2"></a>

```
{
   "app": "mvn -e -q compile exec:java",
   "watch": {
    "include": "src/main/**",
    "exclude": "target/*"
   }
}
```

### 配置 cdk.json 文件，在部署之前使用 Java 构建 CDK 项目
<a name="ref-cli-cmd-watch-examples-3"></a>

```
{
  "app": "mvn -e -q exec:java",
  "build": "mvn package",
  "watch": {
    "include": "src/main/**",
    "exclude": "target/*"
  }
}
```