Serverless框架下WebSocket配置CONVERT_TO_BINARY内容策略

推荐方案：使用事件级 Overrides 配置（适配 Serverless v3.26.0+） #

原生Serverless WebSocket事件未暴露二进制处理相关字段，可通过官方支持的overrides参数直接补充CloudFormation资源属性，无需手动覆盖整个资源。
修改后的serverless.yml函数事件配置如下：

functions:
  my_websocket:
    handler: src/handler.handler
    description: My websocket
    events:
      - websocket:
          route: $default
          overrides:
            integration:
              ContentHandlingStrategy: CONVERT_TO_BINARY
            # 全局二进制媒体类型配置，仅需声明一次即可生效
            api:
              BinaryMediaTypes:
                - '*/*' # 可替换为实际需要的二进制媒体类型，如application/octet-stream
      - websocket:
          route: $connect
          overrides:
            integration:
              ContentHandlingStrategy: CONVERT_TO_BINARY
      - websocket:
          route: $disconnect
          overrides:
            integration:
              ContentHandlingStrategy: CONVERT_TO_BINARY

注意：api级别的BinaryMediaTypes属于WebSocket API全局配置，无需在每个路由事件下重复声明。

兼容方案：手动覆盖 CloudFormation 资源（适配所有 Serverless 版本） #

如果使用旧版Serverless无法使用overrides功能，可通过手动覆盖自动生成的CloudFormation资源实现配置，步骤如下：

• 执行serverless package，生成编译后的模板
• 打开.serverless/cloudformation-template-update-stack.json，确认两类资源的逻辑ID与原有属性：
  • WebSocket API根资源（默认逻辑ID为WebsocketsApi）
  • 各路由对应的Lambda集成资源（默认逻辑ID为Websockets{路由名帕斯卡命名}Integration，如$default对应WebsocketsDefaultIntegration）
• 在serverless.yml的resources.Resources块中，复制对应资源的原有属性，补充需要的二进制处理配置：

resources:
  Resources:
    # 为WebSocket API添加二进制媒体类型配置
    WebsocketsApi:
      Type: AWS::ApiGatewayV2::Api
      Properties:
        BinaryMediaTypes:
          - '*/*'
        # 需从生成的模板中复制原有全部属性，避免配置覆盖异常
        Name: ${self:service}-${sls:stage}
        ProtocolType: WEBSOCKET
        RouteSelectionExpression: $request.body.action

    # 为$default路由集成添加二进制转换策略
    WebsocketsDefaultIntegration:
      Type: AWS::ApiGatewayV2::Integration
      Properties:
        ContentHandlingStrategy: CONVERT_TO_BINARY
        # 需从生成的模板中复制原有全部属性
        ApiId: { Ref: WebsocketsApi }
        IntegrationType: AWS_PROXY
        IntegrationUri:
          Fn::Join:
            - ''
            -
              - 'arn:aws:apigateway:'
              - ${aws:region}
              - ':lambda:path/2015-03-31/functions/'
              - Fn::GetAtt: [MyWebsocketsLambdaFunction, Arn]
              - '/invocations'
        CredentialsArn:
          Fn::GetAtt: [IamRoleLambdaExecution, Arn]
        IntegrationMethod: POST

    # $connect、$disconnect路由的集成资源配置结构与上述一致，分别补充ContentHandlingStrategy属性即可

常见问题说明 #

• 现有serverless-apigw-binary、serverless-apigwy-binary插件仅适配REST API（API Gateway V1）的二进制处理逻辑，未支持WebSocket对应的V2资源结构，无法生效
• 直接在websocket事件下添加contentHandlingStrategy字段会触发Schema校验报错，是因为原生事件配置的Schema未暴露该字段，需通过overrides或资源覆盖的方式补充
• 部署完成后可通过AWS控制台查看对应WebSocket路由的集成配置，确认ContentHandlingStrategy已设置为CONVERT_TO_BINARY

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