API Gateway Lambda代理集成返回Base64文本而非PDF的问题排查

问题核心 #

浏览器直接请求你的GET端点时，由于默认Accept头不包含application/pdf，API Gateway不会将Lambda返回的Base64编码内容解码为二进制PDF，而是直接返回Base64文本；但设置二进制媒体类型为*/*会影响其他JSON接口的正常响应。

可行解决方案 #

方案1：调整Stage的内容处理策略（推荐） #

这是最直接的解决方式，让API Gateway仅根据响应的Content-Type判断是否处理为二进制，忽略请求的Accept头：

1. 进入AWS API Gateway控制台，选中目标API
2. 进入对应Stage（如prod）的Settings页面
3. 在Content Handling下拉菜单中选择Convert to Binary
4. 重新部署API到该Stage（关键步骤，配置变更需部署生效）

该设置仅对二进制媒体类型列表中的Content-Type生效（你已添加application/pdf），不会影响application/json等其他类型接口的正常响应。

方案2：优化Lambda响应头 #

在Lambda返回的响应头中添加Content-Transfer-Encoding，辅助浏览器识别内容编码：

return {
  statusCode: 200,
  headers: {
    "Content-Type": "application/pdf",
    "Content-Disposition": `attachment; filename=${fileName}`,
    "Content-Transfer-Encoding": "base64"
  },
  body: file.Body.toString("base64"),
  isBase64Encoded: true,
};

配合已配置的application/pdf二进制媒体类型，多数浏览器能正确识别并解码内容。

方案3：切换为非代理集成（备选） #

若上述方案无效，可尝试非代理集成，手动控制响应映射：

1. 创建GET方法时选择Lambda非代理集成
2. 配置方法响应：添加application/pdf类型的200状态码
3. 配置集成响应：将Lambda返回的Base64内容映射到响应体，开启Base64解码，并设置Content-Type为application/pdf
4. 部署API生效

此方式配置复杂度更高，但能更精确控制响应流程。

关键注意事项 #

• 不要将二进制媒体类型设为*/*，否则API Gateway会将所有响应当作二进制处理，导致JSON接口返回乱码或内部错误
• 所有配置变更后必须重新部署API到对应Stage，否则不会生效

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