AWS Lambda通过API Gateway返回二进制体与HTTP头的配置及调试问题

我之前做类似需求时也踩过一模一样的坑，你的问题核心在于API Gateway非代理集成模式下，响应映射的路径配置错误，加上二进制转换的配套设置没跟上。下面一步步给你拆解解决方案：

一、先搞定基础：API Gateway二进制媒体类型配置 #

首先得让API Gateway识别你要返回的二进制类型，这是前提：

• 打开API Gateway控制台，找到你的API，进入「Settings」页面
• 在「Binary Media Types」区域，添加需要的类型（比如image/jpeg、image/png），测试阶段可以先填*/*匹配所有类型（生产环境建议精准配置）
• 保存设置，否则API Gateway会把二进制内容当成普通文本处理

二、修正集成响应的映射配置 #

你之前的错误主要出在头映射的路径上——Lambda返回的JSON是顶层结构，headers不在body里面，所以映射路径要调整：

1. 进入你的API资源对应的方法，切换到「Integration Response」标签
2. 选择对应的状态码（比如200，或者创建一个default模板适配所有状态码）
3. 配置头映射：
   • 点击「Add header」，输入Content-Type
   • 映射值填写：$input.json('$.headers.content-type')
   • 如果是重定向场景，添加Location头，映射值写$input.json('$.headers.Location')
4. 配置体映射模板：
   • 为需要的Content-Type（比如image/jpeg）添加模板，模板内容直接写：$input.json('$.body')
   • 重点注意：不要给body加引号！Lambda返回的body已经是纯Base64字符串，加引号会导致API Gateway转换二进制失败
5. 开启二进制转换：
   • 在集成响应的设置里，找到「Content Handling」，选择「Convert to binary」，这样API Gateway会自动把Base64编码的body转换成二进制流返回

三、重定向场景的适配 #

如果Lambda需要返回重定向（比如302状态码）：

• Lambda返回的JSON结构改成：

  { "statusCode": 302, "headers": { "Location": "https://your-target-url.com" }, "body": "", "isBase64Encoded": false }
  

• 在集成响应里添加302状态码的映射，配置Location头的映射值为$input.json('$.headers.Location')
• 体映射模板可以留空，因为重定向不需要返回响应体

四、开启调试日志定位具体错误 #

要搞清楚「Unable to transform response」的根因，必须开启API Gateway的CloudWatch日志：

1. 回到API Gateway控制台的「Settings」页面，找到「CloudWatch Settings」
2. 勾选「Enable CloudWatch Logs」，日志级别选「DEBUG」（会输出映射执行的详细过程）
3. 选择一个有权限推送日志到CloudWatch的IAM角色（可以直接用AWS托管的AmazonAPIGatewayPushToCloudWatchLogs策略）
4. 保存后调用API，然后去CloudWatch控制台找到对应的日志组（格式通常是API-Gateway-Execution-Logs_{你的API ID}/{部署阶段}）
5. 查看日志里的Transformation相关条目，会明确告诉你是映射路径错误、模板语法问题，还是二进制类型不匹配

几个容易踩的坑 #

• 非代理集成模式下，Lambda返回的isBase64Encoded字段不会被API Gateway自动识别，全靠「Content Handling」设置触发二进制转换
• 体映射模板里的$input.json('$.body')必须是纯Base64字符串，不能有多余的引号或转义字符
• 如果要返回自定义头，必须先在「Method Response」里添加对应的头字段，再在「Integration Response」里做映射，否则头不会被返回给客户端

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