在 Visual Studio 中遠端偵錯 Linux 上的 Python 程式碼

發行項
04/18/2024

在本文中，您將探索如何配置 Visual Studio 安裝以支援在遠端 Linux 電腦上偵錯 Python 程式碼。本逐步解說是以 Visual Studio 2019 16.6 版為基礎。

Visual Studio 可以在 Windows 電腦上啟動和遠端偵錯 Python 應用程式。 Visual Studio 還支援使用 debugpy 程式庫，在除 CPython 之外的其他作業系統、裝置或 Python 實現上遠端偵錯。

Visual Studio 2019 16.4 版及更早版本使用 ptvsd 程式庫。在 Visual Studio 2019 16.5 及更高版本中，debugpy 程式庫取代 ptvsd。當您使用 debugpy 時，正在偵錯的 Python 程式碼會裝載 Visual Studio 可以附加的偵錯伺服器。此裝載需要對程式碼稍加修改，以匯入和啟用伺服器。您可能還需要調整遠端電腦上的網路或防火牆配置以允許 TCP 連線。

必要條件

已安裝 Visual Studio 並支援 Python 工作負載。如需詳細資訊，請參閱在 Visual Studio 中安裝 Python 支援。
執行 Python 的遠端電腦，作業系統為 Mac OS 或 Linux。
遠端電腦防火牆上的連線埠 5678 (輸入) 開啟，這是遠端偵錯的預設值。

設定 Linux 電腦

您可以在 Azure，輕鬆建立Linux 虛擬機器器，並從 Windows 使用 Remote Desktop 存取。虛擬機器的 Ubuntu 非常方便，因為預設情況下會安裝 Python。如果您有不同的組態，請參閱安裝其他 Python 下載位置的 Python 解譯器。

設定防火牆

必須在遠端電腦的防火牆上開啟輸入連線埠 5678，才能支援遠端偵錯。

有關如何為 Azure 虛擬機器器建立防火牆規則的詳細資訊，請參閱下列文章：

準備偵錯指令碼

按照以下步驟準備用於在 Linux 上偵錯 Python 程式碼的程式腳本。

在遠端電腦上，使用下列程式碼，建立名為 guiling-game.py 的 Python 檔案：

import random

guesses_made = 0
name = input('Hello! What is your name?\n')
number = random.randint(1, 20)
print('Well, {0}, I am thinking of a number between 1 and 20.'.format(name))

while guesses_made < 6:
    guess = int(input('Take a guess: '))
    guesses_made += 1
    if guess < number:
        print('Your guess is too low.')
    if guess > number:
        print('Your guess is too high.')
    if guess == number:
        break
if guess == number:
    print('Good job, {0}! You guessed my number in {1} guesses!'.format(name, guesses_made))
else:
    print('Nope. The number I was thinking of was {0}'.format(number))

使用 debugpy指令將封裝安裝到您的環pip3 install debugpy境中。

注意

記錄已安裝的 debugpy 版本，以備您進行疑難排解時使用，是一個好主意。 debugpy listing 還顯示可用的版本。
將下列程式碼加入至guessing-game.py，再加入其他程式碼，即可啟用遠端偵錯。 (雖然不是嚴格要求，但在呼叫 listen 函式前，無法對繁衍 (Spawn) 的任何背景執行緒進行偵錯。)
```
import debugpy
debugpy.listen(('0.0.0.0', 5678))
```
儲存檔案並執行程式：
```
python3 guessing-game.py
```
對函數的呼叫會在背景執行，listen並在您與程式互動時等待傳入連線。如果需要，您可以在呼叫wait_for_client函式後呼叫該函數，listen以阻止程式，直到偵錯程式附加。

提示

除了listen和wait_for_client函式之外，debugpy breakpoint還提供一個 helper 函式。如果附加偵錯工具，則此函式會作為程式設計中斷點。如果附加偵錯工具，is_client_connected1則會傳回另True一個函式。在呼叫任何其他debugpy函式之前，您無需檢查此結果。

從 Python 工具遠端附加

下列步驟顯示如何設定中斷點來停止遠端程序。

在本機電腦上建立遠端檔案的複本，然後在 Visual Studio 中開啟它。檔案所在位置並不重要，但其名稱應符合遠端電腦上的指令碼名稱。
(選擇性) 若要讓本機電腦具有適用於 debugpy 的 IntelliSense，請將 debugpy 套件安裝到您的 Python 環境中。
選取 [偵錯]>[附加至處理序]。
在 Attach to Process 對話方塊中，將 Connection Type 設定為 Python remote (debugpy)。
在 Connection Target 欄位中，tcp://<ip_address>:5678輸入指令。
- tcp://將連線型別指定為 Transmission Control Protocol (TCP)。
- <ip_address>是遠端電腦的 IP 位址，可以是明確位址或類似 myvm.cloudapp.net 的名稱。
- :5678是遠端偵錯連線埠號碼。
選取 Enter，以填入該電腦上可用的偵錯處理序清單：

填入此清單之後，如果您剛好在遠端電腦上啟動另一個程式，請選取 [重新整理] 按鈕。
選取要偵錯的處理序並選取 Attach，或連按兩下該程序。
Visual Studio 會切換至偵錯模式，而指令碼會繼續在遠端電腦上執行，提供所有常用的偵錯功能。

您可以在行if guess < number:上設定中斷點，然後切換至遠端電腦，然後輸入另一個猜測。本機電腦上的 Visual Studio 會在中斷點處停止，顯示本機變數等等：
停止偵錯時，Visual Studio 會從程式中斷連線。程式繼續在遠端電腦上執行。 debugpy 也會繼續接聽以便連結偵錯工具，因此您可以隨時將其重新連結至處理序。

疑難排解連線

請檢閱下列要點，以協助疑難排解連線問題。

請務必選取 Python remote (debugpy)，作為 Connection Type。
確認 Connection Target 中的密碼，與遠端程式碼中的密碼完全相符。
確認 Connection Target 中的 IP 位址符合遠端電腦的 IP 位址。
確認遠端電腦上的遠端偵錯連線埠已開啟，:5678而且連線目標包含連線埠尾碼，例如。

若要使用不同的連線埠，請在呼叫函listen數時指定連線埠號碼，如debugpy.listen((host, port))中。在這種情況下，請務必開啟防火牆中的特定埠。
確認遠端電腦上安裝的 debugpy 版本 (pip3 list命令傳回) 與 Visual Studio Python Tools (PTVS) 版本相符。

下表列出有效的版本對。視需要更新遠端電腦上的 debugpy 版本。

Visual Studio Python Tools debugpy

2019 16.6 1.0.0b5 1.0.0b5

2019 16.5 1.0.0b1 1.0.0b1

Visual Studio	Python Tools	debugpy
2019 16.6	1.0.0b5	1.0.0b5
2019 16.5	1.0.0b1	1.0.0b1

注意

Visual Studio 2019 16.0-16.4 版已使用 ptvsd，而非 debugpy。本逐步解說中適用於這些版本的處理序很類似，但函式名稱不同。 Visual Studio 2019 16.5 版使用 debugpy，但函式名稱與 ptvsd 中的函式名稱相同。您會使用 enable_attach，而不是 listen。您會使用 wait_for_attach，而不是 wait_for_client。您會使用 break_into_debugger，而不是 breakpoint。

使用 ptvsd 3.x 進行舊版偵錯

在 Visual Studio 2017 15.7 版及更早版本中，ptvsd 3.x 舊版偵錯工具是預設值。

視您的 Visual Studio 組態而定，您可能需要使用 ptvsd 3.x 進行遠端偵錯：

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
早期 4.x 版本

如果您的組態實作較舊版本的案例，Visual Studio 會顯示錯誤，偵錯程式不支援這個 Python 環境。

安裝程式遠端偵錯

要準備使用 ptvsd 3.x 進行遠端偵錯，請完成以下步驟：

設定密碼，用於限制對執行中指令碼的存取。

在 ptvsd 3.x 中，enable_attach函式要求您傳遞一個"秘密"作為第一個引數。
- 當您附加遠端偵錯工具時，請使用指enable_attach(secret="<secret>")令輸入密碼。
雖然您可以允許任何人使用enable_attach(secret=None)命令進行連線，但不建議使用此選項。
在表單中建立您的tcp://<secret>@<ip_address>:5678連線目標 URL。
- tcp://將連線型別指定為 TCP。
- <secret>是在 Python 程式碼中與enable_attach函式一起傳遞的字串。
- <ip_address>是遠端電腦的 IP 位址，可以是明確位址或類似 myvm.cloudapp.net 的名稱。
- :5678是遠端偵錯連線埠號碼。

與 TCPS 協定的安全連線

依預設，與 ptvsd 3.x 遠端偵錯伺服器的連線僅受密碼保護，所有資料以純文字傳送。對於更安全的連線，ptvsd 3.x 使用 TCP 協定或 TCPS 的安全形式支援 SSL。

使用以下步驟配置 ptvsd 3.x 以使用 TCPS 協定：

在遠端電腦上，使用openssl指令為金鑰和自簽署憑證產生個別的檔案：
```
openssl req -new -x509 -days 365 -nodes -out cert.cer -keyout cert.key
```
- 在openssl提示下，輸入您用來連線 Common Name 的主機名稱或 IP 位址。
有關更多資訊，請參見 Python 模組文件中的 Self-signed ssl憑證。請注意，Python 文件中描述的命令僅生成單個組合檔案。
在程式碼中，使用檔案名稱作為值，修改對enable_attach函式的呼叫，以包含certfile和keyfile引數。這些引數與標準 ssl.wrap_socketPython 函式的含義相同。
```
ptvsd.enable_attach(secret='my_secret', certfile='cert.cer', keyfile='cert.key')
```
您也可以在本機電腦的程式碼檔案中進行相同的變更。因為這個程式碼並未實際執行，所以並非嚴格必要。
在遠端電腦上重新啟動 Python 程式，以便進行偵錯。
使用 Visual Studio 將憑證新增到 Windows 電腦上受信任的根 CA，以保護通道：
1. 將遠端電腦的憑證檔案複製到本機電腦。
2. 開啟 Control Panel，並移至 Windows >Tools Manage 電腦憑證。
3. 在 certlm [Certificates - local computer] 對話方塊中，展開 [Trusted Root Certification Authorities] 節點，按一下右鍵 [Certificates]，然後選取 [>All Tasks] 匯入。
4. 瀏覽並選取從遠端電腦複製的 .cer 檔案。
5. 繼續完成對話方塊提示以完成匯入程式。
在 Visual Studio 中重複附加過程，如先前的從 Python Tools 透過遠端附加中所述。

對於此例證，tcps://請定義為Connection Target (或Qualifier) 的通訊協定。

解決連線問題

在連線嘗試期間，Visual Studio 可能會遇到問題。檢視下列案例，然後視需要採取適當的動作。

透過 SSL 連線時，Visual Studio 會警告可能的憑證問題。

動作：您可以忽略訊息並繼續。

警告

請記住，儘管該頻道仍被加密以防範竊聽，但可能會被中間人攻擊。
Visual Studio 顯示遠端憑證不受信任警告。

問題：憑證未正確加入信任的根 CA。

動作：重新檢查將憑證新增到 Windows 電腦上受信任的根 CA 的步驟，然後再次嘗試連線。
Visual Studio 顯示遠端憑證名稱與主機名稱不相符。

問題：沒有為憑證的 Common Name 指定正確的主機名稱或 IP 位址。

動作：重新檢查 Secure the connection with TCPS 中的步驟。請確定在建立憑證時使用正確的 Common Name，然後再次嘗試連線。

遠端偵錯

共用方式為

在 Visual Studio 中遠端偵錯 Linux 上的 Python 程式碼

必要條件