使用 TypeScript 或 Python 透過 CDK 撰寫、部署及排解 AWS 基礎設施問題。涵蓋最佳實踐、堆疊架構與建構模式。在撰寫 CDK 建構、引導環境、執行 cdk deploy/synth/diff、修正 CDK 或 CloudFormation 錯誤、規劃堆疊結構、匯入現有資源、解決漂移或重構堆疊而不取代資源時，一律使用此技能。
AWS CDK
概述
CDK 建構撰寫、部署工作流程、合規、漂移、匯入資源、安全重構以及排解 CDK CLI / CloudFormation 錯誤的領域專業知識。
何時不使用： 原始 CloudFormation YAML/JSON、SAM、Terraform/Pulumi、CDK Pipelines 以外的 CI/CD。請使用內建知識或專門技能處理這些情況。
重要警告
致命循環： 移除跨堆疊參考會導致部署死結（Export ... cannot be deleted as it is in use by ...）。建議的修正方式：先弱化參考 — CrossStackReferences.of($RESOURCE).produce(ReferenceStrength.BOTH) 然後 WEAK，再移除（需三次部署）。舊版替代方案：兩次部署的 this.exportValue() 方法。請參閱 troubleshooting-deployment。
建構 ID 變更會導致資源取代： 重新命名或移動建構會變更其邏輯 ID → CloudFormation 會取代該資源（有狀態資源會遺失資料）。務必在部署前執行 cdk diff。請參閱 refactor-and-prevent-replacement。
UPDATE_ROLLBACK_FAILED： 堆疊卡住。使用 cdk rollback $STACK 或 cdk rollback $STACK --orphan <LogicalId> 修正。請參閱 troubleshooting-deployment。
非空 S3 儲存桶在銷毀後仍存在： 您必須同時設定 removalPolicy: DESTROY 和 autoDeleteObjects: true。啟用版本控制的儲存桶更糟 — 即使看似刪除，刪除標記仍會保留。
常見工作流程
| 任務 | 快速指令 | 詳細資訊 |
|---|---|---|
| 引導 | cdk bootstrap aws://$ACCOUNT/$REGION |
bootstrap-and-project-setup |
| 新增 TypeScript 專案 | cdk init app --language typescript — 使用 tsx、eslint-plugin-awscdk |
bootstrap-and-project-setup |
| 新增 Python 專案 | cdk init app --language python — 鎖定相依套件、使用虛擬環境 |
bootstrap-and-project-setup |
| 部署 | cdk synth --strict → cdk diff → cdk deploy |
部署至正式環境前務必先執行 diff |
| cdk-nag | Aspects.of(app).add(new AwsSolutionsChecks()) |
compliance-and-drift |
| 漂移 | cdk drift $STACK（在 CI 中使用 --fail） |
compliance-and-drift |
| 匯入資源 | cdk import（互動式或 CI 中使用 --resource-mapping）、cdk deploy --import-existing-resources |
import-and-migrate |
| 安全重構 | cdk refactor --unstable=refactor — 同一次部署中不得有屬性變更 |
refactor-and-prevent-replacement |
排解問題
| 錯誤 | 原因 → 修正方式 |
|---|---|
| DeployFailed / DeploymentError | CDK 錯誤並非根本原因。執行 cdk deploy $STACK --verbose，然後 cdk --unstable=diagnose diagnose $STACK（CLI ≥ 2.1120.0）；否則執行 aws cloudformation describe-events --stack-name $STACK --filters FailedEvents=true — 第一個 _FAILED 事件即為原因。詳細資訊 |
| NoCredentials / ExpiredToken / AssumeRoleFailed | 執行 aws sts get-caller-identity + cdk doctor。SSO 過期、缺少 env、缺少 sts:AssumeRole。詳細資訊 |
| 資產錯誤（CannotFindAsset、FailedToBundleAsset、AssetBuildFailed、AssetPublishFailed） | 路徑錯誤、Docker 未執行或引導儲存桶權限問題。使用 path.join(__dirname, ...)。詳細資訊 |
| AppRequired | 在 cdk.json 中加入 "app": "npx tsx bin/my-app.ts"。詳細資訊 |
| AnnotationErrors | 修正根本問題；僅在最後手段使用 NagSuppressions 抑制。詳細資訊 |
| ConcurrentReadLock / ConcurrentWriteLock | 執行 rm -rf cdk.out 然後重新執行。並行 CI：使用 --output ./cdk.out.$BUILD_ID。詳細資訊 |
| BootstrapVersionValidation | 重新引導。在所有地方使用相同的 --qualifier。詳細資訊 |
| DependencyCycle | 將共享資源提取到第三個堆疊，或使用 SSM 進行晚期繫結。詳細資訊 |
| UnresolvedAccount | 在堆疊上設定明確的 env: { account, region }。提交 cdk.context.json。詳細資訊 |
| NoStacksMatched | CDK 使用邏輯 ID（第二個建構參數），而非 CFN 名稱。執行 cdk list 尋找 ID。詳細資訊 |
| Cannot find module（合成時） | 執行 npx tsc --noEmit，檢查 cdk.json 中的應用程式路徑是否與 tsconfig.json 的 outDir 相符，刪除過時的 .js 檔案。Python：啟動虛擬環境。詳細資訊 |
| V1 匯入路徑 / 重複的 aws-cdk-lib | V1 的 @aws-cdk/* 匯入、錯誤的 Construct 匯入、monorepo 中的重複函式庫副本。詳細資訊 |
| Lambda Cannot find module（執行時期） | 錯誤的處理常式值、缺少 SDK v3 遷移、Python 相依套件未打包。詳細資訊 |
| API Gateway 多階段衝突 | 在 RestApi 上設定 deploy: false，明確建立 Deployment 和 Stage。詳細資訊 |
建構模式
優先使用 L2。當 L2 缺少某個屬性時，使用 L1 搭配 Mixins/Facades。脫逃機制：node.defaultChild → addPropertyOverride。請參閱 construct-patterns。
其他資源
- 搜尋 AWS 文件中的「CDK Developer Guide」、「CDK API Reference」和「CDK Pipelines」
安全考量
- CI/CD 憑證使用 OIDC（無靜態金鑰）
- 引導時使用
--custom-permissions-boundary - 使用
grant*()進行資源間的 IAM 授權 - 在 CI 中使用
cdk-nag+--strict - 有狀態資源放在自己的堆疊中，並設定
terminationProtection: true - 提交
cdk.context.json
