AWS API Gateway Lambda反向代理：JS调用Fetch返回响应头失效怎么办？

当你用Lambda做API Gateway的反向代理，通过JavaScript的Fetch调用外部接口后没法把响应头正确返回给前端时，几乎都是Lambda的响应格式不符合API Gateway要求，或者Fetch响应处理不到位导致的。下面是具体的排查和修复步骤：

1. 必须遵循Lambda代理的响应格式 #

API Gateway对Lambda代理集成的返回结构有强制要求，不能直接返回Fetch的Response对象，必须手动拆解并组装成规范结构：

exports.handler = async (event) => {
  // 调用目标外部接口
  const externalRes = await fetch('https://your-target-api.com');

  // 提取并转换响应头：API Gateway要求headers为键值对对象，键名需符合HTTP规范
  const responseHeaders = {};
  for (const [key, value] of externalRes.headers.entries()) {
    // 跳过API Gateway自动处理的保留头（如x-amz-、x-api-开头的字段）
    if (!key.startsWith('x-amz-') && !key.startsWith('x-api-')) {
      responseHeaders[key] = value;
    }
  }

  // 组装符合要求的最终响应
  return {
    statusCode: externalRes.status,
    headers: {
      ...responseHeaders,
      // 跨域场景必须添加这些头（根据实际需求调整）
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type'
    },
    body: await externalRes.text() // 若为JSON响应，改用JSON.stringify(await externalRes.json())
  };
};

2. 常见错误点排查 #

• 直接返回Fetch响应对象：Fetch返回的Response是特殊对象，API Gateway无法解析，必须手动提取status、headers、body字段重新组装。
• 响应头被过滤：API Gateway会自动过滤x-amz-*、x-api-*这类保留头，若要传递自定义头，需确保头名是合法HTTP格式（用连字符代替下划线），同时在API Gateway集成响应中配置允许这些头通过。
• CORS头缺失：跨域调用场景下，浏览器会拦截无CORS头的响应，看起来像是响应头未返回，必须在Lambda返回的headers中添加对应CORS配置。
• Body未序列化：返回JSON数据时必须用JSON.stringify()转为字符串，不能直接返回JSON对象，否则API Gateway会解析失败。

3. 调试技巧 #

• 查看Lambda控制台的执行日志，确认返回的响应结构是否和示例一致，重点检查headers字段是否包含预期内容。
• 用Postman直接调用API Gateway端点，对比实际返回的响应头和Lambda日志中的headers，定位丢失的字段。
• 检查API Gateway集成设置，确保是Lambda代理集成，且未在集成请求/响应中添加额外头映射规则，避免覆盖需要返回的头。

内容的提问来源于stack exchange，提问作者Matthew V Carey