VS Code中SAM Python调试报错：sam local start-api超时及选项异常

问题根源 #

旧电脑上的AWS SAM CLI版本过低，不支持VS Code SAM扩展自动生成的launch.json中使用的--listen参数，导致CLI执行命令失败，进而VS Code调试时因等待不到服务启动触发超时。

解决方法 #

方法1：升级AWS SAM CLI到最新版本 #

这是最彻底的解决方案，新版本SAM CLI原生支持--listen参数，和VS Code扩展配置兼容：

• macOS（Homebrew安装场景）：

  brew upgrade aws-sam-cli
  

• 其他系统/手动安装场景：
  运行官方安装脚本覆盖旧版本：

  curl -L https://github.com/aws/aws-sam-cli/releases/latest/download/install-sam-cli.pub | sudo tee /etc/pki/rpm-gpg/RPM-GPG-KEY-AWS-SAM-CLI
  curl -L https://github.com/aws/aws-sam-cli/releases/latest/download/aws-sam-cli-linux-x86_64.zip -o sam-cli.zip
  unzip sam-cli.zip -d sam-installation
  sudo ./sam-installation/install
  

  升级完成后，执行sam --version确认版本号，重启VS Code后即可正常调试。

方法2：修改launch.json适配旧版本SAM CLI #

如果暂时无法升级SAM CLI，手动调整调试配置，去掉不支持的--listen参数，改用旧版本调试逻辑：

1. 打开VS Code的.vscode/launch.json文件
2. 替换自动生成的配置为以下内容（适配Python Hello World项目）：

   {
       "version": "0.2.0",
       "configurations": [
           {
               "name": "SAM CLI: Hello World API",
               "type": "python",
               "request": "attach",
               "port": 5858,
               "host": "localhost",
               "preLaunchTask": "sam: local start-api",
               "justMyCode": true
           }
       ]
   }
   

3. 若无.vscode/tasks.json则新建，配置启动命令并添加调试端口参数：

   {
       "version": "2.0.0",
       "tasks": [
           {
               "label": "sam: local start-api",
               "type": "shell",
               "command": "sam local start-api -d 5858",
               "env": {
                   "PYTHONPATH": "${workspaceFolder}"
               },
               "problemMatcher": [],
               "isBackground": true,
               "presentation": {
                   "reveal": "always"
               }
           }
       ]
   }
   

4. 保存配置后重启调试，此时SAM会通过-d 5858开启调试端口，VS Code将连接该端口完成调试。

验证 #

先在CLI手动执行sam local start-api -d 5858，确认服务能正常启动后，再启动VS Code调试，即可解决超时和参数错误问题。

内容的提问来源于stack exchange，提问作者Elia Weiss