配置AWS Lambda与API Gateway返回image/avif类型二进制数据咨询

核心原因 #

该问题是因为API Gateway的二进制媒体类型白名单未主动添加image/avif，仅靠默认image/*通配符匹配存在优先级问题：当请求Accept头首个类型为image/avif时，网关未识别为二进制类型，会直接将Lambda返回的内容按文本处理，最终返回base64编码字符串而非二进制流。

修复步骤 #

步骤1：更新API Gateway二进制媒体类型配置 #

• 进入对应API Gateway控制台，打开「设置」页面
• 找到「二进制媒体类型」模块，点击「添加二进制媒体类型」
• 手动输入image/avif并保存，不要仅依赖image/*通配符，显式添加优先级更高
• 若需同时支持其他图片格式，可同步添加image/webp、image/png等需要的类型
• 配置修改完成后必须重新部署API到对应阶段才会生效

步骤2：调整Lambda返回结构要求 #

不管返回什么格式的二进制图片，都需要严格符合API Gateway的二进制返回规范，Node.js示例代码如下：

exports.handler = async (event) => {
    // 你的图片读取/生成逻辑，imageBuffer为图片二进制Buffer
    const imageBuffer = getYourAvifImageBuffer();
    // 适配请求头返回对应Content-Type
    const acceptHeader = event.headers.Accept || event.headers.accept || '';
    let contentType = 'image/jpeg';
    if (acceptHeader.includes('image/avif')) {
        contentType = 'image/avif';
    } else if (acceptHeader.includes('image/webp')) {
        contentType = 'image/webp';
    }

    return {
        statusCode: 200,
        headers: {
            'Content-Type': contentType,
            'Cache-Control': 'public, max-age=31536000'
        },
        // 关键配置：isBase64Encoded必须设为true，body为二进制Buffer转base64的字符串
        isBase64Encoded: true,
        body: imageBuffer.toString('base64')
    };
};

按上述配置返回后，API Gateway会自动将base64格式的body转换为二进制流返回给客户端，不会让客户端收到base64字符串。

步骤3：验证修复效果 #

使用curl构造目标请求验证：
curl -v -H "accept: image/avif,image/webp,image/apng,image/svg+xml,image/*,*/*;q=0.8" https://你的API地址 > test.avif
下载的test.avif可正常打开即为修复完成。

常见排查点 #

• 确认API修改后已经重新部署到对应阶段，未部署的配置不会生效
• 不要在Lambda返回的headers里手动添加content-encoding，避免和API Gateway的自动压缩逻辑冲突
• 若使用的是HTTP API而非REST API，需要在API的「CORS设置」里允许Accept头传递，同时在「集成请求」里开启「转换二进制有效负载」
• 若使用IaC（CDK/SAM/CloudFormation）部署，需要在API配置的binaryMediaTypes字段中显式加入image/avif

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