AWS API Gateway自定义域名映射与路径代理路由问题排查

问题背景 #

已完成自定义域名创建与映射配置，但访问/v1/account路径时持续返回Forbidden错误，仅$default路由可正常接收请求。需求是通过单API Gateway按路径分发请求至不同服务（例如v1/account对应account Lambda），尝试调整映射路径版本等操作后仍未解决。

映射配置说明 #

自定义域名映射项中，路径前缀设为/v1/account，目标关联指定API Gateway，映射阶段为v1。

网关配置说明 #

API Gateway内已创建/v1/account路径，并关联对应的Lambda集成，同时存在$default路由规则。

排查操作步骤 #

• 核对路由匹配与请求方法一致性
  确认/v1/account路由配置的请求方法（GET/POST等）与实际发起的请求完全匹配，若路由仅配置单一方法，其他方法请求会触发403错误。同时检查该路由是否开启API密钥验证或IAM授权，若开启需确保请求携带有效凭证，可临时关闭授权进行测试，快速排除权限类问题。

• 验证路径转换逻辑
  自定义域名映射的路径前缀/v1/account关联到阶段v1时，默认会剥离前缀，实际转发到API的路径为/account。需确认API Gateway内是否存在/account路径（而非/v1/account）；若需保留完整路径转发，需将映射的路径转换设置为「无」。

• 检查阶段与Lambda权限
  查看API阶段v1的资源策略，确认未限制自定义域名的访问；同时验证Lambda执行角色是否具备apigateway:Invoke权限，以及API Gateway是否被授权调用目标Lambda函数。

• 通过CloudWatch日志定位根因
  开启API Gateway的CloudWatch日志功能，查看请求的详细日志：

  • 确认请求是否命中预期路由，还是被$default路由捕获（若为后者，说明路由匹配规则存在问题）。
  • 日志中会明确标注错误类型，例如权限问题会显示Missing Authentication Token或Access Denied。

• 确认域名SSL证书与DNS解析
  检查自定义域名绑定的SSL证书是否有效、未过期；通过nslookup等工具验证DNS解析是否正确指向API Gateway的分配域名，证书无效或解析错误也可能导致403错误。

• 绕开自定义域名直接测试API
  使用API Gateway原生域名（格式如https://xxxx.execute-api.region.amazonaws.com/v1/account）直接发起请求：

  • 若能正常响应，说明问题出在自定义域名的映射配置；
  • 若仍返回403，问题则集中在API Gateway的路由或权限设置上。

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