因为sam cli默认在当前目录查找template.yaml，若模板位于infra/等子目录则报错；需用--template显式指定路径，且函数名必须为模板中定义的logicalid。
为什么直接运行 sam local invoke 会报 “Template file not found”？
因为 SAM CLI 默认在当前目录找 template.yaml，而很多 Serverless 项目把模板放在 infra/ 或 aws/ 子目录里。不指定路径就失败。
- 运行前先确认模板位置：
find . -name "template.yaml" -o -name "template.yml" - 显式传入路径：
sam local invoke --template infra/template.yaml HelloWorldFunction - 如果函数名带命名空间（如
MyStack-HelloWorldFunction-ABC123），别直接抄 CloudFormation 输出里的全名——sam local invoke只认LogicalId，也就是模板里Resources下定义的键名
VSCode 调试 Lambda 函数时，breakpoint 不生效怎么办？
常见原因是启动调试器时没挂载源码路径，或者 Python/Node.js 运行时没启用调试支持。
- Python 项目必须在
sam build后用--debug-port启动：sam local invoke --debug-port 5858 --debugger-path ./debugger/ --container-env-var PYTHONPATH=/var/task - Node.js 需在
package.json的scripts中确保入口文件用node --inspect-brk启动，且sam local invoke加--skip-pull-image避免覆盖调试镜像 - VSCode 的
launch.json中request必须是attach，不是launch；端口要和--debug-port一致；localRoot和remoteRoot必须严格匹配容器内路径（如/var/task）
sam build 报错 “Failed to build docker image” 怎么快速定位？
本质是构建上下文或 Dockerfile 写法与 SAM 默认行为冲突，不是环境没装 Docker。
- 先加
--debug参数看完整日志：sam build --debug，重点关注最后一段红字错误和docker build命令本身 - 常见陷阱：自定义
Dockerfile里用了COPY . /var/task，但 SAM 构建时实际工作目录是.aws-sam/build/FunctionName，不是项目根目录 - 若用
Image类型函数，确保Metadata下的DockerTag是合法字符串（不能含下划线、大写字母） - 临时绕过：加
--use-container=false用本地构建（仅限 Python/Node.js 等支持本地打包的语言）
本地测试 API Gateway 事件时，event.json 怎么写才不会触发 KeyError: 'pathParameters'？
SAM 模拟的 API Gateway 事件结构严格遵循真实事件格式，漏字段或嵌套错层级就会出 Key 错误。
- 不要手写，用
sam local generate-event生成基础模板：sam local generate-event apigateway aws-proxy > event.json - 如果函数定义了
Path（如/users/{id}），必须手动补全："pathParameters": {"id": "123"}，否则event['pathParameters']就是None而非空 dict - 注意
multiValueHeaders和multiValueQueryStringParameters是可选字段，但一旦出现就必须是 list 类型，不能是 null 或 string
template.yaml 的 CodeUri 却忘了同步更新 sam build 的输入路径。
