如何设置VSCode进行AWS Lambda本地Serverless调试？

本文共计1252个文字，预计阅读时间需要6分钟。

可以直接通过断点调试、查看 `event` 和 `context` 结构、修改代码后按 F5 运行来即时看到效果，而不是依赖 `console.log` 重载部署。这样才是真正的本地调试环境。关键不在于安装多少插件，而在于对运行时行为、调试协议和路径解析的深入理解。

必须装对的三个 CLI 工具和一个插件

缺任何一个，sls offline 启不起来，或者 sam local invoke 报找不到运行时，或者 VS Code 连不上进程。

• aws-sam-cli（不是 serverless CLI）：AWS 官方模拟器，支持完整 Lambda 运行时层（含 /var/task 挂载、/tmp 权限、环境变量注入），sam local invoke 和 sam local start-api 都依赖它；必须用 sam --version 验证已安装且 ≥1.100.0
• serverless CLI（v3+）：如果你用的是 serverless.yml 而非 template.yaml，它负责加载插件、解析 functions.*.handler；运行 sls --version 确认是 v3.x
• docker：SAM CLI 默认用 Docker 运行真实 Amazon Linux 容器镜像，不装 Docker 会 fallback 到 mock 模式，但很多底层行为（如二进制依赖、权限、时区）不一致
• AWS Toolkit for VS Code：不是可选，是必装。它把 sam 命令封装成右键菜单和调试配置，自动生成 .vscode/launch.json，还能直接读取 ~/.aws/credentials 中的 profile

serverless.yml 里 handler 路径写错，VS Code 不报错但调试必失败

VS Code 的 Serverless IDE 插件能校验路径，但很多人没装，或装了却没启用。结果 sls offline 启动成功，HTTP 请求也返回 200，但断点永远不命中——因为函数根本没加载。

• functions.hello.handler 必须是 Node.js 可 require() 的相对路径，带文件后缀：src/handlers/hello.js ✅，src/handlers/hello ❌（Node.js 默认不解析 .js）
• 路径基于 service 字段所在目录，不是 projectRoot；如果 serverless.yml 在子目录，得用 package.patterns 显式包含 handler 文件
• 别信 “自动补全”：有些插件会把 src/handlers/hello.js 补全成 ./src/handlers/hello.js，多出来的 . 会让 SAM CLI 在容器内找 /var/task/./src/...，直接 MODULE_NOT_FOUND

launch.json 配 type: "node" 还是 "aws-sam"？看你怎么启动

两种方式都可行，但混用会连不上。核心区别是：谁控制进程生命周期、谁暴露 --inspect 端口。

• 用 aws-sam 类型（推荐）：在 .vscode/launch.json 里配 "type": "aws-sam"，然后右键 template.yaml → “Debug Locally”。AWS Toolkit 自动调 sam local invoke 并加 --debug-port 9999，VS Code 直接 attach，不用手动开终端
• 用 node 类型（适合 serverless-offline）：配 "type": "node", "request": "attach", "port": 9229，然后终端手动跑 sls offline --debug（注意不是 --debug-port，v10+ 默认禁用 inspect，必须显式加 --inspect）
• 端口不匹配就白搭：aws-sam 默认用 9999，serverless-offline 默认用 9229，launch.json 里的 port 必须跟命令行参数一致

断点不触发？先确认是不是被“冷启动”绕过了

本地调试最常被忽略的一点：Lambda 是事件驱动的，不是服务一启就停在第一行。VS Code 的断点只在函数实际执行时生效。

• 用 sam local start-api 时，得发 HTTP 请求（比如 curl http://localhost:3000/dev/hello）才会触发 handler，断点才激活
• 用 sam local invoke 时，得传测试事件（sam local invoke -e event.json），空事件或格式错会导致函数直接退出，断点跳过
• 如果用了 serverless-offline，确保没漏掉 --noAuth（否则 403 拦截请求，函数根本没执行）
• 检查终端输出：看到 Debugger attached 或 Listening on port 3000 ≠ 断点就绪，得看到 Invoking src/handlers/hello.js 这类日志才表示 handler 已加载

真正卡住的地方，往往不是插件没装全，而是 handler 路径和 launch.json 端口这两处细节没对齐。SAM CLI 的日志默认不显示详细错误，加 --debug 参数再跑一次，比反复重启 VS Code 有用得多。