本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 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 + Typescript/JavaScript/Node.js（亚马逊 Linux 2023） **注意** Lambda 远程调试不支持 Lambda 托管实例和 OCI 图像函数类型。 ### 先决条件 在您开始之前，必须满足以下先决条件。 + 您必须在 AWS Toolkit 中配置有效的 AWS 凭据。有关安装 AWS Toolkit 和配置凭据的更多详细信息，请参阅本用户指南中的[入门](https://docs.aws.amazon.com//toolkit-for-vscode/latest/userguide/setting-up.html)主题。 + Lambda 函数已部署到您的 AWS 账户。有关部署 Lambda 函数的详细信息，请参阅《AWS Lambda开发人员指南》**中的[创建第一个 Lambda 函数](https://docs.aws.amazon.com//lambda/latest/dg/getting-started.html)主题。 + 您必须拥有相应的 AWS Identity and Access Management (IAM) 策略和权限才能调试您的函数。有关 Lambda 权限的更多信息，请参阅《AWS Lambda开发人员指南》**中[适用于 AWS Lambda的AWS 托管式策略](https://docs.aws.amazon.com//lambda/latest/dg/security-iam-awsmanpol.html)主题。以下是一个示例策略，包含在 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: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 工具包扩展。 1. 在 AWS 工具包中，展开 AWS 资源管理器。 1. 在浏览器中，展开 **Lambda** 节点。 1. 找到您想调试的函数，然后在右键菜单中选择**远程调用**图标，以打开**远程调用配置**界面。 **从 Application Builder 浏览器访问 Lambda 远程调试。** 1. 在 VS Code 中，打开 AWS 工具包扩展。 1. 在 AWS 工具包中，展开应用程序生成器资源管理器。 1. 在浏览器中，展开包含您想调试的 Lambda 项目的 `AWS SAM` 项目。 1. 展开您想调试的已部署 `Lambda` 函数。 1. 找到该函数的 remote 选项，然后在右键菜单中选择**远程调用**图标，以打开**远程调用配置**界面。 ## 使用 Lambda 远程调试 以下各部分介绍如何在 AWS Toolkit for Visual Studio Code中使用 Lambda 远程调试。 **注意** Lambda 函数最多支持 5 个层，并且函数代码和所有附加层的总大小不得超过 250MB。Lambda 远程调试需要至少保留 1 个空闲层才能运行。 ### 设置调试会话 在开始之前，请按照以下步骤配置您的调试会话。 1. 通过完成前一节中的 “从资源管理器*访问 Lambda 远程调试” 或 “从应用程序生成 AWS 器资源管理器**访问 Lambda 远程调试”* 过程，打开远程调**用配置**菜单。 1. 在**远程调用配置**菜单中，选中**远程调试**复选框以显示远程调试属性。 1. 指定您的本地处理程序文件的**本地根路径**。 **注意** 本地根路径指的是与您已部署的 Lambda 函数相对应的本地源代码位置。如果您是从 Application Builder 浏览器中的已部署函数开始操作，本地根路径会自动检测。 如果您在本地没有保存源代码，选择**下载远程代码**按钮来获取 Lambda 函数的源代码。这将在 VS Code 编辑器中打开您的 `handler file`。 1. 在**有效载荷**部分，指定您的测试事件数据的来源。 ### 设置断点并调试 按以下步骤设置断点并开始调试。 1. 在 VS Code 编辑器中的 `handler file` 文件，单击行号旁的边距区域，即可在需要暂停调试的位置设置断点。 1. 设置好断点后，返回**远程调用配置**菜单，确认您的设置是正确的，然后选择**远程调用**按钮开始调试。 1. AWS Toolkit 使用调试功能更新您的 Lambda 函数，为调试会话建立安全隧道，使用指定的有效负载调用您的函数，然后在遇到断点时暂停该进程。 1. 在断点暂停时，使用 **RUN AND DEBUG** 面板查看 **VARIABLES**、**CALL STACK** 和 **BREAKPOINTS**。 ### 更新并测试您的函数 如需修改代码并通过快速部署测试变更，请按以下步骤执行操作。 1. 在调试会话仍处于活动状态时，在 VS Code 编辑器中修改您的 `handler file`。 1. 保存您的更改（**Command\$1S on macOS**，**Ctrl\$1S on Windows**） 1. 出现提示时，确认您希望继续部署这些更改。该 AWS 工具包将使用修改后的代码更新您的 Lambda 函数。 1. 设置新的断点，然后再次选择**远程调用**按钮，即可继续调试并测试您的变更。 **注意** 或者，您可以在 VS Code 调试控制中取消选中**附加调试器**选项，然后选择**远程调用**按钮，让函数在不调试的情况下运行。 ### 结束调试会话 以下任一操作都会结束您的远程调试会话，并从项目中移除调试层。 + 在**远程调用配置界面**选择**移除调试设置**选项。 + 在 VS Code 调试控制栏中选择**断开连接**图标。 + 在 VS Code 编辑器中关闭 `handler file`。 **注意** 记录以下内容： Lambda 调试层会在 60 秒处于活动状态后自动移除。这个计时会在上一次调用完成时开始。 如果您在调试过程中对 infrastructure-as-code (IaC) 托管 (AWS SAM,, AWS CDK, Terraform) 函数进行了代码更改，请将其保存到本地项目中，并考虑更新源代码控制存储库。未保存的更改会在 IaC 函数重新部署时被覆盖。 如果您仅出于调试目的进行了临时更改，则可能需要从源代码控制中重新部署函数，以确保其与生产环境中的代码保持一致。 ### 使用源映 TypeScript 射调试 Lambda 函数 以下各节介绍如何使用源映射调试 TypeScript Lambda 函数。 #### 先决条件 要调试您的 TypeScript Lambda 函数，必须满足以下先决条件。 + TypeScript 必须在启用源映射选项的情况下进行编译。有关更多信息，请参阅 VS Code 文档中的[JavaScript 源映射支持](https://code.visualstudio.com/docs/typescript/typescript-debugging#_javascript-source-map-support)主题。 + 不支持内联源地图。必须使用单独`.js.map`的文件来存储源地图。 #### 配置 要为 AWS 工具包中的 Lambda 函数配置 L TypeScript ambda 远程调试，请完成以下步骤。 1. 在 AWS 工具包中，展开 AWS 资源管理器。 1. 在浏览器中，展开 **Lambda** 节点。 1. 导航到要为其配置的功能 TypeScript，然后从上下文菜单中选择 “**远程调用**” 图标以打开 “**远程调用” 配置**屏幕。 1. 选中**远程调试**复选框以启用远程调试。 1. 通过指向包含 `TypeScript handler file` 的目录来配置您的**本地根路径**。 **注意** `TypeScript handler file` 是您设置调试断点的位置。 1. 展开**远程调试附加配置**设置。 1. 选中**源映射**复选框来启用源映射。 1. 将**输出文件**字段设置为您的 Lambda 函数副本所在的本地目录。 **Example** 如果 `app.js` 和 `app.map` 位于 `.aws-sam/build/HelloWorldFunction` 中，则将**输出文件**位置为 `/Users/user/project/aws-sam/build/HelloWorldFunction/*`。 **注意** **输出文件**路径应为绝对路径。 对于 AWS SAM 和 AWS CDK 项目，该 AWS 工具包支持自动源映射检测。如果将这些项目的 Ou **t files** 字段留空，则该工具包将自动尝试检测源地图的位置。 1. 如果您对设置感到满意，请选择 “**远程调用**” 按钮开始调试您的 TypeScript 函数。 ## 故障排除与高级使用案例 如果您的调试会话失败，请按以下步骤开始故障排除： 1. 将 AWS 工具包更新到最新版本。 1. 关闭**远程调用配置** Web 视图并重新打开，以刷新 Web 视图。 1. 完全关闭 VS Code 后再重新打开它。 1. 打开 VS Code 命令面板，输入命令 **AWS: Reset Lambda Remote Debugging Snapshot**，在结果中选择它，以重置 Lambda 远程调试快照。 1. 如果您无法解决问题，请向 Issues 提交[AWS Toolkit for Visual Studio Code GitHub问题](https://github.com/aws/aws-toolkit-vscode/issues)。 ### 高级使用案例：代码签名配置 远程调试需要向您的 Lambda 函数附加调试层。如果您的函数启用并强制执行了代码签名配置，则 AWS Toolkit 无法自动将调试层附加到您的函数。 您可以通过以下两种方式解决代码签名配置问题。 + 暂时移除代码签名。 + 使用已签名的调试层。 #### 暂时移除代码签名。 提供设置 `UntrustedArtifactOnDeployment : Warn` 更新代码签名配置，在调试过程结束后再将其重置回 `Enforced`。 有关更多信息，请参阅 *AWS Lambda API [UpdateCodeSigningConfig](https://docs.aws.amazon.com//lambda/latest/api/API_UpdateCodeSigningConfig.html)参考中的参考资料*。 #### 使用已签名的调试层。 1. 在 AWS 工具包的 Lambda 远程调试中，展开**远程调试其他配置部分**。 1. 在**远程调试附加配置**部分中，从**层覆盖**字段复制您所在区域的层 ARN。 1. 从中 AWS CLI，使用以下命令下载图层版本`aws lambda get-layer-version-by-arn --arn layer-arn`，用您的图层 *ARN 替换 layer-arn*。有关如何下载已签名的调试层的详细说明，请参阅《*AWS CLI 命令*参考》中的 [get-layer-version-by-arn](https://docs.aws.amazon.com/cli/latest/reference/lambda/get-layer-version-by-arn.html) 参考。 1. 使用您的代码签名配置对该层进行签名，并将其发布到您的账户。有关签名和发布指南，请参阅《*AWS Serverless Application Model 开发人员指南*》中的[为您的 AWS SAM 应用程序设置代码签名](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/authoring-codesigning.html)主题。 1. 在已签名的层成功发布到您的账户后，返回 Lambda 远程调试的**远程调试附加配置**部分，然后**层覆盖**字段中输入新的层 ARN。完成后，Lambda 远程调试将使用您签名的调试层，而不再使用默认层。 ### 高级用例：使用 SnapStart 或预配置并发调试函数 对于配置 SnapStart 或预配置并发的 Lambda 函数，发布新版本所需的时间要长得多。为了加快调试工作流程，您可以将 Lambda 远程调试配置为仅更新函数的`$LATEST`版本，而不是发布新版本。 1. 在**远程调用配置**屏幕上，展开**远程调试其他配置**设置。 1. 取消选择 “**发布版本**” 选项。 1. 现在，该 AWS 工具包将仅更新您的函数`$LATEST`版本并使用它进行调试。 **注意** 使用`$LATEST`版本进行调试的副作用是，您应避免其他可能调用您的`$LATEST`版本的流量，以确保调试环境不受干扰。 ### 支持的区域 当某个区域不支持远程调试时，会出现以下错误。 ``` 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](https://docs.aws.amazon.com//lambda/latest/dg/troubleshooting-deployment.html#troubleshooting-deployment-InvalidParameterValueException1)主题部分。 以下列表介绍了排查并解决此错误的一些方法。 + **减小函数大小**：优化函数的代码，移除不必要的依赖关系。 + **移除未使用的层**：在调试期间临时移除非必要层。 + **使用外部依赖项**：将较大的依赖项移至外部存储，例如 Amazon S3，并在运行时加载它们。 ### Java 调试故障排 要调试 Java Lambda 函数，您必须在本地安装与您的 Lambda 函数的运行时版本相匹配的 Java 版本。 例如，在调试 Java 25 函数时，必须在运行 AWS 工具包的本地环境中安装 Java 25。如果您尝试在本地安装了 Java 21 或更早版本的情况下调试 Java 25 函数，则远程调试将无法在您设置的断点处停止。 在开始调试会话之前，请确保您的本地 Java 版本与 Lambda 函数的运行时版本相匹配。 ### 已超出 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 支持联系人门户](https://aws.amazon.com/contact-us/)。*有关 AWS IoT 安全隧道的详细信息，请参阅《开发人员指南》中的[AWS IoT 安全隧道](https://docs.aws.amazon.com/iot/latest/developerguide/secure-tunneling.html)主题。AWS IoT *