如何本地调试AWS API Gateway WebSocket并模拟其行为测试Lambda

作为天天和AWS Serverless打交道的开发者，我太懂每次改完代码要部署才能测试的痛苦了！下面分享两种靠谱的本地调试方案，既能完整模拟WebSocket Gateway的行为，又能直接调试Lambda逻辑，完全不用频繁部署到云端。

一、用AWS SAM CLI完整模拟WebSocket Gateway + 本地调试Lambda #

AWS SAM（Serverless Application Model）是官方推出的工具，专门用来本地开发、调试Serverless应用，对WebSocket的支持非常完善，是我日常调试的首选。

步骤1：准备SAM模板文件（template.yaml） #

先写一个包含WebSocket API和关联Lambda的模板，示例如下：

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: Local WebSocket Debugging Demo

Resources:
  MyWebSocketApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: prod
      ProtocolType: WEBSOCKET
      RouteSelectionExpression: "$request.body.action"

  OnConnectFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: ./src/
      Handler: onconnect.handler
      Runtime: nodejs18.x
      Events:
        ConnectEvent:
          Type: Api
          Properties:
            RestApiId: !Ref MyWebSocketApi
            Path: /
            Method: GET
            ConnectionType: WEBSOCKET

  DefaultMessageFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: ./src/
      Handler: default.handler
      Runtime: nodejs18.x
      Events:
        DefaultEvent:
          Type: Api
          Properties:
            RestApiId: !Ref MyWebSocketApi
            Path: /default
            Method: POST
            ConnectionType: WEBSOCKET

步骤2：启动本地WebSocket服务 #

在项目根目录执行命令：

sam local start-websocket-api

启动成功后，你会得到一个本地WebSocket端点，比如 ws://localhost:3001。

步骤3：测试WebSocket连接与消息 #

用wscat（先通过npm install -g wscat安装）来测试连接和消息：

wscat -c ws://localhost:3001

连接成功后，发送消息（比如{"action": "default", "message": "hello local"}），就能触发对应的Lambda函数了。

步骤4：断点调试Lambda #

如果需要单步调试Lambda逻辑，启动服务时加上调试端口：

sam local start-websocket-api --debug-port 5858

然后在VS Code里配置launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to SAM Local",
      "type": "node",
      "request": "attach",
      "address": "localhost",
      "port": 5858,
      "localRoot": "${workspaceFolder}/src",
      "remoteRoot": "/var/task",
      "protocol": "inspector"
    }
  ]
}

设置好断点，发送消息后就能触发调试，一步步看代码执行逻辑了。

二、单独本地测试WebSocket Lambda函数（无需启动Gateway） #

如果只是想单独验证Lambda的业务逻辑，不需要完整的Gateway流程，可以直接用sam local invoke来模拟Gateway的WebSocket事件。

步骤1：准备事件模拟文件（event.json） #

创建一个模拟WebSocket请求的JSON文件，示例：

{
  "requestContext": {
    "connectionId": "test-connection-id",
    "domainName": "localhost",
    "stage": "prod"
  },
  "body": "{\"action\": \"default\", \"message\": \"test local lambda\"}"
}

步骤2：本地调用Lambda #

执行命令：

sam local invoke DefaultMessageFunction --event event.json

这样就能直接运行Lambda函数，输出结果会打印在控制台，同样可以结合--debug-port参数进行断点调试。

额外小贴士 #

• 本地环境变量：可以创建env.json文件定义Lambda的环境变量，启动服务时用--env-vars env.json加载。
• 热重载：SAM支持--warm-containers EAGER参数，修改Lambda代码后无需重启服务，会自动重载，效率提升很多。

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