AWS API Gateway v2自定义Header无法传递至Lambda的问题求助

核心问题说明 #

APIGW v2（HTTP API）的代理集成和v1 REST API在Header处理上有几个关键差异，导致你无法获取自定义refreshToken Header：

• 代理集成会自动将所有Header键名转为小写，所以Lambda事件中对应的键是refreshtoken而非refreshToken
• 跨域场景下，自定义Header必须在CORS配置中明确允许，否则浏览器会拦截请求，根本不会发送该Header
• 代理集成默认自动转发全量请求数据，手动添加参数映射反而会覆盖默认逻辑，导致Header丢失

具体解决步骤 #

1. 修正Lambda取值逻辑 #

在Lambda中打印完整事件，确认Header位置，注意键名是全小写：

def lambda_handler(event, context):
    # 打印完整事件排查
    print("Lambda接收事件：", event)
    # 用小写键名获取Header值
    refresh_token = event.get('headers', {}).get('refreshtoken')
    return {
        'statusCode': 200,
        'body': f"获取到的refreshToken: {refresh_token}"
    }

2. 配置APIGW v2的CORS（跨域场景必做） #

如果前端是跨域请求，必须在HTTP API的CORS设置中允许自定义Header：

• 进入APIGW v2控制台，打开目标HTTP API的CORS配置页
• 在Allowed headers中添加refreshtoken（大小写不敏感，APIGW会自动兼容）
• 保存配置并等待部署完成

3. 删除错误的参数映射 #

如果之前手动添加了$request.header.refreshtoken的参数映射，立即删除：

• 进入集成配置页面，找到Request parameters或Parameter mappings
• 清空所有手动添加的映射规则，恢复代理集成的默认转发逻辑

4. 验证前端实际请求 #

通过浏览器开发者工具的Network标签检查请求：

• 找到对应的GET请求，查看Request Headers中是否存在refreshtoken
• 如果不存在，检查前端代码是否正确设置Header，或是否存在预检请求失败的情况

关键注意事项 #

• APIGW v2代理集成的headers字段所有键均为小写，务必用小写键名取值
• 跨域场景下，自定义Header必须在CORS中声明允许，否则浏览器会拦截
• 代理集成无需手动配置参数映射，默认自动转发所有请求数据

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