這是 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 環境未啟動，則只有不含資產和 51，200 個位元組以下合成範本的堆疊才會成功部署。

## 用量
<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>`   
平行部署多個堆疊，同時考慮堆疊間相依性。使用此選項可加速部署。您仍然必須將 in 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 將透過服務 APIs 直接更新資源，而不是執行 CloudFormation 部署。  
如果 CDK CLI 偵測到不支援熱插拔的變更，則會忽略這些變更，並顯示訊息。如果您偏好執行完整的 CloudFormation 部署做為回復，請`--hotswap-fallback`改用 。  
CDK CLI 會使用您目前的 AWS 登入資料來執行 API 呼叫。即使`@aws-cdk/core:newStyleStackSynthesis`功能旗標設定為 ，也不會從您的引導堆疊擔任角色`true`。這些角色沒有直接更新 AWS 資源的必要許可，無需使用 CloudFormation。因此，請確定您的登入資料與您執行熱插拔部署的堆疊 AWS 帳戶相同，而且它們具有更新資源所需的 IAM 許可。  
下列變更目前支援熱插拔：  
+ Lambda 函數的程式碼資產 （包括 Docker 影像和內嵌程式碼）、標籤變更和組態變更 （僅支援描述和環境變數）。
+ Lambda 版本和別名變更。
+  AWS Step Functions 狀態機器的定義變更。
+ Amazon ECS 服務的容器資產變更。
+ Amazon S3 儲存貯體部署的網站資產變更。
+  AWS CodeBuild 專案的來源和環境變更。
+ VTL 映射範本會變更 AWS AppSync 解析程式和函數。
+  AWS AppSync GraphQL APIs結構描述變更。
在熱插拔部署中，支援使用特定 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 堆疊中引入偏離，以加速部署。因此，請僅將其用於開發目的。請勿將此選項用於您的生產部署。
+ 此選項被視為實驗性，未來可能會有重大變更。
+ 某些參數的預設值可能與 hotswap 參數不同。例如，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 使用 ChangeSets 的新參數簡化資源匯入](https://aws.amazon.com/about-aws/whats-new/2023/11/aws-cloudformation-import-parameter-changesets/)。  
如需使用此選項的詳細資訊，請參閱在 *aws-cdk-cli GitHub 儲存庫*中[匯入現有資源](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>`   
CloudFormation 將針對堆疊相關事件通知的 Amazon SNS 主題 ARNs。<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 轉返](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 手錶](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'
```