VSCode launch.json调用SAM本地API网关超时问题求助

API 探路者

2026-10-20

问题根因

该问题仅出现在VSCode AWS Toolkit调用场景、命令行直接执行SAM命令正常，核心是Toolkit与SAM本地进程的交互链路异常，常见原因如下：

AWS Toolkit默认SAM启动超时阈值过低，Windows环境下Docker容器启动耗时普遍偏高，默认30秒超时不足以完成整个启动流程
SAM本地进程启动时默认绑定IPv6地址::1，而AWS Toolkit默认尝试连接IPv4地址127.0.0.1，导致连接被拒绝
AWS Toolkit中配置的SAM CLI可执行文件路径异常，或路径包含空格、中文等特殊字符导致进程启动后异常退出
Windows Defender防火墙拦截了VSCode对本地SAM服务端口的访问请求

解决步骤

1. 调整启动超时配置

在launch.json的sam配置节点中添加超时参数，将超时时间拉长到120秒适配Windows环境的启动速度：

"sam": {
  "invokeTimeoutMs": 120000
}

也可以直接在VSCode全局设置中搜索aws.samcli.debug.invokeTimeout，修改全局默认超时值。

2. 强制SAM绑定IPv4地址

在sam配置节点中添加启动参数，指定SAM服务绑定IPv4本地地址，避免IPv4/IPv6适配问题：

"sam": {
  "invokeTimeoutMs": 120000,
  "localArguments": ["--host", "127.0.0.1"]
}

3. 校验SAM CLI路径配置

打开VSCode设置页面，搜索aws.samcli.location，确认配置的路径是SAM CLI的实际安装路径，Windows环境默认路径为C:\Program Files\Amazon\AWSSAMCLI\bin\sam.exe。如果路径包含空格、中文等特殊字符，建议重新安装SAM CLI到无特殊字符的目录，或在配置中用英文双引号包裹完整路径。

4. 排查端口占用与防火墙规则

执行命令netstat -ano | findstr :5858确认报错中提到的5858端口未被其他进程占用，若被占用可在localArguments中添加["-p", "空闲端口号"]指定其他端口启动
暂时关闭Windows Defender防火墙测试，确认是否是拦截导致的连接失败，验证通过后添加VSCode和SAM CLI的入站规则即可。