localstack 无法调试 lambda，因其不支持调试协议、不注入 event/context 且无真实运行时生命周期；必须改用 sam cli 容器模式 + docker 网络桥接，在 amazon linux 镜像中运行函数并暴露调试端口。
不能直接用 LocalStack 调试 Lambda——它不提供调试协议支持，也不注入 context、event 或真实运行时生命周期。所谓“本地无公网运行 + 深度调试”，必须绕过 LocalStack 的 Lambda 模拟层，改用 SAM CLI 容器模式 + Docker 网络桥接，让函数在 Amazon Linux 镜像中运行，同时暴露调试端口。
LocalStack 的 lambda 服务根本不支持 attach 调试
LocalStack 启动的 lambda 服务（如 localstack/localstack 镜像里的）只做 HTTP 接口转发和基础调用封装，底层实际用的是 mock 执行器或轻量沙箱，没有 V8 inspector（Node.js）或 ptvsd/debugpy（Python）集成。你设断点、开 --debug-port、配 launch.json，VS Code 连不上任何进程。
- 现象：
sls invoke local -f myfunc或aws lambda invoke --function-name myfunc --payload '{...}' --endpoint-url http://localhost:4566能返回结果，但 VS Code 始终提示 “Cannot connect to runtime process” - 根本原因：LocalStack 的 Lambda 不启动调试 agent，也不监听
9229/5678等端口 - 替代方案不是“修 LocalStack”，而是换执行引擎——用
sam local invoke替代aws lambda invoke --endpoint-url
sam local invoke 必须走 Docker 并显式开调试端口
sam local invoke 默认用容器跑，但调试端口默认不暴露。你得加 --debug-port 并确保 Docker 容器端口映射到宿主机，否则 VS Code attach 不上。
- Node.js 示例命令：
sam local invoke "MyFunction" -e event.json --debug-port 9229 --docker-network host（Linux/macOS）或--docker-network bridge（Windows WSL） - Python 示例：
sam local invoke "MyFunction" -e event.json --debug-port 5678 --docker-network host，且 handler 文件里要提前插入import debugpy; debugpy.listen(5678) - 关键参数：
--docker-network决定容器能否被宿主机访问；host模式下端口直通，bridge模式需额外加--docker-volume-basedir和端口映射规则 - 常见坑：没加
--debug-port就去 VS Code 里点 Attach，连失败都不报错，只是断点灰掉
VS Code launch.json 必须匹配 SAM 的调试协议和路径
用 "type": "node" 或 "type": "python" 是对的，但 remoteRoot 和 localRoot 必须对齐容器内路径——SAM 默认把代码挂载到 /var/task，不是项目根目录。
- Node.js 正确配置片段：
{ "type": "node", "request": "attach", "name": "Attach to SAM Node", "port": 9229, "address": "localhost", "localRoot": "${workspaceFolder}", "remoteRoot": "/var/task", "sourceMaps": true, "outFiles": ["${workspaceFolder}/.aws-sam/build/**/dist/**/*.js"] } - Python 注意点：
remoteRoot仍为/var/task，但需确认debugpy版本兼容容器内 Python（AL2023 镜像用 Python 3.11，debugpy 才稳定） - 绝对不要写
"type": "aws-sam"：那是给 Toolkit 自动触发sam local invoke用的，不适用于手动 attach 场景 - 路径错误的典型表现：断点打上去是空心圆，hover 提示 “Breakpoint ignored because generated code not found”
LocalStack 只能当事件源网关，别让它碰函数执行
LocalStack 最有价值的角色是模拟 API Gateway、S3、SQS 等触发器——你让它收请求、发事件，再把事件转给 sam local start-api 或 sam local invoke 处理，这样既“无公网”，又保真调试。
- 推荐架构：
curl http://localhost:4566/restapis/xxx/local/_user_request_→ LocalStack APIG → 转发 JSON 到http://localhost:3000/2015-03-31/functions/MyFunction/invocations（由sam local start-api提供） - 关键操作：启动
sam local start-api --docker-network host --debug-port 9229，再启动 LocalStack，并在template.yaml里把Events指向 LocalStack 的 endpoint - 好处：事件结构完全真实（含
requestContext、headers），函数仍在 SAM 容器里执行，断点、变量检查、堆栈全可用 - 忽略这点就等于放弃调试价值——只图“本地运行”，却丢了上下文、权限、时区、/tmp 行为等关键要素
真正卡住人的从来不是“能不能连上”，而是没意识到 LocalStack 和 SAM CLI 是分工关系：一个管“怎么来”，一个管“怎么跑”。混用或强求 LocalStack 承担执行职责，只会陷入端口不通、路径错位、context 缺失的三重静默失败。
