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

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

AWS Lambda 远程调试

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

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

Lambda 远程调试的工作原理

该 AWS 工具包支持远程调试，方法是使用额外的 Lambda 调试层临时修改您的 Lambda 函数，并将 Lambda 调用超时限制延长至 900 秒。 AWS IoT 使用安全隧道在您的本地调试器和 Lambda 运行时环境之间建立安全连接。此连接允许您在远程执行函数时使用本地代码断点来逐步执行该函数。调试会话完成后，所有临时修改都将自动恢复为其原始设置。

开始使用

支持的运行时

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

  • Python（亚马逊 Linux 2023）

  • Java

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

先决条件

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

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

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

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

    注意

    远程调试是通过 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 在应用程序生成器资源管理器中，您可以通过本地 AWS SAM 项目访问 Lambda 远程调试。

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

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

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

  3. 在资源管理器中，展开 Lambda 节点。

  4. 导航到要调试的函数，然后从上下文菜单中选择 “远程调用” 图标以打开 “远程调用” 配置屏幕。

从应用程序生成器资源管理器访问 Lambda 远程调试。

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

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

  3. 从资源管理器中AWS SAM展开包含要调试的 Lambda 项目的项目。

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

  5. 导航到功能遥控器，然后从上下文菜单中选择 “远程调用” 图标以打开 “远程调用” 配置屏幕。

使用 Lambda 远程调试

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

注意

Lambda 函数有 5 层限制，函数代码和所有附加层的组合限制为 250MB。Lambda 远程调试需要至少 1 个空闲层才能运行。

设置调试会话

在开始之前，请完成以下步骤来配置调试会话。

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

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

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

    注意

    本地根路径是与已部署的 Lambda 函数相匹配的源代码的位置。如果您使用的是 Application Builder 资源管理器中已部署的函数，则会自动检测您的本地根路径。

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

  4. 在 P ayload 部分中，指定获取测试事件数据的位置。

设置断点和调试

设置断点并通过完成以下过程开始调试。

  1. handler file在 VS Code 编辑器中，单击装订线边距，在要暂停调试的行号处设置断点。

  2. 如果您对断点感到满意，请返回远程调用配置菜单以验证您的设置配置是否正确，然后选择远程调用按钮开始调试。

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

  4. 在断点暂停时，使用 “运行和调试” 窗格查看您的变量、调用堆栈和断点。

更新和测试你的函数

要修改您的代码并通过快速部署测试更改，请完成以下步骤。

  1. 激活调试会话后，在 VS Code 编辑器handler file中对您的会话进行更改。

  2. 保存您的更改 (Command+S on macOS,Ctrl+S on Windows)

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

  4. 通过设置新的断点并再次选择 “远程调用” 按钮，继续调试和测试您的更改。

    注意

    或者，您可以在 VS Code 调试控件中取消选择 “连接调试器” 选项，然后选择 “远程调用” 按钮，无需调试即可运行您的函数。

结束调试会话

以下每个选项都会结束远程调试会话并从项目中移除调试层。

  • 从 “远程调用配置” 屏幕中选择 “删除调试设置” 选项。

  • 从 VS Code 调试控件中选择断开连接图标。

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

注意

记录以下内容：

  • 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，并在运行时加载它们。

已超出物联网安全隧道配额

以下是在 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. 将 Ou t files 字段设置为 Lambda 函数副本的本地目录。

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

    注意

    Out 文件路径应为绝对路径。

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