VS Code调试AWS SAM/Lambda/TypeScript项目的源映射配置问题

问题背景 #

通过sam init选择「Hello World Example TypeScript」模板生成项目后，出现如下调试异常：

• hello-world/tsconfig.json中sourceMap设为false，template.yaml里esbuild配置的Sourcemap设为true
• 执行sam build后，.aws-sam/build/HelloWorldFunction目录生成了app.js.map文件
• 两种调试方式均能执行Lambda，但无法命中断点：
  • 方式A：运行sam local invoke HelloWorldFunction -d 9999后通过VS Code的attach配置连接
  • 方式B：使用AWS Toolkit生成的direct-invoke配置直接调用
• 调试输出提示找不到hello-world下的app.js.map

使用环境：VS Code 1.81.0、AWS Toolkit 1.82.0、SAM CLI 1.94.0

解决方案 #

1. 统一Source Map配置 #

将hello-world/tsconfig.json中的sourceMap字段改为true，与template.yaml里esbuild的Sourcemap配置保持一致：

{
  "compilerOptions": {
    // ...其他配置
    "sourceMap": true
  }
}

TS编译器生成的source map是esbuild生成最终映射文件的基础，配置不一致会导致路径映射错乱。

2. 添加VS Code调试路径映射 #

在VS Code的.vscode/launch.json中，为attach或direct-invoke配置添加sourceMapPathOverrides字段，将Lambda运行环境的路径映射到本地项目路径：

{
  "configurations": [
    {
      // ...其他调试配置（attach或direct-invoke）
      "sourceMapPathOverrides": {
        "/var/task/app.js": "${workspaceFolder}/hello-world/app.ts",
        "/var/task/*": "${workspaceFolder}/hello-world/*"
      }
    }
  ]
}

Lambda运行时的代码根目录是/var/task，该配置会把map文件中指向/var/task的路径替换为本地hello-world目录的真实路径，让VS Code能正确定位TS源文件。

3. 确保ESBuild生成正确的外部Source Map #

在template.yaml的esbuild配置中添加SourcemapMode: external，强制生成独立的外部map文件（而非内嵌）：

Resources:
  HelloWorldFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: hello-world/
      Handler: app.lambdaHandler
      Runtime: nodejs18.x
      Metadata:
        BuildMethod: esbuild
        BuildProperties:
          Minify: true
          Sourcemap: true
          SourcemapMode: external # 添加这一行
          Target: "es2020"
          EntryPoints:
            - app.ts

验证步骤 #

1. 执行sam build重新编译项目
2. 检查.aws-sam/build/HelloWorldFunction/app.js.map中的sources字段，确认指向本地hello-world/app.ts
3. 重新启动调试，确认断点可以正常命中

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