替换CloudFormation中BasePathMapping为ApiMapping后遇重复键问题求助

我来帮你搞定这个问题，这个"ApiMapping key already exists"错误本质上是旧资源残留或者资源状态不一致导致的，下面是一步步的解决思路和操作方法：

一、先搞懂错误根源 #

你替换成AWS::ApiGatewayV2::ApiMapping后报错，核心原因有两个：

1. 原来的AWS::ApiGateway::BasePathMapping资源并没有被自动删除，它还占用着域名的根路径映射；
2. 你的AWS账户里可能已经存在一个和当前配置冲突的V2 ApiMapping（比如之前手动创建过，或者旧栈部署残留的）。

二、分步解决步骤 #

1. 清理旧的V1 BasePathMapping #

CloudFormation不会自动帮你删除被替换的旧资源，所以得先处理它：

• 先回滚你的Terraform/CloudFormation变更，恢复原来的PathMapping资源定义；
• 登录AWS控制台，进入API Gateway → 找到你的自定义域名 → 切换到「基础路径映射」板块；
• 删除那个指向WebSocket API的(none)路径映射；
• 或者也可以在Terraform里先单独执行删除旧资源的操作，再部署新配置。

2. 确保V2 DomainName和ApiMapping的匹配性 #

WebSocket API只能绑定到V2版本的DomainName（即AWS::ApiGatewayV2::DomainName创建的域名），如果你的CustomDomainName是V1的AWS::ApiGateway::DomainName，那必须先把域名迁移到V2，否则后续还是会出问题。

另外，V2 ApiMapping里如果要实现根路径（对应原来的(none)），不需要额外指定BasePath属性——默认就是根路径，你的当前配置是正确的。

3. 手动清理冲突的V2 ApiMapping（如果需要） #

如果清理旧资源后还是报错，就用AWS CLI排查并删除冲突资源：

• 查询当前域名下的所有ApiMapping：

  aws apigatewayv2 get-api-mappings --domain-name <你的自定义域名>
  

• 找到输出中根路径对应的ApiMappingId，执行删除：

  aws apigatewayv2 delete-api-mapping --api-mapping-id <冲突的ID> --domain-name <你的自定义域名>
  

• 之后重新部署你的Terraform/CloudFormation栈即可。

三、额外注意事项 #

• 同一个V2 DomainName下，根路径只能绑定一个API；如果要同时挂载WebSocket和HTTP/REST API，得给不同的API分配不同的BasePath，并且都用V2的ApiMapping来配置；
• 部署前最好先通过AWS控制台或CLI确认当前域名的映射状态，避免CloudFormation的状态和实际AWS资源不一致导致的问题。

内容的提问来源于stack exchange，提问作者Kostadin Mandulov