如何使用VSCode调试TypeScript项目中的SAM Local API？

核心问题分析 #

你遇到的断点未生效、调试会话30秒终止，主要原因是SAM Local未启动调试模式，且容器默认冷启动后快速退出，导致VSCode调试器无法持续连接；另外原launch.json存在协议或配置匹配问题。

分步解决方案 #

1. 确保TypeScript生成Source Maps #

检查tsconfig.json，开启source map生成（这是VSCode映射TS断点到JS执行代码的核心）：

{
  "compilerOptions": {
    "sourceMap": true,
    "outDir": "./dist",
    // 其他项目配置...
  }
}

重新编译项目，确认dist目录下生成对应.js.map文件。

2. 启动带调试参数的SAM Local API #

执行以下命令启动SAM，开启调试模式并保持容器活跃：

sam local start-api --debug-port 9229 --warm-containers LAZY

• --debug-port 9229：指定容器内Node.js调试器监听端口（Node.js 8+默认使用Inspector协议，该端口比旧的5858协议更稳定），端口会自动映射到本地同端口。
• --warm-containers LAZY：让容器在首次调用后保持运行，避免调试会话因容器退出而中断（解决你遇到的30秒终止问题）。

3. 修正VSCode的launch.json配置 #

替换原配置为以下内容，确保与SAM调试参数匹配：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to SAM Local API",
      "type": "node",
      "request": "attach",
      "address": "localhost",
      "port": 9229,
      "localRoot": "${workspaceFolder}",
      "remoteRoot": "/var/task",
      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
      "sourceMaps": true,
      "protocol": "inspector",
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

• protocol: "inspector"：明确使用Node.js现代调试协议，避免与旧协议冲突。
• skipFiles：跳过Node.js内部文件，聚焦业务代码调试。

4. 调试流程 #

1. 执行上述sam local start-api命令，等待控制台输出Waiting for debugger to attach...提示。
2. 在VSCode「运行和调试」面板选择Attach to SAM Local API并启动调试会话。
3. 用Postman调用API接口，VSCode中设置的TS断点会自动触发。

关键参数说明 #

• --debug-port：核心参数，指定容器内调试器的监听端口，VSCode调试配置必须与该端口一致才能建立连接。
• --debugger-path：仅当需要替换容器内默认Node.js调试器时使用（如自定义调试工具），常规TypeScript项目无需配置，使用默认值即可。

常见问题排查 #

• 断点未触发：检查outFiles路径是否正确指向编译后的JS文件，确保source map文件与JS文件在同一目录。
• 连接失败：确认SAM启动的--debug-port与launch.json中的port完全一致，且本地端口未被占用。

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