本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 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 + Typescript/JavaScript/Node.js (Amazon 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 的 受管政策 AWS Lambda](https://docs.aws.amazon.com//lambda/latest/dg/security-iam-awsmanpol.html)。以下是政策的範例，其中包含在 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: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 延伸模組。 1. 從 AWS Toolkit 中，展開 AWS 瀏覽器。 1. 從瀏覽器展開 **Lambda** 節點。 1. 導覽至您要偵錯的函數，然後從內容功能表中選擇**遠端叫用**圖示，以開啟**遠端叫用組態**畫面。 **從 Application Builder Explorer 存取 Lambda 遠端偵錯。** 1. 從 VS 程式碼中，開啟 AWS Toolkit 延伸模組。 1. 從 AWS Toolkit 中，展開應用程式建置器瀏覽器。 1. 從瀏覽器展開包含您要偵錯之 Lambda `AWS SAM`專案的專案。 1. 展開您要偵錯的已部署`Lambda`函數。 1. 導覽至函數遠端，然後從內容功能表中選擇**遠端叫用**圖示，以開啟**遠端叫用組態**畫面。 ## 使用 Lambda 遠端偵錯 下列各節說明如何在 中使用 Lambda 遠端偵錯 AWS Toolkit for Visual Studio Code。 **注意** Lambda 函數有 5 層限制，函數程式碼和所有連接層的合併限制為 250MB。Lambda 遠端偵錯需要至少 1 個可用層才能執行。 ### 設定偵錯工作階段 開始之前，請先完成下列程序來設定偵錯工作階段。 1. 完成*從 AWS 瀏覽器存取 Lambda 遠端偵錯*，或從上一節*的應用程式建置器瀏覽器程序存取 Lambda 遠端偵錯*，以開啟**遠端調用組態**功能表。 1. 從**遠端調用組態**功能表中，選取**遠端偵錯**核取方塊以顯示遠端偵錯屬性。 1. 指定**本機處理常式檔案的本機根路徑**。 **注意** 本機根路徑是原始碼與部署的 Lambda 函數相符的位置。如果您使用 Application Builder Explorer 中部署的函數，則會自動偵測本機根路徑。 如果您沒有儲存在本機的原始程式碼，請選擇**下載遠端程式碼**按鈕來擷取 Lambda 函數原始程式碼。這將在 VS 程式碼編輯器`handler file`中開啟您的 。 1. 從**承載**區段中，指定取得測試事件資料的位置。 ### 設定中斷點和偵錯 完成下列程序，設定中斷點並開始偵錯。 1. 在 VS 程式碼編輯器`handler file`的 中，按一下裝訂邊，在您要暫停偵錯的行號上設定中斷點。 1. 當您對中斷點感到滿意時，請返回**遠端調用組態**功能表，以確認您的設定已正確設定，然後選擇**遠端調用**按鈕以開始偵錯。 1. Toolkit 會使用偵錯功能 AWS 更新您的 Lambda 函數、為偵錯工作階段建立安全通道、使用指定的承載叫用函數，然後在到達中斷點時暫停程序。 1. 在中斷點暫停時，使用 **RUN AND DEBUG** 窗格來檢視您的 **VARIABLES**、**CALL STACK** 和 **BREAKPOINTS**。 ### 更新和測試您的函數 若要使用快速部署修改程式碼和測試變更，請完成下列程序。 1. 啟用偵錯工作階段後，請在 VS 程式碼編輯器`handler file`中變更您的 。 1. 儲存您的變更 (**Command\$1S on macOS**、**Ctrl\$1S on Windows**) 1. 出現提示時，請確認您希望繼續部署變更。 AWS 工具組將使用修改後的程式碼更新您的 Lambda 函數。 1. 透過設定新的中斷點並再次選取**遠端調用**按鈕，繼續偵錯和測試您的變更。 **注意** 或者，您可以在 VS 程式碼**偵錯控制項中取消選取連接偵錯工具**選項，然後選擇**遠端調用**按鈕來執行函數，而無需偵錯。 ### 結束偵錯工作階段 下列每個選項都會結束遠端偵錯工作階段，並從專案中移除偵錯層。 + 從**遠端調用組態**畫面選擇**移除偵錯設定**選項。 + 從 VS 程式碼偵錯控制項中選擇**中斷**連線圖示。 + 在 VS 程式碼編輯器`handler file`中關閉 。 **注意** 謹記下列事項： Lambda 除錯層會在閒置 60 秒後自動移除。計數會在您上次調用完成時開始。 如果您在偵錯過程中對infrastructure-as-code(IaC) 受管 (AWS SAM AWS CDK、Terraform) 函數進行程式碼變更，請將它們儲存至本機專案，並考慮更新您的來源控制儲存庫。重新部署 IaC 函數時，會覆寫未儲存的變更。 如果您僅為偵錯目的進行暫時性變更，建議您從來源控制重新部署函數，以確保其符合您的生產程式碼。 ### 使用來源映射偵錯 TypeScript Lambda 函數 下列各節說明如何使用來源映射偵錯 TypeScript Lambda 函數。 #### 先決條件 若要偵錯 TypeScript Lambda 函數，必須符合下列先決條件。 + 您必須在啟用來源映射選項的情況下編譯 TypeScript。如需詳細資訊，請參閱 VS 程式碼文件中的 [JavaScript 來源映射支援](https://code.visualstudio.com/docs/typescript/typescript-debugging#_javascript-source-map-support)主題。 + 不支援內嵌來源映射。您必須使用個別`.js.map`的檔案來存放來源映射。 #### Configuration 若要在 AWS Toolkit 中為 TypeScript Lambda 函數設定 Lambda 遠端偵錯，請完成下列步驟。 1. 從 AWS Toolkit 中，展開 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`，請將 **Out 檔案**位置設為 `/Users/user/project/aws-sam/build/HelloWorldFunction/*`。 **注意** **Out 檔案**路徑應為絕對路徑。 對於 AWS SAM 和 AWS CDK 專案， AWS Toolkit 支援自動來源映射偵測。如果這些專案的**輸出檔案**欄位保持空白，工具組會自動嘗試偵測來源映射位置。 1. 當您對設定感到滿意時，請選擇**遠端調用**按鈕以開始偵錯 TypeScript 函數。 ## 故障診斷和進階使用案例 如果您的偵錯工作階段失敗，請完成下列步驟以開始疑難排解程序。 1. 將 AWS Toolkit 更新至最新版本。 1. 關閉**遠端調用組態** Web 檢視並重新開啟，以重新整理 Web 檢視。 1. 完全關閉並重新開啟 VS 程式碼，以重新啟動 VS 程式碼。 1. 開啟 VS Code Command Palette 並輸入命令 **AWS: Reset Lambda Remote Debugging Snapshot**，並在填入結果時選取它，以重設 Lambda 遠端偵錯快照。 1. 如果您無法對問題進行疑難排解，請將問題提交至 [AWS Toolkit for Visual Studio Code GitHub 問題](https://github.com/aws/aws-toolkit-vscode/issues)。 ### 進階使用案例：程式碼簽署組態 遠端偵錯需要將偵錯層連接至 Lambda 函數。如果您的函數已啟用並強制執行程式碼簽署組態， AWS Toolkit 就無法自動將偵錯層連接至函數。 有兩種選項可解決程式碼簽署組態問題。 + 暫時移除程式碼簽署。 + 使用簽章的偵錯層。 #### 暫時移除程式碼簽署 透過設定 來更新程式碼簽署組態`UntrustedArtifactOnDeployment : Warn`，然後在`Enforced`除錯程序完成後重新啟用 。 如需詳細資訊，請參閱 API 參考中的 [UpdateCodeSigningConfig](https://docs.aws.amazon.com//lambda/latest/api/API_UpdateCodeSigningConfig.html) *AWS Lambda 參考*。 #### 使用已簽章的偵錯層 1. 從 AWS Toolkit 中的 Lambda 遠端偵錯，展開**遠端偵錯其他組態**區段。 1. 從**遠端偵錯其他組態**區段中，從層**覆寫欄位複製您的區域層** ARN。 1. 從 中 AWS CLI，使用下列命令下載 layer 版本 `aws lambda get-layer-version-by-arn --arn layer-arn`，將 *layer-arn* 取代為您的 layer ARN。如需如何下載已簽署偵錯層的詳細說明，請參閱《 命令參考》中的 [get-layer-version-by-arn](https://docs.aws.amazon.com/cli/latest/reference/lambda/get-layer-version-by-arn.html) 參考。 *AWS CLI * 1. 使用程式碼簽署組態簽署 layer，並將其發佈至您的帳戶。如需簽署和發佈指引，請參閱《 *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. Toolkit 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 Toolkit 正在執行的本機環境中安裝 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 程式碼執行個體 12 小時。 + 配額適用於每個 AWS 帳戶、每天。 如果您遇到 AWS IoT 安全通道錯誤，請等待每日配額重設，或聯絡 AWS 支援以請求提高配額限制。如需 AWS 支援聯絡資訊，請參閱[AWS 支援聯絡入口網站](https://aws.amazon.com/contact-us/)。如需 AWS IoT 安全通道的詳細資訊，請參閱《 *AWS IoT 開發人員指南*》中的[AWS IoT 安全通道](https://docs.aws.amazon.com/iot/latest/developerguide/secure-tunneling.html)主題。