AWS Toolkit for VS Code是必备插件，需配合AWS SAM CLI（≥1.100.0）、Docker及Serverless CLI（v3+）使用，通过正确配置handler路径与launch.json端口（如9999），才能实现F5触发、断点调试Lambda函数的本地开发环境。
能直接断点调试、看到 event 和 context 结构、改完代码按一次 F5 就触发，不是靠 console.log + 重部署猜逻辑——这才是真正可用的本地调试环境。关键不在装多少插件，而在三处对齐：运行时行为、调试协议、路径解析。
必须装对的三个 CLI 工具和一个插件
缺任何一个，sls offline 启不起来，或者 sam local invoke 报找不到运行时，或者 VS Code 连不上进程。
-
aws-sam-cli（不是serverlessCLI）：AWS 官方模拟器，支持完整 Lambda 运行时层（含 /var/task 挂载、/tmp 权限、环境变量注入），sam local invoke和sam local start-api都依赖它；必须用sam --version验证已安装且 ≥1.100.0 -
serverlessCLI（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 有用得多。
