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

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

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

执行差异以查看 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-method"></a>

 `--method, -m <STRING>`   
指定如何计算差异。  
+  `auto`— 默认。创建 AWS CloudFormation 更改集以显示准确的替换信息。如果无法创建更改集（例如，由于缺少权限），则会回退到仅限模板的差异。使用部署角色。
+  `change-set`— 始终创建更改集，如果无法创建，则会失败。当您需要保证精度时，请使用此选项。使用部署角色。
+  `template`— 直接比较 CloudFormation 模板。速度更快，但不太准确。检测到的需要资源替换的属性的任何更改都将显示为资源替换，即使更改纯粹是表面上的。使用查找角色。

   *默认值*：`auto`<a name="ref-cli-cmd-diff-options-change-set"></a>

 `--change-set <BOOLEAN>`*（已弃用）*   
指定是否创建更改集来分析资源替换。请改用 `--method`。  
 `--change-set`映射到`--method=auto`。 `--no-change-set`映射到`--method=template`。<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>`   
要与 CDK 堆栈进行比较的 CloudFormation 模板路径。暗示`--method=template`。

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

### 与当前部署的名为的堆栈进行比较 MyStackName
<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 --method=template 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 模板进行比较
<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
```