AWS APIGateway HTTP API未返回预期预检头CORS问题排查

AI 小北

2026-10-5

AWS API Gateway HTTP API 预检CORS头不返回的排查方案

优先检查CORS配置匹配度
API Gateway HTTP API的CORS校验逻辑为：只要预检请求的参数和配置项不完全匹配，就直接不返回所有CORS响应头，不会返回错误提示。需要逐一核对：
1. 允许的源（Access-Control-Allow-Origin）：如果填写精确域名，必须和请求的Origin头完全一致，不要加末尾斜杠；如果使用通配符*，则请求不能携带withCredentials/credentials: include参数。
2. 允许的HTTP方法：必须把你实际使用的请求方法（比如你场景里的POST）加入配置列表，同时不要漏加OPTIONS方法。
3. 允许的请求头：如果你的实际请求带了自定义头，必须把所有自定义头的名称精确加入配置列表，也可以填*通配所有请求头。
4. 若使用自定义域名访问，确认自定义域名映射的阶段是你修改了CORS配置的$default阶段，不要映射到其他未修改配置的阶段。
确认部署生效
哪怕开启了$default阶段的自动部署，CORS配置修改后仍可能存在1-2分钟的延迟，建议修改后手动触发一次阶段部署，确认部署完成后再测试。
清除自定义OPTIONS路由
如果你之前为了测试手动添加了OPTIONS方法的路由和集成，必须删除该路由，只要存在自定义OPTIONS路由，API Gateway就会优先走自定义集成逻辑，忽略全局CORS配置，不会自动生成CORS响应头。
校验业务请求返回逻辑
非预检的实际业务请求（比如POST）如果需要返回CORS头，不需要在Lambda里额外添加，API Gateway会自动插入；如果发现业务请求也没有CORS头，再确认是否在配置里把需要的头加入了Access-Control-Expose-Headers暴露列表。