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

在本文中，您將探索如何設定 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 支援。

• 在 macOS 或 Linux 等作系統上執行 Python 的遠端電腦。

• 埠 5678 （輸入） 會在遠端電腦的防火牆上開啟，這是遠端偵錯的預設值。

設定 Linux 電腦

您可以輕鬆地在 Azure 上建立 Linux 虛擬機，並使用 Windows 的遠端桌面 來 存取它。 虛擬機的Ubuntu很方便，因為預設會安裝 Python。 如果您有不同的設定，請參閱 安裝 Python 解釋器，以尋找其他 Python 下載位置。

設定防火牆

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

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

• 使用 Azure 入口網站透過網路安全組來篩選網路流量
• 使用 Azure 入口網站路由表路由傳送網路流量
• 使用 Azure 入口網站部署及設定 Azure 防火牆

準備腳本以進行偵錯

請遵循下列步驟來準備腳本，以偵錯 Linux 上的 Python 程式代碼。

1. 在遠端電腦上，使用下列程式代碼建立名為 guessing-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))
   

2. 使用 pip3 install debugpy 命令，將 debugpy 套件安裝到您的環境中。

   注意

   最好記錄所安裝的 debugpy 版本，以備可能需要進行疑難解答。 debugpy 清單 也會顯示可用的版本。

3. 在其他程序代碼之前，將下列程式代碼新增到 guessing-game.py 檔案頂端，以啟用遠端偵錯。 （雖然不是嚴格的需求，但在呼叫 listen 函式之前，無法偵錯任何繁衍的背景線程。

   import debugpy
   debugpy.listen(('0.0.0.0', 5678))
   

4. 儲存盤案並執行程式：

   python3 guessing-game.py
   

   listen 函式的呼叫會在背景執行，並在您與程式互動時等候連入連線。 如有需要，您可以在呼叫 listen 函式之後呼叫 wait_for_client 函式，以封鎖程式，直到調試器連接為止。

提示

除了 listen 和 wait_for_client 函式之外，debugpy 也會提供協助程式函式 breakpoint。 如果附加調試程式，此函式會做為程式設計斷點。 如果附加調試程式，另一個函式 is_client_connected1會傳回 True。 呼叫任何其他 debugpy 函式之前，您不需要檢查此結果。

使用 Python 工具遠端連接

下列步驟示範如何設定斷點來停止遠程進程。

1. 在本機計算機上建立遠端檔案的複本，並在 Visual Studio 中開啟它。 檔案所在的位置並不重要，但其名稱應該符合遠端電腦上的腳本名稱。

2. （選擇性）若要讓 IntelliSense 在本機電腦上偵錯py，請將 debugpy 套件安裝到 Python 環境中。

3. 選取 偵錯>附加至進程。

4. 在 [附加至程序] 對話框中，將 [連線類型] 設定為 Python 遠端(debugpy)。

5. 在 [連線目標] 欄位中，輸入命令 tcp://<ip_address>:5678。

   • tcp:// 將連線類型指定為傳輸控制通訊協定 （TCP）。
   • <ip_address> 是遠端電腦的 IP 位址，可以是明確的位址或名稱，例如 myvm.cloudapp.net。
   • :5678 是遠端偵錯埠號碼。

6. 選擇 [] 並輸入 [] 以填入該電腦上的可用 debugpy 程式清單：

   

   如果您在填入此列表後，於遠端電腦上啟動了另一個程式，請選取 [重新整理] 按鈕。

7. 選取要偵錯的程序，然後選取 [附加]，或雙擊程序。

8. Visual Studio 會在腳本繼續在遠端電腦上執行時切換到偵錯模式，並提供所有一般 偵錯 功能。

   您可以在 if guess < number: 行上設定斷點，然後切換至遠端計算機，然後輸入另一個猜測。 本機電腦上的 Visual Studio 會在斷點停止、顯示局部變數等等：

   

9. 當您停止偵錯時，Visual Studio 會從程式中斷連結。 程式會繼續在遠端電腦上執行。 debugpy 也會繼續監聽連接偵錯器，因此您可以隨時重新連接至程式。

針對連線進行疑難解答

檢視下列指示，以協助解決連線問題。

• 請確認您在 連線類型中選擇 Python 遠端（debugpy）。

• 確認 連線目標中的秘密 與遠端程式代碼中的秘密完全相符。

• 確認 連線目標中的IP位址 符合遠端電腦的IP位址。

• 確認遠端電腦上的遠端偵錯連接埠已開啟，且連線目標包含埠後綴，例如 :5678。

  若要使用不同的埠，請在呼叫 listen 函式時指定埠號碼，如 debugpy.listen((host, port))中所示。 在此情況下，請務必在防火牆中開啟特定埠。

• 確認安裝在遠端電腦上的 debugpy 版本（如 pip3 list 命令所傳回）符合 Visual Studio Python Tools （PTVS） 版本。

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

  Visual Studio	Python 工具	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 中的名稱相同。 不是使用 listen，而是使用 enable_attach。 與其使用 wait_for_client，您會使用 wait_for_attach。 您會使用 break_into_debugger，而不是 breakpoint。

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

ptvsd 3.x 舊版調試程式是 Visual Studio 2017 15.7 版和更早版本中的預設值。

視 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 進行遠端偵錯，請完成下列步驟：

1. 設定您的秘密，用來限制對執行中腳本的存取。

   在 ptvsd 3.x 中，enable_attach 函式會要求您傳遞「秘密」做為第一個自變數。

   • 當您附加遠端調試程式時，請使用 enable_attach(secret="<secret>") 命令輸入秘密。

   雖然您可以使用 enable_attach(secret=None) 命令允許任何人連線，但不建議使用此選項。

2. 在 表單建立連線目標 URL tcp://<secret>@<ip_address>:5678。

   • tcp:// 將連線類型指定為 TCP。
   • <secret> 是使用 Python 程式代碼中 enable_attach 函式傳遞的字串。
   • <ip_address> 是遠端電腦的 IP 位址，可以是明確的位址或名稱，例如 myvm.cloudapp.net。
   • :5678 是遠端偵錯埠號碼。

使用 TCPS 通訊協定保護連線

根據預設，ptvsd 3.x 遠端偵錯伺服器的連線只會受到秘密保護，所有數據都會以純文本傳遞。 如需更安全的連線，ptvsd 3.x 支援 SSL，方法是使用 TCP 通訊協定的安全形式，或 TCPS。

使用下列步驟來設定 ptvsd 3.x 以使用 TCPS 通訊協定：

1. 在遠端電腦上，使用 openssl 命令來產生金鑰和自我簽署憑證的個別檔案：

   openssl req -new -x509 -days 365 -nodes -out cert.cer -keyout cert.key
   

   • 在 openssl 提示符，輸入用於連線的主機名稱或 IP 地址，這些對應於 的「一般名稱」。

   如需詳細資訊，請參閱 Python ssl 模組檔中 自我簽署憑證。 請注意，Python 檔中所述的命令只會產生單一合併的檔案。

2. 在程式代碼中，修改對 enable_attach 函式的呼叫，以使用檔名作為值來包含 certfile 和 keyfile 自變數。 這些自變數與標準 ssl.wrap_socket Python 函式的意義相同。

   ptvsd.enable_attach(secret='my_secret', certfile='cert.cer', keyfile='cert.key')
   

   您也可以在本機電腦上的程式碼檔案中進行相同的變更。 因為此程式代碼實際上並未執行，因此並非絕對必要。

3. 重新啟動遠端電腦上的 Python 程式，使其準備好進行偵錯。

4. 使用 Visual Studio 將憑證新增至 Windows 電腦上的受信任根 CA，以確保通道安全：

   1. 將憑證檔案從遠端計算機複製到本機計算機。

   2. 開啟 [控制面板]，然後移至 [Windows 工具]>[管理計算機憑證]。

   3. 在 [憑證 - 本機計算機] 對話框中，展開 [信任的根憑證授權單位] 節點，以滑鼠 右鍵點擊 [憑證]，然後選取 [所有工作>匯入]。

   4. 瀏覽至並選取從遠端電腦複製的 .cer 檔案。

   5. 繼續執行對話框提示以完成匯入程式。

5. 重複 Visual Studio 中的附加程式，如先前 從 Python 工具遠端附加中所述。

   針對這個實例，請將 tcps:// 定義為 連接目標 的通訊協定（或 限定符）。

   

解決連線問題

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

• Visual Studio 會在透過 SSL 連線時警告潛在的憑證問題。

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

  謹慎

  請記住，雖然通道仍然加密，以防止竊聽，但它可以開放給中間人攻擊。

• Visual Studio 會顯示 遠端憑證不受信任 警告。

  問題：憑證未正確新增至信任的根 CA。

  動作：重新 檢查將憑證新增至 Windows 電腦上的受信任根 CA 的步驟，然後再試一次連線。

  

• Visual Studio 會顯示 遠端憑證名稱不符合主機名 警告。

  問題：憑證的 一般名稱 未指定適當的主機名或IP位址。

  動作：重新檢查 使用 TCPS 保護連線的步驟。 當您建立憑證時，請務必使用正確的 Common Name，然後再試一次連線。

  

相關內容

• 遠端偵錯