PyCharm 2026.3 Help

使用 PyCharm 进行远程调试

使用 PyCharm,您可以通过位于另一台计算机上的解释器调试应用程序,例如在 Web 服务器或专用测试机器上。

PyCharm 提供两种远程调试方式:

  • 通过远程解释器。

    适用场景: 使用此方法可利用远程机器上可用的扩展调试功能。

    要求: 本地机器可通过 SSH 访问远程服务器。

  • 使用 Python 远程调试服务器配置。

    适用场景: 使用此方法将调试过程集成到远程服务器上一系列正在运行的进程中。 当您无法显式为调试运行应用程序,或需要先执行一些准备工作时,此方法会很有帮助。

    要求: 本地机器可通过 SSH 访问远程服务器,且远程服务器可通过任意预定义端口访问本地机器。

在开始之前

完成以下准备任务:

  1. 在本地机器上,按照 创建 Python 项目 中的说明创建纯 Python 项目。

  2. 向该项目添加一个 Python 文件(Alt+Insert - Python 文件)。

  3. 将以下代码添加到 Python 文件:

    import math class Solver: def demo(self, a, b, c): d = b ** 2 - 4 * a * c if d > 0: disc = math.sqrt(d) root1 = (-b + disc) / (2 * a) root2 = (-b - disc) / (2 * a) return root1, root2 elif d == 0: return -b / (2 * a) else: return "This equation has no roots" if __name__ == '__main__': solver = Solver() while True: a = int(input("a: ")) b = int(input("b: ")) c = int(input("c: ")) result = solver.demo(a, b, c) print(result)

为远程解释器创建部署配置

在本示例中,运行应用程序的机器称为 local ,带有远程解释器的机器称为 remote。

配置远程解释器

  1. 请确保您能够通过 SSH 访问远程机器。

  2. 按照 使用 SSH 配置解释器 中的说明将新的远程解释器添加到项目,并指定连接到远程机器所需的凭据。

  3. 为项目创建远程解释器后,将自动创建相应的部署配置。 要预览它,在本地机器上按 Ctrl+Alt+S 打开 设置 对话框,然后转到 构建、执行、部署 | 部署。

    部署配置
  4. 您可以接受所有默认设置,或在需要时进行更改。 在本示例中,我们将使用 MySFTPConnection 作为部署配置的名称。

  5. 请确保 根路径 的值与所创建 SSH 解释器相应设置中指定的路径一致。

    按 Ctrl+Alt+S 打开设置并转到 Python | 所有解释器。 选择已创建的 SSH 解释器,然后点击 显示解释器路径 (显示解释器路径)。 所选解释器的现有路径会显示在 解释器路径 对话框中。

现在,您的部署配置已就绪。

将应用程序部署到远程主机

接下来,您需要将应用程序部署到远程主机。

  1. 在 工具 菜单中,选择 部署 | 上传到 MySFTPConnection。

  2. 文件传输 工具窗口会显示。 验证传输的文件数量。

    文件传输窗口

调试应用程序

  1. 在编辑器背景处右键点击,选择 调试 <FileName> (此处为 调试 'quadratic_equation')。

  2. 查看调试输出。

    在远程服务器上调试

使用 Python 远程调试服务器配置进行远程调试

还可以使用专用的运行/调试配置启用远程调试: Python 调试服务器。

创建运行/调试配置

  1. 转到 运行| 编辑配置… 。将打开 运行/调试配置对话框。 在工具栏上点击 添加配置 ,并在可用配置列表中选择 Python 调试服务器。

    添加 Python 远程调试配置
  2. 输入此运行/调试配置的名称——就用 MyRemoteServer。 指定运行 IDE 的机器的 端口 编号(此处为 12345 )和 IDE 主机名 (此处为 192.168.106.73)。 这些参数将由远程调试服务器用于访问该机器。

  3. 在 路径映射 字段中点击 。 将本地机器上的路径映射到远程机器上的路径:

    路径映射
  4. 查看 更新您的脚本 说明。 您可以使用 PyCharm 安装中的 pydevd-pycharm.egg ( <%instance% directory>/debug-eggs/pydevd-pycharm.egg ),或使用 pip 安装 pydevd-pycharm 包。

    根据您的选择,执行以下更改:

    • 在远程机器上运行以下命令来安装 pydevd-pycharm 包:

      pip install pydevd-pycharm~=<version of PyCharm on the local machine>

      例如, pip install pydevd-pycharm~=242.20224.428)

    • 按如下方式修改源代码文件:

    import math #==============this code added==================================================================: import pydevd_pycharm pydevd_pycharm.settrace('192.168.106.73', port=12345, stdout_to_server=True, stderr_to_server=True) #================================================================================================ class Solver: def demo(self, a, b, c): d = b ** 2 - 4 * a * c if d > 0: disc = math.sqrt(d) root1 = (-b + disc) / (2 * a) root2 = (-b - disc) / (2 * a) return root1, root2 elif d == 0: return -b / (2 * a) else: return "This equation has no roots" if __name__ == '__main__': solver = Solver() while True: a = int(input("a: ")) b = int(input("b: ")) c = int(input("c: ")) result = solver.demo(a, b, c) print(result)

    按如下方式修改代码:

    import math #==============this code added==================================================================: import sys sys.path.append("<PyCharm directory>/debug-eggs/pydevd-pycharm.egg") import pydevd_pycharm pydevd_pycharm.settrace('172.20.208.95', port=12345, stdout_to_server=True, stderr_to_server=True) #================================================================================================ class Solver: def demo(self, a, b, c): d = b ** 2 - 4 * a * c if d > 0: disc = math.sqrt(d) root1 = (-b + disc) / (2 * a) root2 = (-b - disc) / (2 * a) return root1, root2 elif d == 0: return -b / (2 * a) else: return "This equation has no roots" if __name__ == '__main__': solver = Solver() while True: a = int(input("a: ")) b = int(input("b: ")) c = int(input("c: ")) result = solver.demo(a, b, c) print(result)

创建 SFTP 连接

  1. 在远程机器上创建一个目录,用于上传文件 quadratic_equation.py 。 您可以在 Terminal 窗口中执行此操作:

    $cd /tmp $mkdir pycharm_project_986
  2. 在本地机器上创建一个连接配置。 转到 工具 | 部署 | 配置… 。在打开的对话框中,点击 添加服务器 ,并在 添加服务器 对话框中选择连接类型(此处为 SFTP),并输入其名称(此处为 MySFTPConnection)。

  3. 在 连接 选项卡中,指定 SFTP 主机(远程机器的地址)、该机器的用户名和密码。

    请注意,指定的用户应具有对远程主机的 SSH 访问权限。

  4. 点击 映射 选项卡,并在服务器上输入部署路径。 点击浏览按钮并选择所需文件夹 /tmp/pycharm_project_986 。 请注意,浏览按钮显示的是远程主机的内容。 应用更改并关闭对话框。

将文件部署到远程机器

  1. 将以下文件部署到远程机器: pydevd-pycharm.egg 和 quadratic_equation.py 。

    在本地机器上的 项目工具窗口 中,选择文件,右键点击所选内容并选择 部署 | 上传到 MySFTPConnection。

  2. 检查 文件传输 对话框,确保来自本地机器的文件已上传到远程服务器。

    文件传输窗口

启动调试服务器

  1. 选择已创建的运行/调试配置,并点击 调试:

    运行调试配置
  2. 确保 Debug 窗口 显示 正在等待进程连接… 消息。 该消息会一直显示,直到您在远程机器上启动脚本,并且该脚本连接到调试服务器。

在远程机器上执行 Python 文件

  1. 在远程机器上,导航到 tmp/pycharm_project_986 目录。

  2. 在远程主机上启动 quadratic_equation.py 文件。 为此,请在 Terminal 窗口中输入以下命令:

    $python3 quadratic_equation.py
    $python quadratic_equation.py

    该调试方法的最大优势在于,当远程调试是计划任务的一部分,或在运行 Python 脚本之前需要执行一些准备步骤时,您可以通过任意 bash 脚本来运行该 Python 文件。 如果是这种情况,请在您的 bash 脚本的适当位置添加以下几行:

    cd /tmp/pycharm_project_986 python3 quadratic_equation.py
    cd /tmp/pycharm_project_986 python quadratic_equation.py

调试应用程序

  • 在本地机器上,切换到 Debug 窗口。 它将显示与 pydev 调试器的连接。

    您的代码实际上在远程主机上执行,但在本地机器上进行调试。

使用 Python 调试服务器调试本地进程工具窗口。此操作在

还可以在运行 PyCharm 的机器上使用 Python 调试服务器 配置。 当无法从 PyCharm 运行/调试配置启动程序时,这会很有用,例如:

  • shell 脚本会启动 Python 解释器。

  • 程序会启动一个调试器不会自动附加到的进程,即使选择了 调试时自动附加到子进程 选项(在 Python 调试器 设置页面上)也是如此。

由于代码在同一台机器上运行,因此不需要部署配置或路径映射。

调试本地进程

  1. 创建 Python 调试服务器 运行/调试配置,如 创建运行/调试配置 中所述。 保留默认 IDE 主机名 值 localhost ,指定 端口 编号,并将 路径映射 留空。

  2. 将 pydevd-pycharm 软件包安装到运行程序的解释器中。 使用与 PyCharm 构建匹配的版本:运行 pip install pydevd-pycharm~=<build number> 命令,该命令来自配置的 更新您的脚本 说明。 或者,将 pydevd-pycharm.egg (来自 PyCharm 安装)添加到 Python 路径。

  3. 将配置的 更新您的脚本 说明中的代码添加到程序,例如:

    import pydevd_pycharm pydevd_pycharm.settrace('localhost', port=12345, stdout_to_server=True, stderr_to_server=True)

    如果程序启动其他 Python 进程,请将此代码添加到在这些进程中运行的代码中。

  4. 在调试模式下启动配置。 调试窗口 会显示 正在等待进程连接… 消息。

  5. 以常规方式启动程序,例如运行 shell 脚本。 当程序执行 settrace() 调用时,会连接到 PyCharm,然后可以在 调试 工具窗口中进行调试。

要在不更改代码的情况下调试已在运行的本地 Python 进程,请使用 附加到进程。

总结

为了使用远程解释器进行调试,您必须通过 PyCharm 启动程序,这并不总是可行。 另一方面,使用调试服务器时,您可以连接到正在运行的进程。

比较这两种方法。

在第一种情况下,我们

在第二种情况下,我们

2026年 11月 3日