在 Visual Studio 中偵錯 Python 程式碼

發行項
04/18/2024

Visual Studio 為 Python 提供全面的偵錯體驗。在本文中，將探討如何將偵錯工具連結到正在執行的程序上，並在 Watch 和 Immediate 視窗中評估表達式。在偵錯工具中，您可以檢查區域性變數、使用中斷點、步進/跳出/越過陳述式、設定下一個陳述式等。

如需案例特定的偵錯資訊，請參閱下列文章：

必要條件

已安裝 Visual Studio 並支援 Python 工作負載。如需詳細資訊，請參閱在 Visual Studio 中安裝 Python 支援。
與偵錯工具一起使用的 Python 程式碼。

偵錯程式碼是否含專案

如果您想要控制您的 Python 環境和引數，請先為程式碼建立專案。您可以使用 From existing Python code 專案範本建立專案。如需詳細資訊，請參閱從現有的 Python 程式碼檔案建立專案。

但是，您不需要在 Visual Studio 中使用專案或方案檔來偵錯 Python 程式碼。若要在獨立的 Python 檔案中偵錯程式碼，請在 Visual Studio >中開啟您的檔案，然後選取 Debug Start Debugging。 Visual Studio 啟動具有全域預設環境且沒有引數的指令碼。然後，您就能獲得程式碼的完整偵錯支援。如需詳細資訊，請參閱 Python 環境。

探索基本偵錯

基本偵錯工作流程涉及設定中斷點、逐步執行程式碼、檢查值以及處理例外狀況。您可以選取 >Debug Start Debugging ，或使用 F5 鍵盤捷徑來啟動偵錯工作階段。 對於專案，這些動作會使用專案的使用中環境和任何為 Project Properties 指定的命令列引數或搜尋路徑來啟動啟動檔案。若要設定屬性，請參閱 Set project debugging options。

設定專案啟動檔案

專案的啟動檔案在 Solution Explorer 中以粗體顯示。您可以選擇使用哪個檔案做為啟動檔案。

若要將專案檔案指定為啟動檔案，請以滑鼠右鍵按一下檔案，然後選取 Set as Startup Item。

在 Visual Studio 2017 15.6 及更高版本中，如果您沒有指定的啟動檔案集，就會看到警示。 Visual Studio 的早期版本可能會在執行 Python 解譯器時開啟 Output 視窗，或者 Output 視窗會短暫地開啟和關閉。

指定使用中環境

如果您使用專案檔案，偵錯工具一律會以專案的活動 Python 環境啟動。您可以變更目前的使用中環境。如需詳細資訊，請參閱 Select a Python environment for a project。

如果您正在偵錯獨立的 Python 程式碼檔案，Visual Studio 會啟動具有全域預設環境且沒有引數的指令碼。

設定中斷點

中斷點會在標示的點停止執行程式碼，讓您可以檢查程式狀態。

Python 中的一些中斷點可能會令已使用其他程式設計語言的開發人員感到意外。在 Python 中，整個檔案就是可執行程式碼，因此 Python 會在載入檔案來處理任何最上層類別或函式定義時執行檔案。如果設定中斷點，您可能會發現偵錯工具會透過類別宣告進行部分中斷。這種行為正確，不過有時會很令人意外。

若要設定中斷點，請在程式碼編輯器的左邊界中選取，>或用滑鼠右鍵按一下程式碼行，然後選取 Breakpoint Insert Breakpoint。每行都有設定的中斷點，都會出現一個紅點。
若要移除中斷點，請選取紅點，或在程式碼>行上按一下滑鼠右鍵，然後選取 Breakpoint Delete Breakpoint。您也可以選取紅點，然後選取 Breakpoint >Disable Breakpoint 停用中斷點。

設定條件和動作

您可以自訂觸發中斷點的條件，例如僅在變數設為特定值或值範圍時中斷。

若要設定條件，請以滑鼠右鍵按一下中斷點的紅點，選取 Conditions。 Breakpoint Settings 對話方塊開啟。

在對話方塊中，您可以使用 Python 程式碼來新增多個條件並建立條件表達式。如需 Visual Studio 中這項功能的完整詳細資訊，請參閱中斷點條件。
您也可以選擇設定中斷點的 Actions。您可以建立訊息以記錄至 Output 視窗，並選擇性地指定繼續自動執行。

記錄訊息會建立 追蹤點，但不會直接將記錄程式碼新增至應用程式。

視您如何設定中斷點的條件和動作而定，左邊距中的紅色圖示會變更以指示您的設定。您可能會看到點狀的時鐘計時器或菱形。

逐步執行程式碼

當 Visual Studio 在中斷點處停止程式碼執行時，您可以使用數個命令逐步執行程式碼或執行程式碼區塊，然後再中斷一次。這些命令在 Visual Studio 中的少數地方可用，包括 [偵錯工具]工具列、[偵錯] 功能表、程式碼編輯器中按一下滑鼠右鍵的快顯功能表，以及鍵盤快速鍵。

下表總結這些指令並提供鍵盤快速鍵：

Command	捷徑	描述
繼續	F5	執行程式碼，直到到達下一個中斷點。
逐步執行	F11	執行下一個陳述式並停止。如果下一個語句是函式的呼叫，則偵錯程式會在被呼叫的函式的第一行停止。
逐程序	F10	執行下一個陳述式，包括呼叫函式 (執行所有程式碼) 並套用任何傳回值。此指令可讓您輕鬆跳過不需要除錯的函式。
跳出	Shift+F11	執行程式碼直到目前函式結束，然後跳到呼叫陳述式。當您不需要對目前函式的其餘部分進行偵錯時，此命令非常有用。
執行至游標處	Ctrl+F10	執行程式碼，直到插入號在編輯器中的位置。此命令可讓您輕鬆略過不需偵錯的程式碼區段。
設定下一個陳述式	Ctrl+Shift+F10	將程式碼中的目前執行點變更為插入記號的位置。此命令可讓您略過特定的程式碼區段而不執行，例如當您知道程式碼有錯誤或是會產生不想要的副作用時。
顯示下一個陳述式	Alt+Num+\	返回要在程式碼中執行的下一個陳述式。此指令可協助您找出程式碼中偵錯工具停止的位置。

檢查和修改值

當您在偵錯工具中停止程式碼執行時，您可以檢查並修改變數的值。您也可以使用 [監看式] 視窗來監視個別的變數及自訂運算式。如需詳細資訊，請參閱 [檢查變數]。

若要在偵錯期間使用 DataTips 功能來檢視值，請將滑鼠停留在編輯器中的任何變數上。您可以選取要變更的變數值：
若要使用 Autos 視窗，>請選取 >Debug Windows Autos。此視窗包含接近目前陳述式的變數與運算式。您可以在值欄中連按兩下，或選取並輸入 F2，以編輯值：

有關使用 Autos 視窗的詳細資訊，請參見 Autos 和 Locals 視窗中的 Inspect variables。
若要使用 Locals，>請選取 >Debug Windows Locals。此視窗會顯示目前範圍內所有可再次編輯的變數：

有關使用 Locals 視窗的詳細資訊，請參見 Autos 和 Locals 視窗中的 Inspect variables。
若要使用 [監看式]視窗，請選取 [偵錯]>[Windows]>[監看式]>[監看式 1-4]。此選項可讓您輸入任意 Python 運算式並檢視結果。運算式會針對每個步驟重新評估︰

如需有關使用 [監看式] 視窗的詳細資訊，請參閱使用監看式及快速監看式視窗在變數設定監看式。
若要檢查字串值，請選取 Value 項目專案右側的 View (放大鏡)。 str、unicode、bytes和bytearray型別均可供檢查。

View 下拉式功能表顯示四個視覺化選項：文字、HTML、XML 或 JSON。

選取視覺化後，彈出式對話方塊會根據選取的型別顯示未加引號的字串值。您可以使用換行與捲動、語法反白以及樹狀檢視來檢視字串。這些視覺化功能可協助偵錯長且複雜字串的問題。

檢視例外

如果對程式進行偵錯時發生錯誤，但您沒有例外狀況處理常式可以處理它，偵錯工具會在例外狀況的位置中斷︰

發生錯誤時，可以檢查目前的程式狀態，包括呼叫堆疊。但是，如果您逐步執行程式碼，偵錯程式會繼續擲回例外狀況，直到處理例外狀況或您的程式結束為止。

若要>檢視展開的例外檢視，>請選取 Debug Windows Exception Settings。

在 Exceptions Settings 視窗中，例外旁邊的核取方塊會控制當發生例外時，偵錯工具是否一直中斷。
若要針對特定例外更頻繁地中斷，請在 Exception Settings 視窗中選取例外旁的核取方塊。
根據預設，當在原始程式碼中找不到例外狀況處理常式時，大多數例外狀況都會中斷。若要變更此行為，請以滑鼠右鍵按一下任何例外狀況，並修改 [當使用者程式碼中未處理時繼續] 選項。若要減少例外中斷頻率，請取消選取此選項。
若要設定 Exception Settings 視窗中未出現的異常，請選取 Add (加號)。輸入要監視的例外狀況名稱。名稱必須符合例外狀況的完整名稱。

設定專案偵錯選項

根據預設，偵錯工具會使用標準 Python 啟動器啟動您的程式，不使用任何命令列引數或其他特殊路徑或條件。您可以設定偵錯屬性來設定 Python 專案的啟動選項。

若要存取專案的偵錯屬性，請在 Solution Explorer、以滑鼠右鍵按一下您的 Python 專案、選取屬性，然後選取 Debug 頁籤。

以下部分介紹特定屬性。

定義啟動行為

下表列出 Launch mode 屬性的可能值。使用此屬性定義偵錯工具的啟動行為。

值	Description
標準 Python 啟動器	使用可攜式 Python 編寫的與 CPython、IronPython 和類似 Stackless Python 變體相容的偵錯程式碼。此選項為偵錯純 Python 程式碼提供最佳體驗。當您連結至執行中的 `python.exe` 處理序時，會使用此屬性中指定的啟動器。此啟動器還提供 CPython 的混合模式偵錯，可讓您在 C/C++ 程式碼和 Python 程式碼之間無縫切換。
Web 啟動器	啟動時啟動您的預設瀏覽器，並啟用範本偵錯。有關更多資訊，請參見 Web 模板偵錯部分。
Django Web 啟動器	實作與 Web 啟動程式屬性相同的行為，但適用於 Django 環境。此選項僅用於向後相容的目的。
IronPython (.NET) 啟動器	使用 .NET 偵錯工具，它只能與 IronPython 搭配使用，但可以跨越 C# 和 Visual Basic 等任何 .NET 語言專案。如果您連結至裝載 IronPython 的執行中 .NET 程序，則會使用此啟動程式。

定義執行行為

下表說明您可以設定以設定偵錯工具執行行為的屬性。

屬性	說明
搜尋路徑	指定 Visual Studio 用於專案的檔案和資料夾搜尋路徑。這些值符合在 Solution Explorer 中專案的 Search Paths 節點中顯示的專案。雖然您可以在此對話方塊中指定搜尋路徑，但使用 Solution Explorer (您可以瀏覽資料夾並自動將路徑轉換為相對表單) 會更容易。
指令碼引數	定義要新增至 Visual Studio 用來啟動指令碼的命令中的引數，並顯示在指令碼檔案名稱之後。值中列出的第一個專案可供指令碼 as 為 `sys.argv[1]`the second as `sys.argv[2]`使用等。
解譯器引數	在指令碼名稱前列出要新增至啟動器命令列的引數。常見的引數是`-W ...`用來控制警告、`-O`稍微最佳化您的程式，`-u`以及使用無緩衝 IO。 IronPython 使用者可能會使用此欄位傳遞 `-X` 選項，例如 `-X:Frames` 或 `-X:MTA`。
解譯器路徑	識別解譯器路徑，以覆寫與目前環境相關的路徑。該值對於使用非標準解譯器啟動指令碼可能很有用。
環境變數	使用此屬性來`<NAME>=\<VALUE>`新增表單專案。 Visual Studio 會將此屬性值套用到`PYTHONPATH`任何現有的全域環境變數上，並依 Search Paths 設定進行設定。因此，此設定可用來手動覆寫任何其他變數。

使用互動式視窗

在偵錯工作階段期間，您可以使用兩個互動視窗：標準 Visual Studio Immediate 視窗和 Python Debug Interactive 視窗。

開啟 Immediate 視窗

您可以使用標準的 Visual Studio Immediate 視窗快速評估 Python 運算式，並檢查或指派執行中的程式中的變數。如需詳細資訊，請參閱即時運算視窗。

若要開啟 Immediate 視窗，>請選取 >Debug Windows Immediate。您也可以使用鍵盤快速鍵 Ctrl+Alt+I。

開啟 Debug Interactive 視窗

Python Debug Interactive 視窗提供一個豐富的環境，偵錯時可使用完整的互動式 REPL 體驗，包括編寫和執行程式碼。此視窗會使用 Standard Python 啟動程式，自動連線到偵錯工具中啟動的任何程式，包括透過 [偵錯]>[連結至處理序]連結的程式。不過，使用混合模式 C/C++ 偵錯時，無法使用此視窗。

若要使用 Debug >Interactive 視窗，>請選取 Debug Windows +Python Debug +Interactive (Shift Alt I)。

除標準 REPL 命令外，Debug Interactive 視窗也支援特殊的元命令，如下表所述：

Command	描述
`$continue`、`$cont`、`$c`	從目前的陳述式開始執行程式。
`$down`、`$d`	在堆疊追蹤中將目前的框架下移一層。
`$frame`	顯示目前的影格識別碼。
`$frame`	將目前的影格切換為指定的影格 ID。 - 需要<框架 >ID 引數。
`$load`	從檔案載入命令，並執行直到完成。
`$proc`	顯示目前的處理序識別碼。
`$proc`	將目前處理序切換為指定的處理序 ID。 - 需要<處理序 >ID 引數。
`$procs`	列出目前正在偵錯的程序。
`$stepin`、`$step`、`$s`	如有可能，請執行下一個函式呼叫。
`$stepout`、`$return`、`$r`	跳出目前的功能。
`$stepover`、`$until`、`$unt`	逐步執行下一個函式呼叫。
`$thread`	顯示目前的執行緒識別碼。
`$thread`	將目前執行緒切換為指定的執行緒 ID。 - 需要 <執行緒 >ID 引數。
`$threads`	列出目前正在偵錯的執行緒。
`$up`、`$u`	在堆疊追蹤中將目前的框架上移一層。
`$where`、`$w`、`$bt`	列出目前執行緒的框架。

標準偵錯工具視窗 (例如 [處理序]、[執行緒] 和 [呼叫堆疊]) 不會與 [互動式偵錯] 視窗同步。 如果您在 Debug Interactive 視窗中變更使用中的程序、執行緒或框架，則其他偵錯工具視窗不會受到影響。同樣地，在其他偵錯工具視窗變更使用中的處理序、執行緒或框架，也不會影響 [互動式偵錯] 視窗。

使用舊版偵錯工具

視您的環境組態而定，您可能需要使用舊版除錯程式：

Visual Studio 2017 版本 15.7 及更早版本搭配 Python 2.6、3.1 至 3.4 或 IronPython
Visual Studio 2019 版本 16.5 及更新版本，搭配 Python 2.6、3.1 至 3.4 或 IronPython
ptvsd 3.x 和 4.x 早期版本

舊版偵錯工具是 Visual Studio 2017 15.7 版及更早版本中的預設值。

若要使用>舊版除錯程式，請選取 Tools Options，>展開 Python Debugging 選項，然後選取 Use lagacy debugger 選項。

支援舊版 Visual Studio 或 Python

Visual Studio 2017 15.8 及更高版本使用基於 ptvsd 4.1 及更高版本的偵錯程式。 Visual Studio 2019 16.5 及更高版本使用基於 debugpy 的偵錯工具。這兩個版本的偵錯工具與 Python 2.7 或 Python 3.5 及更高版本相容。

如果您正在執行其中一個 Visual Studio 版本，但您正在使用 Python 2.6、3.1 到 3.4 或 IronPython，Visual Studio 會顯示錯誤，Debugger does not support this Python environment：

當 Visual Studio 報告此環境錯誤時，您必須使用舊版偵錯工具。

支援較舊的 ptvsd 版本

如果您在目前環境中使用較舊版本的 ptvsd (例如較舊的 4.0.x 版本，或遠端偵錯所需的 3.x 版本)，Visual Studio 可能會顯示錯誤或警告。

如果您的環境使用 ptvsd 3.x，Visual Studio 會顯示錯誤，無法載入 Debugger 套件:

當您使用舊版 ptvsd 時，會出現警告 Debugger package is outdated：

當 Visual Studio 報告這些環境錯誤時，您必須使用舊版偵錯工具。

重要

雖然您可以選擇忽略某些版本的 ptvsd 的警告，但 Visual Studio 可能無法正常運作。

管理您的 ptvsd 安裝

請依照下列步驟管理您的 ptvsd 安裝：

在 Python Environments 視窗中，轉到 Packages 頁籤。
在搜尋方塊中輸入 ptvsd，並檢查已安裝的 ptvsd 版本：
如果版本低於 4.1.1a9 (隨附於 Visual Studio 的版本)，請選取套件右側的 X 以將舊版解除安裝。 Visual Studio 就會使用其隨附的版本。 (您也可以使用pip uninstall ptvsd命令從 PowerShell 解除安裝。)
或者，您可以按照 Troubleshoot debug scenarios 部分中的說明將 ptvsd 軟體包更新為其最新版本。

疑難排解偵錯案例

下列案例說明除錯組態的其他疑難排解選項。

升級 Visual Studio 2019 的 ptvsd

如果您在 Visual Studio 2019 16.4 及更早版本中的偵錯工具有問題，請先升級您的偵錯工具版本，如下所示：

在 Python Environments 視窗中，轉到 Packages 頁籤。
在搜尋方塊中輸入 ptvsd —upgrade，然後選取 Run 指令：pip install ptvsd - upgrade。 (您也可以從 PowerShell 使用相同的命令。)

如果問題仍然存在，請在 PTVS GitHub 儲存庫上提交問題。

注意

針對 Visual Studio 2019 16.5 版和更新版本，debugpy 是 Visual Studio Python 工作負載的一部分，並隨著 Visual Studio 一起更新。

啟用偵錯工具記錄

在調查偵錯工具問題的過程中，Microsoft 可能會要求您啟用並收集偵錯工具記錄以協助診斷。

下列步驟在目前的 Visual Studio 工作階段中啟用偵錯：

選取檢視其他 >Windows Command >Window，在 Visual Studio 中開啟命令視窗。

輸入下列命令：

DebugAdapterHost.Logging /On /OutputWindow

開始偵錯，並完成重現問題的必要步驟。在此期間，[偵錯配接器主機記錄] 下的 [輸出] 視窗中會出現偵錯記錄。然後，您可以從該視窗複製記錄檔，並貼入 GitHub 問題、電子郵件等。
如果 Visual Studio 停止回應，或是您無法存取 [輸出] 視窗，請重新啟動 Visual Studio、開啟命令視窗，並輸入下列命令：
```
DebugAdapterHost.Logging /On
```
開始偵錯，並再次重現您的問題。偵錯工具記錄位於%temp%\DebugAdapterHostLog.txt中。

在 Visual Studio 中偵錯 Python 程式碼

必要條件

偵錯程式碼是否含專案