WebStorm使用Serverless调试本地Node.js Lambda函数断点不触发问题

问题场景 #

基于Node.js开发AWS Lambda函数，使用Serverless Framework + serverless-offline插件做本地模拟，IDE为WebStorm。服务启动后发送请求可正常收到响应，但代码中设置的断点完全不触发，调试流程未生效。

现有配置 #

serverless.yml #

service: applicationsync
frameworkVersion: '3'
provider:
  name: aws
  runtime: nodejs12.x

plugins:
  - serverless-offline

functions:
  hello:
    handler: index.handler
    events:
      - http:
          path: hello
          method: get
      - http:
          path: hello

package.json #

{
  "name": "applicationsync",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "start": "./node_modules/.bin/serverless offline -s dev",
    "debug": "set SLS_DEBUG=* && node --inspect /usr/lib/node_modules/serverless/bin/serverless offline -s dev"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "serverless-offline": "^8.8.0"
  },
  "dependencies": {
    "aws-sdk": "^2.1170.0",
    "mysql": "^2.18.1"
  }
}

问题根因 #

1. 当前debug启动脚本仅给Serverless主进程添加了--inspect调试参数，serverless-offline默认会通过独立进程/工作线程运行Lambda业务代码，子进程不会继承主进程的调试配置，调试器实际没有挂载到运行业务代码的进程上，断点自然无法命中。
2. 脚本直接调用全局路径下的Serverless二进制文件，容易和项目本地依赖的版本、插件路径不匹配，导致调试参数传递失效。
3. 未关闭Lambda默认超时机制，调试过程中进程可能提前退出，且默认开启的工作线程模式对Inspector调试协议兼容性差。

修复步骤 #

• 第一步：修改package.json中的debug启动脚本
  替换原有debug脚本为以下配置，使用项目本地依赖的Serverless，同时给Lambda执行进程开启调试，关闭超时和不兼容的工作线程模式：

  "scripts": {
    "start": "./node_modules/.bin/serverless offline -s dev",
    "debug": "set SLS_DEBUG=* && node --inspect=9229 ./node_modules/serverless/bin/serverless offline -s dev --noTimeout --inspect=9229 --useWorkerThreads false"
  }
  

  如果使用PowerShell或Mac/Linux环境，把命令开头的set SLS_DEBUG=* && 替换为对应环境的环境变量设置语法即可。
• 第二步：配置WebStorm调试连接
  不要直接使用NPM脚本旁的debug按钮启动，手动添加Attach to Node.js/Chrome类型的调试配置：
  • 调试端口设置为9229
  • 勾选「自动重连」选项
  • 先通过终端执行npm run debug启动服务，等控制台输出Debugger listening on ws://127.0.0.1:9229/xxx日志后，再启动刚才创建的Attach调试配置，控制台出现Debugger attached提示即为连接成功。
• 第三步：补全serverless.yml的冗余配置（可选但建议）
  当前配置中第二个http事件缺失method字段，虽然不影响调试，但建议补全避免路由匹配异常；也可以在provider块中固定stage配置减少参数冲突。

验证方式 #

在index.js的handler函数中打行断点，发送请求到本地服务地址http://localhost:3000/dev/hello，断点会正常命中，可正常使用单步执行、变量查看、调用栈追踪等调试能力。

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