关于 aws-cdk
aws-cdk 是面向 AWS CDK 应用编写与部署团队的领域技能，涵盖构造模式、合规性、漂移、资源导入、安全重构、部署流程和故障排查，并说明如何避免资源替换及不安全的部署方式。
主要功能
- 01构造编写模式
- 02部署与差异检查流程
- 03合规性与漂移检查
- 04资源导入与安全重构
- 05CDK 和 CloudFormation 故障排查
适用场景
- 01生产部署前审查变更
- 02诊断 CDK 部署失败
- 03导入现有 AWS 资源
- 04重构构造并避免资源替换
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/aws-cdk确认已加载。
包含的文件
除 SKILL.md 外，安装时一起下载的参考资料和脚本。
references/bootstrap-and-project-setup.mdcompliance-and-drift.mdconstruct-patterns.mdfast-deployments.mdimport-and-migrate.mdrefactor-and-prevent-replacement.mdtroubleshooting-credentials.mdtroubleshooting-deployment.mdtroubleshooting-synth.mdv1-to-v2-migration.md详细介绍
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> 修复。Express mode 堆栈是例外——完全无法回滚。参见 troubleshooting-deployment。
Hotswap 和 express mode 仅供开发使用：--hotswap / --hotswap-fallback 会绕过 CloudFormation，并有意造成漂移；--express 会在资源稳定前报告成功，并禁用自动回滚。生产环境绝对不能使用这两种模式。失败的 --express 部署无法回滚——请通过再次使用 --express 部署来向前修复。参见 fast-deployments。
销毁后非空 S3 存储桶仍会保留：必须同时设置 removalPolicy: DESTROY 和 autoDeleteObjects: true。版本控制存储桶的问题更严重——即使看似已删除，删除标记仍会保留。
常见工作流
| 任务 | 快速命令 | 详情 |
|---|---|---|
| 引导 | cdk bootstrap aws://$ACCOUNT/$REGION | bootstrap-and-project-setup |
| 新建 TS 项目 | cdk init app --language typescript — 使用 tsx、eslint-plugin-awscdk | bootstrap-and-project-setup |
| 新建 Python 项目 | cdk init app --language python — 固定依赖版本，使用 virtualenv | bootstrap-and-project-setup |
| 部署 | cdk synth --strict → cdk diff → cdk deploy | 部署到生产环境前始终先运行 diff |
| 快速开发迭代 | cdk deploy --hotswap-fallback、cdk watch 或 cdk deploy --express — 仅供开发使用，绝不用于生产环境 | fast-deployments |
| 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 |
快速部署 — Hotswap 与 Express（仅限开发环境）
两者都以牺牲安全性换取速度，绝不能在生产环境中使用。
**如何选择：**如果你主要使用可热替换的资源，且不在意漂移，请使用 --hotswap / --hotswap-fallback，以获得最快的迭代速度。如果不能接受漂移，或你的资源不可热替换，请使用 --express。
恢复工作流（通过 --revert-drift 处理 hotswap 漂移、将失败的 --express 部署继续向前推进）、可热替换资源规则，以及通过 IAM/监控强制执行生产环境禁用规则，详见完整指南：快速部署。
故障排除
| 错误 | 原因 → 修复 |
|---|---|
| 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 的 app 路径是否与 tsconfig.json 的 outDir 匹配，并删除过时的 .js 文件。Python：激活虚拟环境。详情 |
| V1 导入路径 / 重复的 aws-cdk-lib | V1 的 @aws-cdk/* 导入、错误的 Construct 导入，以及 monorepo 中存在重复的库副本。详情 |
| Lambda Cannot find module（运行时） | handler 值错误、缺少 AWS SDK v3 迁移，或未打包 Python 依赖项。详情 |
| API Gateway 多阶段冲突 | 在 RestApi 上设置 deploy: false，并显式创建 Deployment 和 Stage。详情 |
在 --hotswap 下更改未部署 | 对不可热交换资源的更改会被静默忽略，仅记录在日志中——命令仍会报告成功。查看输出；使用 --hotswap-fallback 强制改用 CloudFormation 部署。详情 |
--express 部署失败 / 无法回滚 | Express 模式无法使用 Rollback Stack API，且不得使用标准部署来恢复。向前修复：解决原因后运行 cdk deploy $STACK --express。详情 |
| 开发堆栈出现意外偏差 | Hotswap 和 cdk watch 会按设计产生偏差。在恢复之前，权威依据是实时资源，而非 CloudFormation 的记录。使用 cdk deploy $STACK --revert-drift 进行协调；它会使用 Drift Aware Changesets 使实时资源与模板保持一致（将实际状态更新为符合期望状态；不会重写 CF 记录以匹配发生偏差的资源）。详情 |
构造模式
优先使用 L2。当 L2 缺少某个属性时，使用带 Mixins/Facades 的 L1。逃生舱口：node.defaultChild → addPropertyOverride。参见 construct-patterns。
其他资源
- 分别在 AWS 文档中搜索 “CDK Developer Guide”、“CDK API Reference” 和 “CDK Pipelines”
安全注意事项
- CI/CD 凭证使用 OIDC（不使用静态密钥）
- 引导时使用
--custom-permissions-boundary - 跨资源 IAM 使用
grant*() - 在 CI 中使用
cdk-nag和--strict - 将有状态资源放在独立的堆栈中，并设置
terminationProtection: true - 提交
cdk.context.json