共用方式為

在 Visual Studio 中對 Python 程式代碼進行偵錯

  • 發行項

Visual Studio 提供 Python 的完整偵錯體驗。 在本文中，您會探索如何將調試程式附加至執行中的進程，並在 Watch 和 Immediate 視窗中評估表達式。 在偵錯工具中，您可以檢查局部變數、使用斷點、逐步執行/跳出/跳過語句、設定下一個語句等等。

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

先決條件

  • 已安裝Visual Studio並支援 Python 工作負載。 如需詳細資訊，請參閱 在Visual Studio中安裝 Python 支援。

  • 要與調試程式搭配使用的 Python 程式代碼。

使用或不使用專案對程式代碼進行偵錯

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

不過，您不需要 Visual Studio 中的專案或方案檔來偵錯 Python 程式代碼。 若要在獨立 Python 檔案中偵錯程式代碼，請在 Visual Studio 中開啟您的檔案，然後選取 [偵錯]>[開始偵錯]。 Visual Studio 會使用全域默認環境啟動腳本，而且沒有自變數。 接著，您就擁有程式代碼的完整偵錯支援。 如需詳細資訊，請參閱 Python 環境。

探索基本除錯

基本的除錯工作流程包括設定斷點、逐步執行程式碼、檢查變數值，以及處理例外狀況。 您可以選取 [偵錯]>[開始偵錯] 或使用 F5 鍵盤快捷方式來啟動偵錯會話。 對於專案，這些動作會啟動 啟動檔案，並使用專案的啟用環境和針對 Project Properties指定的任何命令列參數或搜尋路徑。 若要設定屬性，請參閱 設定專案偵錯選項。

設定專案啟動檔

項目的啟動檔案會在 [方案總管] 中以粗體顯示。 您可以選擇要使用哪個檔案作為啟動檔案。

  • 若要將項目檔指定為啟動檔案，請以滑鼠右鍵按下檔案，然後選取 [[設定為啟始專案]。

在 Visual Studio 2017 15.6 版和更新版本中，如果您沒有指定的啟動檔案集，就會看到警示。 舊版 Visual Studio 可能會在 Python 解釋器執行時開啟 輸出 視窗，或 輸出 視窗短暫開啟和關閉。

指定目前使用中的環境

如果您使用專案檔，調試程式一律會從專案的使用中 Python 環境開始。 您可以變更目前的活動環境。 如需詳細資訊，請參閱 為項目選取 Python 環境。

如果您要偵錯獨立 Python 程式代碼檔案，Visual Studio 會以全域默認環境啟動腳本，而且沒有自變數。

設定斷點

斷點會在標示點停止執行程序代碼，以便檢查程序狀態。

對於經驗豐富的其他程式語言開發者來說，Python 中的某些斷點可能會令人驚訝。 在 Python 中，整個檔案都是可執行程式代碼，因此 Python 會在載入檔案以處理任何最上層類別或函式定義時執行檔案。 如果已設定斷點，您可能會發現調試程式會中斷類別宣告的一部分。 即使有時出人意料，這種行為也是正確的。

  • 若要設定斷點，請在程式碼編輯器的左邊界點擊一下，或以滑鼠右鍵點擊程式碼行，然後選取 [斷點]>[插入斷點]。 每個具有設定斷點的行上會出現一個紅點。

    展示 Visual Studio 中程式碼文件左側邊界上斷點顯示方式的螢幕截圖。

  • 若要移除斷點，請選取紅點或以滑鼠右鍵按下程式代碼行，然後選取 [斷點]>[刪除斷點]。 您也可以選取紅點並選取斷點，然後選取 [斷點 ]>[停用斷點]來停用斷點。

    顯示如何在 Visual Studio 程式代碼檔案左邊界停用斷點的螢幕快照。

設定條件和動作

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

  • 若要設定條件，請以滑鼠右鍵按下斷點的紅點，選取 [條件] 。 斷點設定 對話框隨即開啟。

    在對話框中，您可以新增多個條件，並使用 Python 程式代碼建立條件表示式。 如需 Visual Studio 中此功能的完整詳細數據，請參閱 斷點條件。

    顯示如何在 Visual Studio 中設定斷點條件的選項的螢幕快照。

  • 您也可以選擇為斷點設定 Actions。 您可以建立訊息以記錄至 [輸出 ] 視窗，並選擇性地指定自動繼續執行。

    顯示如何在 Visual Studio 中建立斷點與追蹤點動作的螢幕快照。

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

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

逐步執行程式碼

當 Visual Studio 在斷點停止程式代碼執行時，有數個命令可用來逐步執行程式碼或執行程式碼區塊，然後再中斷一次。 命令可在 Visual Studio 的幾個位置使用，包括 調試程式 工具列、偵錯 功能表、程式代碼編輯器中的滑鼠右鍵操作功能表，以及透過鍵盤快捷方式。

下表摘要說明這些命令，並提供鍵盤快捷方式：

命令 捷徑 描述
停止 Shift + F5 停止偵錯會話。
重新啟動 Ctrl + Shift + F5 重新啟動目前的偵錯會話。
繼續 F5 執行程序代碼，直到您到達下一個斷點為止。
邁入 F11 執行下一個語句並停止。 如果下一個語句是對函式的呼叫，調試程式會在所呼叫函式的第一行停止。
單步執行 F10 執行下一個語句，包括呼叫函式（執行其所有程序代碼），以及套用任何傳回值。 此命令可讓您輕鬆地略過不需要偵錯的函式。
逐步退出 Shift+F11 執行程式代碼直到目前函式的結尾，然後步進至呼叫陳述式。 當您不需要偵錯目前函式的其餘部分時，此命令會很有用。
執行至游標 Ctrl+F10 執行代碼至編輯器中插入符號所在的位置。 此命令可讓您輕鬆地略過不需要偵錯的程式代碼區段。
設定下一語句 Ctrl+Shift+F10 將程式碼中的目前執行位置變更為光標所在的位置。 此命令可讓您完全省略程式代碼區段，例如當您知道程式代碼有錯誤或產生不必要的副作用時。
顯示下一個語句 Alt+Num+\ 返回下一個語句，以在程式碼中執行。 此命令可協助您在程式碼中找出停止調試程式的位置。

檢查和修改值

當您在除錯程式中停止程式代碼執行時，您可以檢查和修改變量的值。 您也可以使用 監控視窗 來監視個別變數和自定義表達式。 如需詳細資訊，請參閱 檢查變數。

  • 若要在偵錯期間使用 DataTips 功能來檢視值，請將滑鼠停留在編輯器中的任何變數上。 您可以選取變數值來變更它：

    顯示 Visual Studio 調試程式中變數之 DataTips 值的螢幕快照。

  • 若要使用 [自動] 視窗，請選取 [偵錯>Windows>自動]。 此視窗包含接近目前語句的變數和表達式。 您可以在值資料列中按兩下，或選取並輸入 F2 以編輯值：

    顯示 Visual Studio 調試程式中 [自動視窗] 視窗的螢幕快照。

    如需有關如何使用 Autos 視窗的更多資訊，請參閱 在 Autos 和 Locals 視窗中檢查變數。

  • 若要使用 [局部變數] 視窗，請選取 [偵錯>Windows>局部變數]。 此視窗會顯示目前範圍中的所有變數，可以再次編輯：

    顯示 Visual Studio 調試程式中 [局部變數] 視窗的螢幕快照。

    如需使用 [局部變數] 視窗的詳細資訊，請參閱 在 [自動] 和 [局部] 視窗中檢查變數。

  • 若要使用 Watch 視窗，請選擇 [偵錯]>Windows>Watch>Watch 1-4。 此選項可讓您輸入任意 Python 運算式並檢視結果。 系統會針對每個步驟重新評估表示式：

    顯示 Visual Studio 調試程式中 [監看式] 視窗的螢幕快照。

    如需使用 Watch 視窗的詳細資訊，請參閱 使用 Watch 和 QuickWatch 視窗設定變數監看。

  • 若要檢查字串值，請選取 檢視 （放大鏡）位於 值 項目右側。 str、unicode、bytes和 bytearray 類型全部可供檢查。

    [檢視] 下拉功能表會顯示四個視覺效果選項：Text、HTML、XML 或 JSON。

    顯示如何從 Visual Studio 調試程式的檢視放大鏡圖標存取視覺化工具的螢幕快照。

    選取視覺效果之後，快顯對話框會根據選取的類型顯示未加上批註的字串值。 您可以使用包裝和捲動、語法醒目提示和樹檢視來檢視字串。 這些視覺效果可協助偵錯長而複雜的字串問題。

檢視例外狀況

如果在偵錯期間於程式發生錯誤，但您沒有例外狀況處理程式，調試程式會在例外狀況的點中斷：

顯示 Visual Studio 調試程式中未處理錯誤的例外狀況彈出視窗的螢幕快照。

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

  • 若要查看例外狀況的展開檢視，請選取 [偵錯>Windows>例外狀況設定]。

    顯示 Visual Studio 調試程式中 [例外狀況設定] 視窗的螢幕快照。

    在 [例外狀況設定] 視窗中，例外狀況下一個複選框會控制調試程式 是否一律 引發該例外狀況時中斷。

  • 若要針對特定例外狀況更頻繁地中斷，請選取 [例外狀況設定] 視窗中例外狀況旁的複選框。

  • 根據預設，大部分例外狀況會在原始程式碼中找不到例外狀況處理程式時中斷。 若要變更此行為，請以滑鼠右鍵按下任何例外狀況，然後修改 [在使用者程序代碼 中未處理時繼續] 選項。 若要減少例外狀況的中斷頻率，請取消選取此選項。

  • 若要設定未出現在 [例外狀況設定] 視窗中的例外狀況，請選取 [新增 加號]。 輸入要監看的例外狀況名稱。 名稱必須符合例外狀況的完整名稱。

設定專案偵錯選項

根據預設，調試程式會使用標準 Python 啟動器、沒有命令行自變數，以及沒有其他特殊路徑或條件來啟動程式。 您可以藉由設定偵錯屬性來設定 Python 專案的啟動選項。

  • 若要存取專案的偵錯屬性，請在 [方案總管] 中以滑鼠右鍵按兩下 Python 專案，選取 [屬性]，然後選取 [偵錯 ] 索引卷標。

    顯示Visual Studio調試程式中 Python 專案偵錯屬性的螢幕快照。

下列各節說明特定屬性。

定義啟動行為

下表列出 啟動模式 屬性的可能值。 使用這個屬性來定義調試程序的啟動行為。

價值 描述
標準 Python 啟動器 使用以與 CPython、IronPython 和 Stackless Python 等變體相容的可攜式 Python 撰寫的偵錯程序代碼。 此選項提供對純 Python 程式代碼進行偵錯的最佳體驗。 當您附加至執行中的 python.exe 進程時，會使用此屬性中指定的啟動器。 此啟動器也針對 CPython 提供 混合模式除錯，這可讓您順暢地在 C/C++ 程式碼與 Python 程式碼之間進行切換。
網頁啟動器 在啟動時啟動預設瀏覽器，並啟用範本的偵錯。 如需詳細資訊，請參閱 Web 範本偵錯 一節。
Django Web 啟動器 實作與 Web 啟動器 屬性相同的行為，但適用於 Django 環境。 僅針對回溯相容性而使用此選項。
IronPython （.NET） 啟動器 使用僅適用於 IronPython 的 .NET 調試程式，但允許在任何 .NET 語言項目之間逐步執行，包括 C# 和 Visual Basic。 如果您附加至裝載 IronPython 的執行中 .NET 進程，就會使用此啟動器。

定義執行行為

下表描述您可以設定為設定調試程式執行行為的屬性。

財產 描述
搜尋路徑 指定 Visual Studio 用於專案的檔案和資料夾搜尋路徑。 這些值與專案 搜尋路徑 節點中顯示的項目相符，位於 方案總管中。 雖然您可以在此對話框中指定搜尋路徑，但 方案總管更容易使用，您可以在其中瀏覽資料夾，並將路徑自動轉換成相對表單。
腳本自變數 定義要新增至 Visual Studio 用來啟動腳本之命令的自變數，並在腳本的檔名之後顯示。 列在值中的第一個項目可由腳本作為 sys.argv[1]使用，第二個項目作為 sys.argv[2]使用，依此類推。
直譯器參數 列出要新增至啟動器命令行的自變數，再列出腳本的名稱。 常見的選項包括 -W ... 來控制警告、-O 稍微優化您的程式，以及 -u 使用未經緩衝的 IO。 IronPython 使用者可能會使用此字段來傳遞 -X 選項，例如 -X:Frames 或 -X:MTA。
解釋器路徑 指定一個解釋器路徑，以覆蓋與目前環境相關聯的路徑。 此值對於使用非標準解釋器啟動腳本可能很有用。
環境變數 使用這個屬性新增類似 <NAME>=\<VALUE>的項目。 Visual Studio 會最後套用這個屬性值，並覆蓋任何現有的全域環境變數，然後根據搜尋路徑 設定來配置 PYTHONPATH。 因此，此設定可用來手動覆寫任何其他變數。

使用互動式視窗

偵錯會話期間可以使用兩個 互動式 視窗：標準 Visual Studio 即時運算 視窗和 Python 偵錯互動式 視窗。

開啟 [即時視窗]

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

  • 若要開啟 [實時運算] 視窗，請選取 [偵錯>Windows>實時運算]。 您也可以使用鍵盤快捷方式 Ctrl+Alt+I。

開啟 [即時偵錯] 視窗

Python 偵錯互動式 視窗提供豐富的環境，具有偵錯時可用的完整 互動式 REPL 體驗，包括撰寫和執行程式代碼。 此視窗會使用標準 Python 啟動器自動連線到調試程式中啟動的任何進程，包括透過 [偵錯]>[附加至進程]所附加的進程。 不過，使用混合模式 C/C++偵錯時，無法使用此視窗。

  • 若要使用 [偵錯互動式] 視窗，請選取 [偵錯>Windows>Python 偵錯互動式] (Shift+Alt+I)。

    顯示如何在 Visual Studio 中使用 Python 偵錯互動式視窗的螢幕快照。

除了 標準 REPL 命令之外，偵錯互動式 視窗還支援特殊的中繼命令，如下表所述：

命令 描述
$continue、$cont、$c 從目前的語句開始執行程式。
$down、$d 將當前框架在堆疊追蹤中下移一層。
$frame 顯示目前的框架識別碼。
$frame 將目前的框架切換至指定的框架識別碼。
- 需要 <框架標識碼> 自變數。
$load 從檔案載入命令並執行，直到完成為止。
$proc 顯示目前的進程識別碼。
$proc 將目前的進程切換至指定的進程標識碼。
- 需要 <進程標識碼> 自變數。
$procs 列出目前正在偵錯的進程。
$stepin、$step、$s 如果可能的話，請逐步執行下一個函數調用。
$stepout、$return、$r 走出目前的功能。
$stepover、$until、$unt 略過下一個函數呼叫。
$thread 顯示目前的線程標識碼。
$thread 將目前的線程切換至指定的線程標識碼。
- 需要 <線程標識碼> 自變數。
$threads 列出目前正在偵錯的線程。
$up、$u 將當前框架在堆疊追蹤中上移一個層級。
$where、$w、$bt 列出目前線程的框架。

進程、線程和 呼叫堆疊 等標準調試程序視窗不會與偵錯互動式 視窗 同步處理。 如果您變更 偵錯互動式 視窗中的作用中進程、線程或框架，則其他調試程序視窗不會受到影響。 同樣地，變更其他調試程序視窗中的作用中進程、線程或框架不會影響 [偵錯互動式 ] 視窗。

使用舊版調試程式

視您的環境設定而定，您可能需要使用舊版調試程式：

  • 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 版和更早版本中的預設值。

  • 若要使用舊版調試程式，請選取 [[工具]>[選項]，展開 [Python>偵錯] 選項，然後選取 [使用舊版調試程式] 選項。

支援舊版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 會顯示錯誤，調試程式不支援此 Python 環境：

調試程序錯誤訊息「調試程式不支援此 Python 環境」的螢幕快照。

當 Visual Studio 回報此環境錯誤時，您必須使用舊版調試程式。

支援較舊的 ptvsd 版本

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

如果您的環境使用 ptvsd 3.x，Visual Studio 會顯示錯誤，調試程式套件無法載入：

調試程式錯誤訊息「無法載入調試程式套件」的螢幕快照。

當您使用舊版 4.x 版 ptvsd 時，調試程式套件已過期，會出現警告：

調試程式警告訊息「調試程式套件已過期」的螢幕快照。

當 Visual Studio 回報這些環境錯誤時，您必須使用舊版調試程式。

重要

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

管理 ptvsd 安裝

請遵循下列步驟來管理 ptvsd 安裝：

  1. 在 [Python 環境] 視窗中，移至 [套件] 索引標籤。

  2. 在搜尋方塊中輸入 ptvsd，並檢查已安裝的 ptvsd 版本：

    顯示如何在 [Python 環境] 視窗中檢查 ptvsd 版本的螢幕快照。

  3. 如果版本低於 4.1.1a9（與 Visual Studio 配套的版本），請選取套件右側的 X，以卸載舊版。 Visual Studio 接著會使用其配套版本。 （您也可以使用 pip uninstall ptvsd 命令從 PowerShell 卸載。

  4. 或者，您可以遵循疑難解答偵錯案例 一節中的指示，將 ptvsd 套件更新為最新版本。

針對偵錯情境進行疑難解答

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

升級 ptvsd 用於 Visual Studio 2019

如果您在 Visual Studio 2019 16.4 版和更早版本中有調試程序的問題，請先升級您的調試程式版本，如下所示：

  1. 在 [Python 環境] 視窗中，移至 [套件] 索引標籤。

  2. 在搜尋方塊中輸入 ptvsd --upgrade，然後選取 執行命令：pip install ptvsd --upgrade。 （您也可以從 PowerShell 使用相同的命令。

    顯示如何在 [Python 環境] 視窗中選取 ptvsd 升級命令的螢幕快照。

    如果問題持續發生，請在 PTVS GitHub 存放庫上提出問題，。

    注意

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

啟用偵錯工具記錄

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

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

  1. 若要在 Visual Studio 中開啟命令視窗，請選取 [檢視]>[其他 Windows>命令視窗]。

  2. 輸入下列命令：

    DebugAdapterHost.Logging /On /OutputWindow

  3. 開始偵錯，並完成重現問題所需的步驟。 在此期間，偵錯記錄會出現在 [偵錯配接器主機記錄檔] 底下的 [輸出] 視窗中。 然後，您可以從該視窗複製記錄，並貼到 GitHub 問題、電子郵件等等。

    顯示 Visual Studio [輸出] 視窗中調試程式記錄輸出的螢幕快照。

  4. 如果 Visual Studio 停止回應，或您無法存取 輸出 視窗，請重新啟動 Visual Studio、開啟命令視窗，然後輸入下列命令：

    DebugAdapterHost.Logging /On

  5. 開始偵錯並重新重現您的問題。 調試程式記錄位於 %temp%\DebugAdapterHostLog.txt中。

相關內容