AWS Lambda 遠端偵錯 - AWS 適用於 VS 程式碼的工具組
Lambda 遠端偵錯的運作方式開始使用存取 Lambda 遠端偵錯使用 Lambda 遠端偵錯故障診斷和進階使用案例

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

AWS Lambda 遠端偵錯

AWS Toolkit for Visual Studio Code 可讓您直接在 VS 程式碼中偵錯在雲端執行的 AWS Lambda 函數。透過 AWS Lambda 遠端偵錯，您可以檢查執行中的函數、設定中斷點、檢查變數和逐步偵錯，而無需修改其現有的開發工作流程。

下列各節說明如何在 中使用 Lambda 遠端偵錯 AWS Toolkit for Visual Studio Code。

Lambda 遠端偵錯的運作方式

Toolkit 會使用額外的 Lambda 偵錯層暫時修改 Lambda 函數，並將 Lambda 調用逾時限制延長至 900 秒，以 AWS 啟用遠端偵錯。使用 Secure Tunneling 在本機偵錯工具與 Lambda 執行期環境之間建立 AWS IoT 安全連線。此連線可讓您在遠端執行時，使用本機程式碼中斷點逐步完成函數。偵錯工作階段完成後，所有暫時修改都會自動還原為其原始設定。

開始使用

支援的執行期

Lambda 遠端偵錯支援下列執行時間。

  • Python (Amazon Linux 2023)

  • Java

  • JavaScript/Node.js (Amazon Linux 2023)

先決條件

在開始之前，必須符合下列先決條件。

  • 您必須在 AWS Toolkit 中設定有效的 AWS 登入資料。如需安裝 AWS Toolkit 和設定登入資料的其他詳細資訊，請參閱本使用者指南中的入門主題。

  • Lambda 函數已部署至 AWS 您的帳戶。如需部署 Lambda 函數的詳細資訊，請參閱《 AWS Lambda開發人員指南》中的建立您的第一個 Lambda 函數主題。

  • 您必須擁有適當的 AWS Identity and Access Management (IAM) 政策和許可，才能偵錯函數。如需 Lambda 許可的其他詳細資訊，請參閱《 AWS Lambda開發人員指南》中的主題AWS 的 受管政策 AWS Lambda。以下是政策的範例，其中包含在 Toolkit 中使用 AWS 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 Toolkit 中的 Lambda 遠端偵錯： AWS Explorer 或 Application Builder Explorer。從 AWS 瀏覽器，您可以透過 AWS Lambda 節點存取 Lambda 遠端偵錯。從 Application Builder Explorer，您可以透過本機 AWS SAM 專案存取 Lambda 遠端偵錯。

從 AWS 瀏覽器存取 Lambda 遠端偵錯

  1. 從 VS 程式碼中，開啟 AWS Toolkit 延伸模組。

  2. 從 AWS Toolkit 中，展開 AWS 瀏覽器。

  3. 從瀏覽器展開 Lambda 節點。

  4. 導覽至您要偵錯的函數，然後從內容功能表中選擇遠端叫用圖示，以開啟遠端叫用組態畫面。

從 Application Builder Explorer 存取 Lambda 遠端偵錯。

  1. 從 VS 程式碼中，開啟 AWS Toolkit 延伸模組。

  2. 從 AWS Toolkit 中，展開應用程式建置器瀏覽器。

  3. 從瀏覽器展開包含您要偵錯之 Lambda AWS SAM專案的專案。

  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 Explorer 中部署的函數，則會自動偵測您的本機根路徑。

    如果您沒有儲存在本機的原始程式碼，請選擇下載遠端程式碼按鈕來擷取 Lambda 函數原始程式碼。這將在 VS 程式碼編輯器handler file中開啟您的 。

  4. 從承載區段中，指定取得測試事件資料的位置。

設定中斷點和偵錯

完成下列程序，設定中斷點並開始偵錯。

  1. 在 VS 程式碼編輯器handler file的 中，按一下裝訂邊，在您要暫停偵錯的行號上設定中斷點。

  2. 當您對中斷點感到滿意時，請返回遠端調用組態功能表，確認您的設定已正確設定，然後選擇遠端調用按鈕以開始偵錯。

  3. Toolkit 會使用偵錯功能 AWS 更新您的 Lambda 函數、為偵錯工作階段建立安全通道、使用指定的承載叫用函數，然後在到達中斷點時暫停程序。

  4. 在中斷點暫停時，使用 RUN AND DEBUG 窗格來檢視您的 VARIABLES、CALL STACK 和 BREAKPOINTS。

更新和測試您的函數

若要使用快速部署修改程式碼和測試變更，請完成下列程序。

  1. 啟用除錯工作階段後，請在 VS 程式碼編輯器handler file中變更您的 。

  2. 儲存您的變更 (Command+S on macOS、Ctrl+S on Windows)

  3. 出現提示時，請確認您希望繼續部署變更。 AWS 工具組將使用修改後的程式碼更新您的 Lambda 函數。

  4. 透過設定新的中斷點並再次選取遠端調用按鈕，繼續偵錯和測試您的變更。

    注意

    或者，您可以在 VS 程式碼偵錯控制項中取消選取連接偵錯工具選項，然後選擇遠端調用按鈕來執行函數，而無需偵錯。

結束偵錯工作階段

下列每個選項都會結束遠端偵錯工作階段，並從專案中移除偵錯層。

  • 從遠端調用組態畫面選擇移除偵錯設定選項。

  • 從 VS 程式碼偵錯控制項中選擇中斷連線圖示。

  • 在 VS 程式碼編輯器handler file中關閉 。

注意

謹記下列事項：

  • Lambda 除錯層會在閒置 60 秒後自動移除。計數會在您上次調用完成時開始。

  • 如果您在偵錯過程中對infrastructure-as-code(IaC) 受管 (AWS SAM、 AWS CDK、Terraform) 函數進行程式碼變更，請將它們儲存到您的本機專案，並考慮更新您的來源控制儲存庫。重新部署 IaC 函數時，會覆寫未儲存的變更。

  • 如果您僅為偵錯目的進行暫時性變更，建議您從來源控制重新部署函數，以確保其符合您的生產程式碼。

故障診斷和進階使用案例

如果您的偵錯工作階段失敗，請完成下列步驟以開始疑難排解程序。

  1. 將 AWS Toolkit 更新至最新版本。

  2. 關閉遠端調用組態 Web 檢視並重新開啟，以重新整理 Web 檢視。

  3. 完全關閉並重新開啟 VS 程式碼，以重新啟動 VS 程式碼。

  4. 開啟 VS Code Command Palette 並輸入命令 AWS: Reset Lambda Remote Debugging Snapshot，並在填入結果時選取它，以重設 Lambda 遠端偵錯快照。

  5. 如果您無法對問題進行故障診斷，請將問題提交至 AWS Toolkit for Visual Studio Code GitHub 問題。

進階使用案例：程式碼簽署組態

遠端偵錯需要將偵錯層連接至 Lambda 函數。如果您的函數已啟用並強制執行程式碼簽署組態， AWS Toolkit 就無法自動將偵錯層連接至函數。

有兩種選項可解決程式碼簽署組態問題。

  • 暫時移除程式碼簽署。

  • 使用已簽署的偵錯層。

暫時移除程式碼簽署

透過設定 來更新程式碼簽署組態UntrustedArtifactOnDeployment : Warn，然後在Enforced除錯程序完成後重新啟用 。

如需詳細資訊，請參閱 API 參考中的 UpdateCodeSigningConfig AWS Lambda 參考。

使用已簽署的偵錯層

  1. 從 AWS Toolkit 中的 Lambda 遠端偵錯，展開遠端偵錯其他組態區段。

  2. 從遠端偵錯其他組態區段中，從層覆寫欄位複製區域層 ARN。

  3. 從 中 AWS CLI，使用下列命令來下載 layer 版本 aws lambda get-layer-version-by-arn --arn layer-arn，將 layer-arn 取代為您的 layer ARN。如需如何下載已簽署偵錯層的詳細說明，請參閱《 命令參考》中的 get-layer-version-by-arn 參考。 AWS CLI

  4. 使用程式碼簽署組態簽署 layer，並將其發佈至您的帳戶。如需簽署和發佈指引，請參閱《 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 程式碼執行個體 12 小時。

  • 配額適用於每個 AWS 帳戶、每天。

如果您遇到 AWS IoT 安全通道錯誤，請等待每日配額重設，或聯絡 AWS 支援以請求提高配額限制。如需 AWS 支援聯絡資訊，請參閱AWS 支援聯絡入口網站。如需 AWS IoT 安全通道的詳細資訊，請參閱《 AWS IoT 開發人員指南》中的AWS IoT 安全通道主題。

使用來源映射偵錯 TypeScript Lambda 函數

下列各節說明如何使用來源映射偵錯 TypeScript Lambda 函數。

先決條件

若要偵錯 TypeScript Lambda 函數，必須符合下列先決條件。

  • 您的 TypeScript 必須符合已啟用的來源映射選項。如需詳細資訊，請參閱 VS 程式碼文件中的 JavaScript 來源映射支援主題。

  • 若要使用內嵌來源映射，所有變更都必須重新部署到雲端。

組態

若要在 AWS Toolkit 中為 TypeScript Lambda 函數設定 Lambda 遠端偵錯，請完成下列步驟。

  1. 從 AWS Toolkit 中，展開 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，請將 Out 檔案位置設為 /Users/user/project/aws-sam/build/HelloWorldFunction/*。

    注意

    Out 檔案路徑應為絕對路徑。

  9. 當您對設定感到滿意時，請選擇遠端調用按鈕以開始偵錯 TypeScript 函數。