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

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

# `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'
```