部署含REST API与apigateway.BasePathMapping的CDK栈时遇已存在错误

问题根源 #

这个报错本质是AWS云端残留了<my_domain>|(none)的路径映射资源，或者CDK本地缓存的状态和云端不同步，哪怕删了栈重建也会触发冲突。

实操解决步骤 #

清理CDK本地缓存 #

• 删掉项目根目录的cdk.out文件夹，这玩意儿存着旧的部署记录，很容易导致误判。
• 打开cdk.context.json，如果里面有和这个域名相关的条目，直接删掉后保存文件。
• 执行cdk bootstrap --force，强制刷新CDK和AWS环境的同步状态。

彻底清除云端残留资源 #

• 用AWS CLI查询该域名下所有路径映射：

  aws apigateway get-base-path-mappings --domain-name <你的域名>
  

  如果返回结果里还有(none)的映射，执行删除命令：

  aws apigateway delete-base-path-mapping --domain-name <你的域名> --base-path '(none)'
  

• 进入API Gateway控制台的自定义域名页面，反复刷新确认该域名下没有残留的路径映射（控制台可能存在延迟，多等待2-3分钟再检查）。
• 检查Route53的域名解析记录，如果之前指向该API Gateway的A/AAAA记录仍存在，手动删除这些记录。

调整CDK代码避免重复冲突 #

• 确保BasePathMapping的domainName属性引用的是CDK中定义的自定义域名资源，不要直接硬编码域名字符串。
• 显式将basePath设为空字符串，替代默认的(none)值，代码示例：

  new apigateway.BasePathMapping(this, 'UniqueMappingId', {
    domainName: myCustomDomain,
    restApi: myRestApi,
    basePath: '' // 显式指定空路径，避免默认值引发的冲突
  });
  

• 给BasePathMapping设置唯一的资源ID，让CDK能准确识别资源身份，避免和旧残留资源混淆。

最后验证 #

完成上述步骤后，先执行cdk diff查看变更内容，确认无资源冲突提示后，再运行cdk deploy重新部署栈。

内容的提问来源于stack exchange，提问作者Romain Deterre