在 VS Code 中進行 Python 除錯

Python 擴充功能支援透過 Python 除錯器擴充功能，對多種類型的 Python 應用程式進行除錯。若要快速瀏覽基本除錯流程，請參閱教學課程 - 設定並執行除錯器。此外，也可參閱 Flask 教學課程。這兩個教學課程皆展示了核心技能，例如設定中斷點與單步執行程式碼。

對於一般除錯功能（例如檢查變數、設定中斷點以及其他與語言無關的活動），請參閱 VS Code 除錯。

本文主要探討 Python 特有的除錯組態，包括針對特定應用程式類型的必要步驟以及遠端除錯。

Python 除錯器擴充功能

Python 除錯器擴充功能會與 VS Code 的 Python 擴充功能一同自動安裝。它透過 debugpy 為多種 Python 應用程式提供除錯功能，包括指令碼、Web 應用程式、遠端處理程序等。

若要確認是否已安裝，請開啟擴充功能檢視（⇧⌘X (Windows, Linux Ctrl+Shift+X)）並搜尋 @installed python debugger。您應該能在結果中看到 Python 除錯器擴充功能。

您可以參考該擴充功能的 README 頁面，以取得支援的 Python 版本相關資訊。

初始化設定

組態（Configuration）會驅動 VS Code 在除錯工作階段期間的行為。組態定義於存放於工作區 .vscode 資料夾中的 launch.json 檔案內。

注意：若要變更除錯組態，您的程式碼必須儲存在資料夾中。

若要初始化除錯組態，請先選取側邊欄中的執行與除錯檢視

如果您尚未定義任何組態，您會看到一個執行並除錯按鈕以及一個建立組態 (launch.json) 檔案的連結

若要產生包含 Python 組態的 launch.json 檔案，請執行下列步驟

1. 選取建立 launch.json 檔案連結（如上圖所示），或使用執行 > 開啟組態功能表命令。

2. 從除錯器選項清單中選取 Python 除錯器。

3. 命令選擇區將開啟組態選單，讓您選擇要用於 Python 專案檔案的除錯組態類型。如果您想對單一 Python 指令碼進行除錯，請在出現的選取除錯組態選單中選取 Python 檔案。

   

   注意：若在沒有組態存在的情況下，透過除錯面板、F5 或執行 > 啟動除錯來啟動除錯工作階段，也會開啟除錯組態選單，但不會建立 launch.json 檔案。

4. 隨後，Python 除錯器擴充功能會建立並開啟一個 launch.json 檔案，其中包含基於您先前所選項目（在本例中為Python 檔案）的預定義組態。您可以修改組態（例如加入引數），也可以加入自訂組態。

   

組態屬性的詳細資料將在本文稍後的標準組態與選項章節中說明。其他組態也會在本文的針對特定應用程式類型進行除錯章節中描述。

其他設定

預設情況下，VS Code 僅顯示 Python 除錯器擴充功能所提供的最常見組態。您可以使用清單及 launch.json 編輯器中提供的新增組態命令，來選擇要加入 launch.json 的其他組態。當您使用此命令時，VS Code 會提示您選擇所有可用的組態清單（請務必選取 Python 選項）

選取使用處理程序識別碼 (PID) 附加選項會產生下列結果：

請參閱針對特定應用程式類型進行除錯以取得這些組態的詳細資訊。

在除錯期間，狀態列會顯示目前的組態與目前的除錯解譯器。選取該組態會彈出清單，讓您從中選擇不同的組態

與 VS Code 的 Python 擴充功能其他功能相同，除錯器預設會使用您為工作區所選取的相同解譯器。若要專門為除錯使用不同的解譯器，請在適用於該除錯組態的 launch.json 中設定 python 的值。或者，使用狀態列上的 Python 解譯器指標來選取不同的解譯器。

基本除錯

如果您只想對 Python 指令碼進行除錯，最簡單的方法是選取編輯器執行按鈕旁邊的向下箭頭，然後選擇 Python 除錯器：偵錯 Python 檔案。

如果您想對使用 Flask、Django 或 FastAPI 的 Web 應用程式進行除錯，Python 除錯器擴充功能可透過執行與除錯檢視中的顯示所有自動除錯組態選項，根據您的專案結構動態建立除錯組態。

但如果您想對其他類型的應用程式進行除錯，您可以透過執行檢視點擊執行與除錯按鈕來啟動除錯器。

當尚未設定任何組態時，系統會為您提供除錯選項清單。在此，您可以選取適當的選項來快速對程式碼進行除錯。

兩種常見的選項是使用 Python 檔案組態來執行目前開啟的 Python 檔案，或是使用 使用處理程序識別碼 (PID) 附加組態，將除錯器附加至已在執行的處理程序。

關於建立與使用除錯組態的詳細資訊，請參閱初始化組態與其他組態章節。一旦新增組態後，即可從下拉式清單中選取，並使用啟動除錯按鈕 (F5) 進行啟動。

命令列除錯

如果您的 Python 環境中已安裝 debugpy，也可以從命令列執行除錯器。

安裝 debugpy

您可以使用 python -m pip install --upgrade debugpy 將 debugpy 安裝至您的 Python 環境中。

命令列語法

除錯器命令列語法如下

python -m debugpy
    --listen | --connect
    [<host>:]<port>
    [--wait-for-client]
    [--configure-<name> <value>]...
    [--log-to <path>] [--log-to-stderr]
    <filename> | -m <module> | -c <code> | --pid <pid>
    [<arg>]...

範例

從命令列中，您可以使用指定的連接埠 (5678) 和指令碼來啟動除錯器。此範例假設該指令碼會長期執行，並省略了 --wait-for-client 旗標，這代表指令碼不會等待用戶端附加。

python -m debugpy --listen 5678 ./myscript.py

然後，您將使用下列組態從 VS Code Python 除錯器擴充功能進行附加。

{
  "name": "Python Debugger: Attach",
  "type": "debugpy",
  "request": "attach",
  "connect": {
    "host": "localhost",
    "port": 5678
  }
}

注意：指定主機對於 listen 是選用的，預設會使用 127.0.0.1。

如果您想對遠端程式碼或在 Docker 容器中執行的程式碼進行除錯，則需要在遠端機器或容器上修改上述 CLI 命令以指定主機。

python -m debugpy --listen 0.0.0.0:5678 ./myscript.py

相關的組態檔如下所示。

{
  "name": "Attach",
  "type": "debugpy",
  "request": "attach",
  "connect": {
    "host": "remote-machine-name", // replace this with remote machine name
    "port": 5678
  }
}

注意：請注意，當您指定 127.0.0.1 或 localhost 以外的主機值時，等於是開啟連接埠以允許來自任何機器的存取，這具有安全性風險。進行遠端除錯時，請務必採取適當的安全預防措施，例如使用 SSH 通道。

命令列選項

注意：[<arg>] 可用於將命令列引數傳遞給正在啟動的應用程式。

透過網路連線進行附加除錯

本機指令碼除錯

有時您可能需要對由另一個處理程序在本機呼叫的 Python 指令碼進行除錯。例如，您可能正在對一個針對特定處理任務執行不同 Python 指令碼的 Web 伺服器進行除錯。在這種情況下，您需要在指令碼啟動後將 VS Code 除錯器附加至該指令碼。

1. 執行 VS Code，開啟包含該指令碼的資料夾或工作區，如果尚不存在，則為該工作區建立 launch.json。

2. 在指令碼程式碼中，加入下列內容並儲存檔案

   import debugpy
   
   # 5678 is the default attach port in the VS Code debug configurations. Unless a host and port are specified, host defaults to 127.0.0.1
   debugpy.listen(5678)
   print("Waiting for debugger attach")
   debugpy.wait_for_client()
   debugpy.breakpoint()
   print('break on this line')
   

3. 使用終端機：建立新終端機開啟終端機，這會啟用指令碼選定的環境。

4. 在終端機中，安裝 debugpy 套件。

5. 在終端機中，使用指令碼啟動 Python，例如 python3 myscript.py。您應該會看到程式碼中包含的 "Waiting for debugger attach" 訊息，且指令碼會在 debugpy.wait_for_client() 呼叫處暫停。

6. 切換至執行與除錯檢視（⇧⌘D (Windows, Linux Ctrl+Shift+D)），從除錯器下拉式清單中選取適當的組態，並啟動除錯器。

7. 除錯器應會在 debugpy.breakpoint() 呼叫處停止，此時您便可正常使用除錯器。您也可以選擇使用 UI 而非 debugpy.breakpoint() 在指令碼程式碼中設定其他中斷點。

使用 SSH 進行遠端指令碼除錯

遠端除錯允許您在程式於遠端電腦上執行時，透過本地的 VS Code 對其進行單步執行。無需在遠端電腦上安裝 VS Code。為了提高安全性，您可能需要或希望在除錯時使用安全連線（如 SSH）連線至遠端電腦。

注意：在 Windows 電腦上，您可能需要安裝 Windows 10 OpenSSH 才能使用 ssh 命令。

下列步驟概述了設定 SSH 通道的一般流程。SSH 通道可讓您在本機電腦上以更安全的方式進行工作，就像直接在遠端操作一樣，而不需開啟公開存取連接埠。

在遠端電腦上

1. 開啟 sshd_config 組態檔（Linux 下位於 /etc/ssh/，Windows 下位於 %programfiles(x86)%/openssh/etc）並加入或修改下列設定，以啟用連接埠轉送

   AllowTcpForwarding yes
   

   注意：AllowTcpForwarding 的預設值為 yes，因此您可能不需要進行任何變更。

2. 如果您必須加入或修改 AllowTcpForwarding，請重新啟動 SSH 伺服器。在 Linux/macOS 上，請執行 sudo service ssh restart；在 Windows 上，請執行 services.msc，在服務清單中選取 OpenSSH 或 sshd，然後選擇重新啟動。

在本機電腦上

1. 執行 ssh -2 -L sourceport:localhost:destinationport -i identityfile user@remoteaddress 來建立 SSH 通道，為 destinationport 選擇一個連接埠，並在 user@remoteaddress 中使用適當的使用者名稱與遠端電腦的 IP 位址。例如，若要使用 IP 位址 1.2.3.4 上的連接埠 5678，命令將會是 ssh -2 -L 5678:localhost:5678 -i identityfile user@1.2.3.4。您可以使用 -i 旗標指定識別檔案的路徑。

2. 驗證您是否可以在 SSH 工作階段中看到提示字元。

3. 在您的 VS Code 工作區中，於 launch.json 檔案內為遠端除錯建立組態，將連接埠設定為與 ssh 命令中使用的連接埠相同，並將主機設定為 localhost。您在此使用 localhost 是因為您已經設定了 SSH 通道。

   {
     "name": "Python Debugger: Attach",
     "type": "debugpy",
     "request": "attach",
     "port": 5678,
     "host": "localhost",
     "pathMappings": [
       {
         "localRoot": "${workspaceFolder}", // Maps C:\Users\user1\project1
         "remoteRoot": "." // To current working directory ~/project1
       }
     ]
   }
   

啟動除錯

現在 SSH 通道已連線至遠端電腦，您可以開始進行除錯。

1. 兩台電腦：確保兩端皆有完全相同的原始程式碼。

2. 兩台電腦：安裝 debugpy。

3. 遠端電腦：有兩種方式可以指定如何附加至遠端處理程序。

   1. 在原始程式碼中，加入下列行，將 address 取代為遠端電腦的 IP 位址與連接埠號碼（此處以 IP 位址 1.2.3.4 為例）。

      import debugpy
      
      # Allow other computers to attach to debugpy at this IP address and port.
      debugpy.listen(('1.2.3.4', 5678))
      
      # Pause the program until a remote debugger is attached
      debugpy.wait_for_client()
      

      listen 中使用的 IP 位址應為遠端電腦的私有 IP 位址。隨後即可正常啟動程式，它會暫停直到除錯器附加為止。

   2. 透過 debugpy 啟動遠端處理程序，例如

      python3 -m debugpy --listen 1.2.3.4:5678 --wait-for-client -m myproject
      

      這會使用 python3 啟動套件 myproject，使用遠端電腦的私有 IP 位址 1.2.3.4 並監聽連接埠 5678（您也可以透過指定檔案路徑而非使用 -m 來啟動遠端 Python 處理程序，例如 ./hello.py）。

4. 本機電腦：僅在您已依照上述說明修改遠端電腦上的原始程式碼時，請在原始程式碼中加入相同程式碼的註解副本。加入這些行可確保兩台電腦上的原始程式碼逐行相符。

   #import debugpy
   
   # Allow other computers to attach to debugpy at this IP address and port.
   #debugpy.listen(('1.2.3.4', 5678))
   
   # Pause the program until a remote debugger is attached
   #debugpy.wait_for_client()
   

5. 本機電腦：切換至 VS Code 中的執行與除錯檢視（⇧⌘D (Windows, Linux Ctrl+Shift+D)），選取 Python 除錯器：附加組態

6. 本機電腦：在您想要開始除錯的程式碼位置設定中斷點。

7. 本機電腦：使用修改後的 Python 除錯器：附加組態與「啟動除錯」按鈕來啟動 VS Code 除錯器。VS Code 應會在您本機設定的中斷點處停止，讓您能夠單步執行程式碼、檢查變數以及執行所有其他除錯動作。您在偵錯主控台中輸入的運算式也會在遠端電腦上執行。

   輸出至 stdout 的文字（如 print 陳述式）會出現在兩台電腦上。然而，其他輸出（如來自 matplotlib 等套件的圖形繪圖）僅會出現在遠端電腦上。

8. 在遠端除錯期間，除錯工具列顯示如下

   

   在此工具列上，中斷連線按鈕（⇧F5 (Windows, Linux Shift+F5)）會停止除錯器並允許遠端程式執行完成。重新啟動按鈕（⇧⌘F5 (Windows, Linux Ctrl+Shift+F5)）會在本地電腦上重新啟動除錯器，但不會重新啟動遠端程式。只有在您已經重新啟動遠端程式並需要重新附加除錯器時，才使用重新啟動按鈕。

設定組態選項

當您第一次建立 launch.json 時，會有兩個標準組態，分別在整合式終端機（VS Code 內部）或外部終端機（VS Code 外部）中執行編輯器中的作用中檔案。

{
  "configurations": [
    {
      "name": "Python Debugger: Current File (Integrated Terminal)",
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal"
    },
    {
      "name": "Python Debugger: Current File (External Terminal)",
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "console": "externalTerminal"
    }
  ]
}

具體設定會在後續章節中描述。您也可以加入標準組態中未包含的其他設定，例如 args。

提示：在專案中建立一個執行特定啟動檔案的組態通常很有幫助。例如，如果您希望在啟動除錯器時始終以引數 --port 1593 啟動 startup.py，請建立如下組態項目

 {
     "name": "Python Debugger: startup.py",
     "type": "debugpy",
     "request": "launch",
     "program": "${workspaceFolder}/startup.py",
     "args" : ["--port", "1593"]
 },

name

提供顯示在 VS Code 下拉式清單中的除錯組態名稱。

類型

識別要使用的除錯器類型；對於 Python 程式碼除錯，請將此項保留為 debugpy。

request

"program": "/Users/Me/Projects/MyProject/src/event_handlers/__init__.py",

"program": "${workspaceFolder}/src/event_handlers/__init__.py",

"args": ["--quiet", "--norepeat", "--port", "1593"],

{
  "name": "Python Debugger: Current File",
  "type": "debugpy",
  "request": "launch",
  "program": "${file}",
  "console": "integratedTerminal",
  "autoReload": {
    "enable": true
  }
}