本地运行SAM API时BinaryMediaTypes无法正常返回PDF问题求助

1. 确认Lambda响应结构是否符合要求 #

SAM本地对二进制响应的格式要求更严格，必须包含以下关键字段：

• isBase64Encoded: true：明确告知API Gateway模拟器body是base64编码的二进制数据
• Content-Type: application/pdf：正确设置响应的媒体类型
• body必须是PDF原始二进制数据的base64编码字符串，而非原始字节

示例响应结构（Python）：

import base64

def lambda_handler(event, context):
    with open("generated.pdf", "rb") as f:
        pdf_content = f.read()
    return {
        "statusCode": 200,
        "headers": {
            "Content-Type": "application/pdf"
        },
        "body": base64.b64encode(pdf_content).decode("utf-8"),
        "isBase64Encoded": True
    }

2. 验证template.yaml的BinaryMediaTypes配置是否生效 #

确保BinaryMediaTypes配置绑定到了Lambda关联的API资源上，而非默认的隐式API：

Resources:
  # 显式定义API资源并配置BinaryMediaTypes
  PdfApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: dev
      BinaryMediaTypes:
        - "*/*"

  # Lambda关联该显式API
  PdfGeneratorFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: ./pdf-generator
      Handler: index.handler
      Events:
        GetPdfRequest:
          Type: Api
          Properties:
            RestApiId: !Ref PdfApi
            Path: /generate-pdf
            Method: get

如果Lambda使用默认隐式API（未指定RestApiId），BinaryMediaTypes的配置可能不会被应用到该API上。

3. 升级SAM CLI到最新版本 #

旧版本SAM CLI存在二进制响应处理的bug，运行以下命令升级：

# pip安装方式
pip install --upgrade aws-sam-cli

# 验证版本
sam --version

4. 排查客户端（Postman）设置问题 #

• 尝试用curl测试响应是否正常：

  curl http://localhost:3000/generate-pdf --output test.pdf
  

  如果下载的test.pdf能正常打开，说明是Postman的设置问题：在Postman的响应面板中切换到「Binary」视图查看，或关闭自动解析响应的设置。
• 确保Postman没有添加Accept: text/*之类的请求头，导致响应被错误编码。

5. 重启SAM本地服务 #

修改template.yaml或Lambda代码后，必须重启sam local start-api服务，确保配置生效。

内容的提问来源于stack exchange，提问作者red house 87