Quarkus Lambda REST端点API Gateway响应被强制Base64编码问题

一、禁用Base64编码的具体方法 #

1. 配置Quarkus Lambda REST扩展 #

在application.properties中明确指定需要透传的二进制媒体类型，让Quarkus识别这些类型的内容无需编码：

quarkus.amazon-lambda-rest.binary-media-types=image/png,image/jpeg,application/octet-stream

若需适配所有二进制类型，可使用*/*，但建议明确指定目标类型以避免不必要的内容透传。

2. 确保REST端点返回正确响应格式 #

端点需返回包含原始字节实体和精确Content-Type头的Response对象，示例代码：

@GET
@Path("/s3-content/{objectKey}")
public Response fetchS3Content(@PathParam("objectKey") String objectKey) {
    // 从S3获取原始字节内容
    byte[] contentBytes = s3Client.getObjectAsBytes(BUCKET_NAME, objectKey).asByteArray();
    // 获取S3对象自带的Content-Type（或根据业务场景硬编码）
    String contentType = s3Client.headObject(HeadObjectRequest.builder().bucket(BUCKET_NAME).key(objectKey).build()).contentType();
    
    return Response.ok(contentBytes)
                   .header(HttpHeaders.CONTENT_TYPE, contentType)
                   .build();
}

3. 验证API Gateway配置 #

• 确认已在API Gateway控制台的设置→二进制媒体类型中添加目标类型（如image/png），添加后必须重新部署API才能使配置生效。
• 确保API使用Lambda代理集成，只有代理集成会自动根据Content-Type和二进制配置处理内容编码逻辑。

二、API Gateway忽略Content-Type/二进制配置的常见场景 #

• 配置未部署：修改二进制媒体类型后未重新部署API到对应阶段，新配置不会生效。
• Content-Type不精确匹配：响应头的Content-Type必须与API Gateway配置的二进制类型完全一致，例如配置image/png但返回image/png;charset=utf-8，会导致匹配失败。
• Lambda响应isBase64Encoded字段错误设为true：若Quarkus或自定义代码强制将该字段设为true，API Gateway会默认按Base64编码处理内容，忽略二进制配置。
• 使用非代理集成：传统Lambda集成（非代理）需手动在集成响应中配置内容处理策略，不会自动识别二进制类型。
• 阶段配置覆盖全局配置：API Gateway的每个阶段可单独设置二进制媒体类型，若阶段配置与全局配置冲突，会优先使用阶段配置。
• Lambda响应格式不符合代理要求：代理集成要求响应必须包含statusCode、headers、body等核心字段，格式错误时API Gateway会默认按文本处理，导致Base64编码。

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