在 VS Code 中進行 Python 偵錯

Python 擴充功能透過 Python Debugger 擴充功能支援多種 Python 應用程式類型的偵錯。如需基本偵錯的簡短逐步解說，請參閱教學課程 - 設定並執行偵錯工具。另請參閱 Flask 教學課程。這兩個教學課程都示範了核心技能，例如設定中斷點和逐步執行程式碼。

關於一般偵錯功能，例如檢查變數、設定中斷點以及其他與語言無關的操作，請參閱 VS Code 偵錯。

本文主要探討 Python 專屬的偵錯設定，包括特定應用程式類型所需的步驟以及遠端偵錯。

Python Debugger 擴充功能

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

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

您可以參閱擴充功能的 README 頁面，以了解支援的版本資訊。

初始化設定

設定會驅動 VS Code 在偵錯工作階段期間的行為。設定定義在儲存於工作區 .vscode 資料夾中的 launch.json 檔案內。

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

若要初始化偵錯設定，請先選取側邊欄中的執行檢視

如果您尚未定義任何設定，您會看到執行與偵錯按鈕以及建立設定 (launch.json) 檔案的連結

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

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

2. 從偵錯工具選項清單中選取 Python Debugger。

3. 命令選擇區將開啟一個設定功能表，讓您選擇要用於 Python 專案檔案的偵錯設定類型。如果您想偵錯單一 Python 指令碼，請在出現的選取偵錯設定功能表中選取 Python 檔案。

   

   注意：當沒有任何設定存在時，透過偵錯面板、F5 或執行 > 啟動偵錯來啟動偵錯工作階段，也會帶出偵錯設定功能表，但不會建立 launch.json 檔案。

4. 接著，Python Debugger 擴充功能會建立並開啟一個 launch.json 檔案，其中包含根據您先前所選項目 (在此情況下為Python 檔案) 的預先定義設定。您可以修改設定 (例如新增引數)，也可以新增自訂設定。

   

設定屬性的詳細資料將於本文稍後的標準設定與選項中介紹。其他設定也會在本文的偵錯特定應用程式類型中說明。

其他設定

根據預設，VS Code 僅顯示由 Python Debugger 擴充功能提供最常見的設定。您可以使用清單與 launch.json 編輯器中顯示的新增設定命令，來選取其他要包含在 launch.json 中的設定。當您使用該命令時，VS Code 會提示您列出所有可用的設定 (請務必選取 Python 選項)

選取使用處理程序 ID 附加會產生下列結果：

關於所有這些設定的詳細資料，請參閱偵錯特定應用程式類型。

在偵錯期間，狀態列會顯示目前的設定與目前的偵錯解譯器。選取該設定會帶出一個清單，您可從中選擇不同的設定

根據預設，偵錯工具會使用為您的工作區所選取的相同解譯器，就像 VS Code 的 Python 擴充功能的其他功能一樣。若要專門針對偵錯使用不同的解譯器，請在適用偵錯設定的 launch.json 中設定 python 的值。或者，使用狀態列上的 Python 解譯器指示器來選取其他解譯器。

基本偵錯

如果您只對偵錯 Python 指令碼感興趣，最簡單的方法是選取編輯器上執行按鈕旁向下箭號，然後選取 Python Debugger: Debug Python File。

如果您想要使用 Flask、Django 或 FastAPI 來偵錯 Web 應用程式，Python Debugger 擴充功能會透過執行與偵錯檢視中的顯示所有自動偵錯設定選項，根據您的專案結構提供動態建立的偵錯設定。

但如果您想要偵錯其他類型的應用程式，您可以透過執行檢視，按一下執行與偵錯按鈕來啟動偵錯工具。

尚未設定任何設定時，系統會提供您一份偵錯選項清單。在這裡，您可以選取適當的選項來快速偵錯您的程式碼。

兩個常見的選項是使用 Python 檔案設定來執行目前開啟的 Python 檔案，或是使用使用處理程序 ID 附加設定將偵錯工具附加至已經在執行的處理程序。

關於建立與使用偵錯設定的資訊，請參閱初始化設定與其他設定章節。新增設定後，即可從下拉式清單中選取該設定，並使用啟動偵錯按鈕 (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 Debugger 擴充功能進行附加。

{
  "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 Debugger: Attach 設定

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

7. 本機電腦：使用修改後的 Python Debugger: Attach 設定與「啟動偵錯」按鈕來啟動 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

指定啟動偵錯的模式

• launch：在 program 中指定的檔案上啟動偵錯工具
• attach：將偵錯工具附加至已經在執行的處理程序。如需範例，請參閱遠端偵錯。

program

提供 python 程式進入點模組 (啟動檔案) 的完整限定路徑。預設設定中經常使用的值 ${file} 會使用編輯器中目前使用中的檔案。透過指定特定的啟動檔案，無論開啟了哪些檔案，您都可以確保始終以相同的進入點啟動程式。例如

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

您也可以依賴來自工作區根目錄的相對路徑。例如，如果根目錄是 /Users/Me/Projects/MyProject，則您可以使用下列範例

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

module

提供指定要偵錯之模組名稱的功能，類似於在命令列執行時的 -m 引數。如需詳細資訊，請參閱 Python.org

python

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

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

{
    "name": "Python Debugger: Flask",
    "type": "debugpy",
    "request": "launch",
    "module": "flask",
    "env": {
        "FLASK_APP": "app.py"
    },
    "args": [
        "run",
        "--no-debugger"
    ],
    "jinja": true
},

{
    "name": "Python Debugger: Flask (development mode)",
    "type": "debugpy",
    "request": "launch",
    "module": "flask",
    "env": {
        "FLASK_APP": "app.py",
        "FLASK_ENV": "development"
    },
    "args": [
        "run"
    ],
    "jinja": true
},