使用 VNC + VS-Code 进行 PyQt 程序断点调试

---

使用 VNC + VS-Code 进行 PyQt 程序断点调试

在远程服务器上开发 PyQt 应用时，很多开发者选择通过 VNC（Virtual Network Computing）来进行图形界面的操作和调试。然而，在 VNC 环境中使用 VS Code 来调试 PyQt 程序时，可能会遇到一些问题，如 GUI 无法显示、断点无法触发等。本文将介绍如何在 VNC 上通过 VS Code 进行 PyQt 程序的断点调试。

环境准备

在本文中，我们假设你已经配置好了以下环境：

1. VNC 服务器：你可以通过 VNC 客户端连接到远程服务器，进行图形化界面的操作。
2. VS Code：在 VNC 环境下，你可以通过 VS Code 来进行程序开发和调试。
3. PyQt5：你已安装了 PyQt5 来开发图形界面程序。

提示：如果你尚未配置 VNC 服务器，可以参考 VNC 配置教程 来完成 VNC 服务端的设置。

在 VNC 中调试 PyQt 程序时的常见问题

在 VNC 环境下，最常见的调试问题包括：

• GUI 界面不显示：程序运行时，窗口未弹出，无法交互。
• 断点无法触发：设置的断点无法被触发，程序卡住或无法继续执行。

这些问题通常是由于 环境变量设置不当、主线程被调试器锁住 或 图形驱动未正确配置 导致的。

解决方案

Step 1：确认 DISPLAY 环境变量

VNC 环境的图形界面通常使用 DISPLAY 环境变量来指定显示设备。在连接到 VNC 服务器后，我们需要确认当前的 DISPLAY 变量设置。

打开终端并运行以下命令：

echo $DISPLAY

你将看到类似以下的输出：

:1

这个值 :1 就是你当前 VNC 会话的显示编号。记住这个值，接下来会用它来配置 VS Code。

Step 2：配置 VS Code 的 launch.json

在 VS Code 中，我们需要为调试器配置正确的环境变量，确保调试时 PyQt 能够连接到 VNC 会话中的图形显示。

1. 打开 VS Code，进入你的项目文件夹。
2. 如果你没有 .vscode/launch.json 文件，可以在调试面板中点击 创建一个 launch.json 文件。
3. 在 launch.json 中添加以下配置：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: PyQt in VNC",
      "type": "python",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "env": {
        "DISPLAY": ":1",  // 根据你实际的 DISPLAY 设置
        "QT_QPA_PLATFORM_PLUGIN_PATH": "/home/elon/.conda/envs/elon_clone/lib/python3.8/site-packages/PyQt5/plugins/platforms",
        "LIBGL_ALWAYS_INDIRECT": "1",
        "LIBGL_DRIVERS_PATH": "/usr/lib/x86_64-linux-gnu/dri",
        "FONTCONFIG_PATH": "/etc/fonts"
      }
    }
  ]
}

在这个配置中，DISPLAY 设置为你 VNC 会话的显示编号（如 :1）。QT_QPA_PLATFORM_PLUGIN_PATH 配置了 Qt 平台插件路径，确保 GUI 可以正确加载。同时，LIBGL_ALWAYS_INDIRECT 和 FONTCONFIG_PATH 变量用来解决图形驱动和字体配置的问题。

Step 3：配置 console 为 integratedTerminal

确保在 launch.json 配置中，console 设置为 "integratedTerminal"，这样 PyQt 窗口才能在 VNC 中正常显示。不要设置为 "internalConsole"，因为它不会启动图形界面。

"console": "integratedTerminal"

Step 4：调整程序代码

确保你的 PyQt 程序在启动时不会阻塞事件循环。你可以通过以下方式修改程序，避免阻塞主线程：

import sys
from PyQt5.QtCore import QTimer
from PyQt5.QtWidgets import QApplication, QMainWindow, QPushButton

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("调试测试")
        self.setGeometry(100, 100, 300, 200)

        btn = QPushButton("点击我", self)
        btn.clicked.connect(self.on_click)
        btn.move(100, 80)

    def on_click(self):
        print("按钮被点击")
        # ✅ 在这里设置断点
        x = 1  # 👈 断点就在这里
        print("继续执行")

def run():
    app = QApplication(sys.argv)
    window = MainWindow()
    window.show()

    # 用 QTimer 保持事件循环活跃
    def loop():
        app.processEvents()
        QTimer.singleShot(50, loop)  # 每 50ms 处理一次事件

    loop()
    sys.exit(app.exec_())

if __name__ == "__main__":
    run()

Step 5：启动调试

1. 在 VS Code 中打开你需要调试的 PyQt 程序。
2. 确保你选择了 Python: PyQt in VNC 配置。
3. 按下 F5 或点击左侧的 调试按钮 开始调试。

这样，你就可以在 VNC 环境下启动并调试你的 PyQt 程序了，断点也能正确触发，GUI 界面会正常弹出。

常见问题解决

1. GUI 不显示：

   • 确保 DISPLAY 环境变量正确，设置为你当前 VNC 会话的显示编号（如 :1）。
   • 使用 QTimer 保持事件循环运行，确保界面保持活跃。

2. 图形驱动错误：

   • 使用 LIBGL_ALWAYS_INDIRECT 和 LIBGL_DRIVERS_PATH 配置来绕过硬件加速问题。
   • 安装缺失的图形驱动和字体库：libgl1-mesa-glx、libgl1-mesa-dri 和 fontconfig。

3. 调试界面卡住：

   • 确保你使用的是 integratedTerminal 而非 internalConsole。
   • 调试时，避免在 app.exec_() 之前设置断点，最好在按钮回调或信号槽中设置断点。

结语

通过以上步骤，你可以在 VNC 环境中顺利地用 VS Code 调试 PyQt 程序，解决了 GUI 界面不显示和断点无法触发的问题。这样，你可以更加高效地进行图形界面应用的开发和调试。

希望这篇文章对你有所帮助，祝你调试愉快！

---

这样写的博客大致内容已经覆盖了从环境配置到调试问题解决的全过程，适合 VNC 环境下的 PyQt 调试。如果需要更多修改或细节，可以随时告诉我！