AWS Lambda 远程调试 - AWS 适用于 VS Code 的工具包
Lambda 远程调试的工作原理开始使用访问 Lambda 远程调试使用 Lambda 远程调试故障排除与高级使用案例

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

AWS Lambda 远程调试

AWS Toolkit for Visual Studio Code 使您可以直接在 VS Code 中调试在云中运行的 AWS Lambda 函数。通过 AWS Lambda 远程调试，您可以检查正在运行的函数、设置断点、检查变量和逐步调试，而无需修改其现有开发工作流程。

以下各部分介绍如何在 AWS Toolkit for Visual Studio Code中使用 Lambda 远程调试。

Lambda 远程调试的工作原理

该 AWS 工具包支持远程调试，方法是使用额外的 Lambda 调试层临时修改您的 Lambda 函数，并将 Lambda 调用超时限制延长至 900 秒。通过 AWS IoT 安全隧道，您的本地调试器会与 Lambda 运行时环境之间建立一条安全连接。通过这条连接，您可以使用本地代码中的断点，对远程运行的函数进行逐步调试。调试会话结束后，所有临时修改都会被自动恢复到原始设置。

开始使用

支持的运行时

Lambda 远程调试支持以下运行时：

  • Python（Amazon Linux 2023）

  • Java

  • JavaScript/Node.js（亚马逊 Linux 2023）

先决条件

在您开始之前，必须满足以下先决条件。

  • 您必须在 AWS Toolkit 中配置有效的 AWS 凭据。有关安装 AWS Toolkit 和配置凭据的其他详细信息，请参阅本用户指南中的入门主题。

  • Lambda 函数已部署到您的 AWS 账户。有关部署 Lambda 函数的详细信息，请参阅《AWS Lambda开发人员指南》中的创建第一个 Lambda 函数主题。

  • 您必须拥有相应的 AWS Identity and Access Management (IAM) 策略和权限才能调试您的函数。有关 Lambda 权限的更多信息，请参阅《AWS Lambda开发人员指南》中适用于 AWS Lambda的AWS 托管式策略主题。以下是一个示例策略，包含在 AWS Toolkit 中使用 Lambda 远程调试所需的最低权限。

    注意

    远程调试是通过 AWS AWS IoT 安全隧道启用的。这可让您的本地调试器与 Lambda 运行时环境建立安全连接。

    
{
  "Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "lambda:ListFunctions",
        "lambda:GetFunction",
        "lambda:GetFunctionConfiguration",
        "lambda:GetLayerVersion",
        "lambda:UpdateFunctionConfiguration",
        "lambda:InvokeFunction",
        "lambda:PublishVersion",
        "lambda:DeleteFunction",
        "iot:CloseTunnel",
        "iot:OpenTunnel",
        "iot:RotateTunnelAccessToken",
        "iot:ListTunnels"
      ],
      "Resource": "*"
    }
  ]
}

访问 Lambda 远程调试

在 AWS 工具包中访问 Lambda 远程调试有两种主要路径： AWS 资源管理器或应用程序生成器资源管理器。在 AWS 资源管理器中，您可以通过节点访问 Lambda 远程调试。 AWS Lambda 在 Application Builder 浏览器中，您可以通过本地 AWS SAM 项目访问 Lambda 远程调试。

从资源管理器访问 Lambda 远程调试 AWS

  1. 在 VS Code 中，打开 AWS 工具包扩展。

  2. 在 AWS 工具包中，展开 AWS 资源管理器。

  3. 在浏览器中，展开 Lambda 节点。

  4. 找到您想调试的函数，然后在右键菜单中选择远程调用图标，以打开远程调用配置界面。

从 Application Builder 浏览器访问 Lambda 远程调试。

  1. 在 VS Code 中，打开 AWS 工具包扩展。

  2. 在 AWS 工具包中，展开应用程序生成器资源管理器。

  3. 在浏览器中，展开包含您想调试的 Lambda 项目的 AWS SAM 项目。

  4. 展开您想调试的已部署 Lambda 函数。

  5. 找到该函数的 remote 选项，然后在右键菜单中选择远程调用图标，以打开远程调用配置界面。

使用 Lambda 远程调试

以下各部分介绍如何在 AWS Toolkit for Visual Studio Code中使用 Lambda 远程调试。

注意

Lambda 函数最多支持 5 个层，并且函数代码和所有附加层的总大小不得超过 250MB。Lambda 远程调试需要至少保留 1 个空闲层才能运行。

设置调试会话

在开始之前，请按照以下步骤配置您的调试会话。

  1. 通过完成前一节中的 “从资源管理器访问 Lambda 远程调试” 或 “从应用程序生成 AWS 器资源管理器访问 Lambda 远程调试” 过程，打开远程调用配置菜单。

  2. 在远程调用配置菜单中，选中远程调试复选框以显示远程调试属性。

  3. 指定您的本地处理程序文件的本地根路径。

    注意

    本地根路径指的是与您已部署的 Lambda 函数相对应的本地源代码位置。如果您是从 Application Builder 浏览器中的已部署函数开始操作，本地根路径会自动检测。

    如果您在本地没有保存源代码，选择下载远程代码按钮来获取 Lambda 函数的源代码。这将在 VS Code 编辑器中打开您的 handler file。

  4. 在有效载荷部分，指定您的测试事件数据的来源。

设置断点并调试

按以下步骤设置断点并开始调试。

  1. 在 VS Code 编辑器中的 handler file 文件，单击行号旁的边距区域，即可在需要暂停调试的位置设置断点。

  2. 设置好断点后，返回远程调用配置菜单，确认您的设置是正确的，然后选择远程调用按钮开始调试。

  3. AWS Toolkit 使用调试功能更新您的 Lambda 函数，为调试会话建立安全隧道，使用指定的有效负载调用您的函数，然后在遇到断点时暂停该进程。

  4. 在断点暂停时，使用 RUN AND DEBUG 面板查看 VARIABLES、CALL STACK 和 BREAKPOINTS。

更新并测试您的函数

如需修改代码并通过快速部署测试变更，请按以下步骤执行操作。

  1. 在调试会话仍处于活动状态时，在 VS Code 编辑器中修改您的 handler file。

  2. 保存您的更改（Command+S on macOS，Ctrl+S on Windows）

  3. 出现提示时，确认您希望继续部署这些更改。该 AWS 工具包将使用修改后的代码更新您的 Lambda 函数。

  4. 设置新的断点，然后再次选择远程调用按钮，即可继续调试并测试您的变更。

    注意

    或者，您可以在 VS Code 调试控制中取消选中附加调试器选项，然后选择 远程调用按钮，让函数在无调试模式下运行。

结束调试会话

以下任一操作都会结束您的远程调试会话，并从项目中移除调试层。

  • 在远程调用配置界面选择移除调试设置选项。

  • 在 VS Code 调试控制栏中选择断开连接图标。

  • 在 VS Code 编辑器中关闭 handler file。

注意

记录以下内容：

  • Lambda 调试层会在 60 秒处于活动状态后自动移除。这个计时会在上一次调用完成时开始。

  • 如果您在调试过程中对 infrastructure-as-code (IaC) 托管 (AWS SAM,, AWS CDK, Terraform) 函数进行了代码更改，请将其保存到本地项目中，并考虑更新源代码控制存储库。未保存的更改会在 IaC 函数重新部署时被覆盖。

  • 如果您为了调试而进行了临时修改，则可能需要从源代码控制中重新部署函数，以确保其与生产环境中的代码保持一致。

故障排除与高级使用案例

如果您的调试会话失败，请按以下步骤开始故障排除：

  1. 将 AWS 工具包更新到最新版本。

  2. 关闭远程调用配置 Web 视图并重新打开，以刷新 Web 视图。

  3. 完全关闭 VS Code 后再重新打开它。

  4. 打开 VS Code 命令面板，输入命令 AWS: Reset Lambda Remote Debugging Snapshot，在结果中选择它，以重置 Lambda 远程调试快照。

  5. 如果您无法解决问题，请向 Issues 提交AWS Toolkit for Visual Studio Code GitHub问题。

高级使用案例：代码签名配置

远程调试需要向您的 Lambda 函数附加调试层。如果您的函数启用并强制执行了代码签名配置，则 AWS Toolkit 无法自动将调试层附加到您的函数。

您可以通过以下两种方式解决代码签名配置问题。

  • 暂时移除代码签名。

  • 使用已签名的调试层。

暂时移除代码签名。

提供设置 UntrustedArtifactOnDeployment : Warn 更新代码签名配置，在调试过程结束后再将其重置回 Enforced。

有关更多信息，请参阅 AWS Lambda API UpdateCodeSigningConfig参考中的参考资料。

使用已签名的调试层。

  1. 在 AWS 工具包的 Lambda 远程调试中，展开远程调试其他配置部分。

  2. 在远程调试附加配置部分中，从层覆盖字段复制您所在区域的层 ARN。

  3. 从中 AWS CLI，使用以下命令下载图层版本aws lambda get-layer-version-by-arn --arn layer-arn，用您的图层 ARN 替换 layer-arn。有关如何下载已签名的调试层的详细说明，请参阅《AWS CLI 命令参考》中的 get-layer-version-by-arn 参考。

  4. 使用您的代码签名配置对该层进行签名，并将其发布到您的账户。有关签名和发布指南，请参阅《AWS Serverless Application Model 开发人员指南》中的为您的 AWS SAM 应用程序设置代码签名主题。

  5. 在已签名的层成功发布到您的账户后，返回 Lambda 远程调试的远程调试附加配置部分，然后层覆盖字段中输入新的层 ARN。完成后，Lambda 远程调试将使用您签名的调试层，而不再使用默认层。

支持的区域

当某个区域不支持远程调试时，会出现以下错误。

Region ${region} doesn't support remote debugging yet

以下是受支持的区域列表。

  • ap-east-1

  • ap-northeast-1

  • ap-northeast-2

  • ap-south-1

  • ap-southeast-1

  • ap-southeast-2

  • ca-central-1

  • eu-central-1

  • eu-north-1

  • eu-west-1

  • eu-west-2

  • eu-west-3

  • me-central-1

  • me-south-1

  • sa-east-1

  • us-east-1

  • us-east-2

  • us-west-1

  • us-west-2

Lambda RequestEntityTooLargeException

Lambda 函数最多支持 5 个层，并且函数代码和所有附加层的总大小不得超过 250MB。远程调试层的大小约为 40MB。如果您的函数包较大或已附加多个层，这可能会导致总大小超出限制。有关更多详细信息，请参阅《AWS Lambda 开发者指南》中的 Lambda: InvalidParameterValueException 或 RequestEntityTooLargeException主题部分。

以下列表介绍了排查并解决此错误的一些方法。

  • 减小函数大小：优化函数的代码，移除不必要的依赖关系。

  • 移除未使用的层：在调试期间临时移除非必要层。

  • 使用外部依赖项：将较大的依赖项移至外部存储，例如 Amazon S3，并在运行时加载它们。

已超出 IoT 安全隧道配额

以下是在 Lambda 远程调试中达到 AWS IoT 安全隧道连接的每日限制时发生的隧道配额超出错误的示例。

Error creating/reusing tunnel: LimitExceededException: Exceeded quota of Lambda debugging tunnels

AWS IoT 安全隧道连接具有以下配额：

  • 免费层的 IoT 安全隧道每天最多分配 10 个连接。

  • 每个隧道支持一个 VS Code 实例，最长 12 小时。

  • 配额适用于每个 AWS 账户、每天。

如果您遇到 AWS IoT 安全隧道错误，请等待每日配额重置或联系 AWS 支持部门申请提高配额限制。有关 AWS 支持联系人信息，请访问AWS 支持联系人门户。有关 AWS IoT 安全隧道的详细信息，请参阅《开发人员指南》中的AWS IoT 安全隧道主题。AWS IoT

使用源映 TypeScript 射调试 Lambda 函数

以下各节介绍如何使用源映射调试 TypeScript Lambda 函数。

先决条件

要调试您的 TypeScript Lambda 函数，必须满足以下先决条件。

  • 您 TypeScript 必须遵守启用的源地图选项。有关更多信息，请参阅 VS Code 文档中的JavaScript 源映射支持主题。

  • 如果使用内嵌的源映射，所有更改都必须重新部署到云中。

配置

要为 AWS 工具包中的 Lambda 函数配置 L TypeScript ambda 远程调试，请完成以下步骤。

  1. 在 AWS 工具包中，展开 AWS 资源管理器。

  2. 在浏览器中，展开 Lambda 节点。

  3. 导航到要为其配置的功能 TypeScript，然后从上下文菜单中选择 “远程调用” 图标以打开 “远程调用” 配置屏幕。

  4. 选中远程调试复选框以启用远程调试。

  5. 通过指向包含 TypeScript handler file 的目录来配置您的本地根路径。

    注意

    TypeScript handler file 是您设置调试断点的位置。

  6. 展开远程调试附加配置设置。

  7. 选中源映射复选框来启用源映射。

  8. 将输出文件字段设置为您的 Lambda 函数副本所在的本地目录。

    如果 app.js 和 app.map 位于 .aws-sam/build/HelloWorldFunction 中，则将输出文件位置为 /Users/user/project/aws-sam/build/HelloWorldFunction/*。

    注意

    输出文件路径应为绝对路径。

  9. 如果您对设置感到满意，请选择 “远程调用” 按钮开始调试您的 TypeScript 函数。