必须装齐aws toolkit for vs code、sam cli（≥1.100.0）、docker和serverless cli v3+（若用serverless.yml），缺一则sam local invoke报module_not_found或断点不触发；handler路径须严格匹配约定，launch.json中type必须与启动方式一致（推荐"aws-sam"）。
调试前必须装齐这四个东西
缺任何一个，sam local invoke 会报 MODULE_NOT_FOUND，或者断点完全不触发——不是代码问题，是环境没对齐。
-
AWS Toolkit for VS Code：必装，不是可选。它生成.vscode/launch.json、读取~/.aws/credentials、右键菜单全靠它 -
sam cli（≥1.100.0）：运行sam --version验证。它是唯一能挂载/var/task、注入真实context和环境变量的模拟器 -
docker：SAM 默认用容器跑 Amazon Linux 镜像。不装 Docker 会 fallback 到 mock 模式，但二进制依赖、/tmp权限、时区全不对 -
serverless CLI v3+（仅当你用serverless.yml）：sls offline启动失败？先sls --version看是不是 v3.x；v2 不兼容新 handler 解析逻辑
handler 路径写错，VS Code 绝不报错但调试必挂
这是最隐蔽的坑：路径多一个点、少一个斜杠，sam local invoke 仍返回 200，函数却根本没加载，断点永远不命中。
- Node.js 示例：handler 必须写成
src/handlers/hello.handler，不能写./src/handlers/hello.handler（开头的.会让 SAM 在容器内找/var/task/./src/） - Python 示例：写成
app.lambda_handler，不是app.py::lambda_handler或./app.lambda_handler - 如果
serverless.yml在子目录（比如packages/api/serverless.yml），得显式配package.patterns包含 handler 文件，否则打包时漏掉 - 用
Serverless IDE插件校验路径，但得手动启用：右键serverless.yml→ “Validate Serverless Configuration”
launch.json 里 type 填 "aws-sam" 还是 "node"
填错类型会导致 VS Code 连不上进程——不是端口冲突，是调试协议压根不匹配。
- 用
"type": "aws-sam"（推荐）：右键template.yaml→ “Debug Locally”，Toolkit 自动调sam local invoke --debug-port 9999，VS Code 直接 attach - 用
"type": "node"（仅限serverless-offline）：配runtimeExecutable指向sls，runtimeArgs加offline，但context是 mock 的，/tmp权限和真实 Lambda 不一致 - 混用必失败：比如 launch.json 用
"node"类型，却去右键 template.yaml 调 “Debug Locally”，VS Code 找不到进程 PID
本地调试 ≠ 执行 handler 函数体
只跑 node src/handlers/hello.js 或 python app.py，看到 console.log 就以为通了？那只是函数入口，不是 Lambda 生命周期。
- 真正调试要触发完整链路：事件注入（API Gateway proxy event / S3 event）、
context构造（含getRemainingTimeInMillis）、超时控制、层加载、环境变量生效 - 单次调用：右键
template.yaml→ “AWS: Invoke SAM Application Locally”，选预设事件模板（如 API Gateway HTTP POST），输入 JSON 查看完整event结构 - HTTP 接口调试：终端运行
sam local start-api，访问http://localhost:3000/dev/hello，断点才会被 API Gateway 请求触发 - 注意：Docker 容器里
process.env和本地终端不一样，所有环境变量必须在template.yaml的Environment.Variables下定义，不能靠.env文件
sam 如何解析 CodeUri 和 Handler 字符串、docker 是否真挂载了源码路径、以及 launch.json 的 type 是否和启动方式严格对应——这三个点任意一个偏移，断点就成摆设。
