在 VS Code 中进行 Python 调试

Python 扩展支持通过 Python 调试器扩展 调试多种类型的 Python 应用程序。有关基本调试的简短演示，请参阅 教程 - 配置和运行调试器。另请参阅 Flask 教程。两个教程都展示了设置断点和逐行执行代码等核心技能。

对于诸如检查变量、设置断点以及其他不依赖于语言的调试功能，请参阅VS Code 调试。

本文主要讨论Python特定的调试配置，包括特定应用类型和远程调试的必要步骤。

Python 调试器扩展

Python调试器扩展会自动安装在Python扩展中，适用于VS Code。它提供通过debugpy进行的多种Python应用程序的调试功能，包括脚本、网络应用、远程进程等。

要验证它是否已安装，请打开扩展视图 (⇧⌘X (Windows, Linux Ctrl+Shift+X)) 并搜索@已安装的Python调试器您应该在结果中看到Python Debugger扩展。

你可以参考扩展的README页面以获取支持的Python版本信息。

初始化配置

配置驱动VS Code在调试会话期间的行为。配置在文件中定义。launch.json存储在文件中的文件.vscode在你的工作区中创建一个文件夹。

注意：要更改调试配置，您的代码必须存储在文件夹中。

要初始化调试配置，请首先在侧栏中选择运行视图：

如果您还没有定义任何配置，您将看到一个按钮来运行和调试以及一个创建配置（launch.json）文件的链接：

生成一个launch.json文件包含Python配置，请执行以下步骤：

1. 选择创建 launch.json 文件 链接（在上面的图像中突出显示）或使用运行 > 打开配置 菜单命令。

2. 选择 Python 调试器 从调试器选项列表中。

3. 从命令面板中将打开一个配置菜单，允许您选择要用于我们Python项目文件的调试配置类型。如果您想调试单个Python脚本，请在出现的选择调试配置菜单中选择Python文件。

   

   注意：通过调试面板启动调试会话，F5，或在没有配置的情况下 运行 > 启动调试，也会弹出调试配置菜单，但不会创建一个launch.json文件。

4. Python 调试器扩展然后创建并打开一个launch.json 包含基于您之前选择的预定义配置的文件，本例中为 Python 文件。您可以修改配置（例如添加参数），还可以添加自定义配置。

   

配置属性的详细信息将在本文的 标准配置和选项 部分 later 被涵盖。其他配置也在本文的 调试特定应用类型 部分描述。

附加配置

默认情况下，VS Code 只显示 Python 调试器扩展提供的最常见配置。您可以选择其他配置以包含在内。launch.json 使用 添加配置 命令在列表中显示，并且 launch.json 编辑器。使用该命令时，VS Code 会提示您选择所有可用的配置（请确保选择Python 选项）：

选择 通过进程ID附加 时，结果如下：

参见调试特定应用类型 以了解所有这些配置的详细信息。

在调试过程中，状态栏显示当前配置和当前调试解释器。选择配置会弹出一个列表，从中您可以选择其他配置：

默认情况下，调试器使用为你的工作区选择的相同的解释器，就像 VS Code 的 Python 扩展的其他功能一样。要为调试专门使用不同的解释器，请设置 的值Python在launch.json适用于特定调试器的配置。或者，使用状态栏上的Python解释器指示器来选择其他的解释器。

基本调试

如果你只对调试Python脚本感兴趣，最简单的方法是选择编辑器中运行按钮旁边的下箭头，然后选择Python调试器：调试Python文件。

如果你想要使用Flask、Django或FastAPI调试一个网页应用程序，Python Debugger扩展提供了基于你的项目结构的动态创建的调试配置，通过显示所有自动调试配置选项，在运行和调试视图中。

但是如果你想要调试其他种类的应用程序，你可以通过运行视图点击运行和调试按钮启动调试器。

当没有设置任何配置时，您将看到一个调试选项列表。在这里，您可以选择适当的选项来快速调试您的代码。

两个常见的选项是使用Python 文件配置来运行当前打开的Python文件，或者使用通过进程ID附加配置将调试器附加到已经运行的进程。

有关创建和使用调试配置的信息，请参阅初始化配置和附加配置部分。一旦添加了配置，就可以从下拉列表中选择并使用开始调试按钮（F5）启动。

命令行调试

调试器也可以从命令行运行，如果调试工具 debugpy已安装在你的Python环境中。

安装 debugpy

你可以使用debugpy进行安装python -m pip install --upgrade 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）和脚本启动调试器，使用以下语法。此示例假定脚本是长时间运行的，并省略了--等待客户端标志，表示脚本将不会等待客户端连接。

python -m debugpy --listen 5678 ./myscript.py

然后，您将使用以下配置将 VS Code Python 调试器扩展附加到目标。

{
  "name": "Python Debugger: Attach",
  "type": "debugpy",
  "request": "attach",
  "connect": {
    "host": "localhost",
    "port": 5678
  }
}

注意：在listen中指定主机是可选的，如果不指定，将默认使用127.0.0.1。

如果你想要调试远程代码或在远程机器或容器中运行的代码，你需要修改之前的 CLI 命令来指定一个主机。

python -m debugpy --listen 0.0.0.0:5678 ./myscript.py

相关的配置文件将如下所示。

{
  "name": "附加",
  "类型": "debugpy",
  "请求": "附加",
  "连接": {
    "主机": "远程机器名称", // 用远程机器名称替换
    "端口": 5678
  }
}

注意：请意识到当您指定一个主机值而不是127.0.0.1或本地主机您正在打开一个端口以允许从任何机器访问，这存在安全风险。在进行远程调试时，您应该确保采取适当的的安全措施，例如使用SSH隧道。

命令行选项

注意：[<参数>]可以将命令行参数传递给正在启动的应用程序。

通过网络连接附加进行调试

本地脚本调试

可能有需要调试由另一个进程本地调用的Python脚本的情况。例如，您可能正在调试一个运行特定处理作业的不同Python脚本的网页服务器。在这种情况下，您需要在脚本启动后将其附加到VS Code调试器：

1. 运行 VS Code，打开包含脚本的文件夹或工作区，并创建一个launch.json为该工作区创建一个，如果还没有的话。

2. 在脚本代码中，添加以下内容并保存文件：

   导入 debugpy
   
   # 5678 是 VS Code 调试配置中的默认附加端口。除非指定了主机和端口，否则主机默认为 127.0.0.1
   debugpy.listen(5678)
   print("正在等待调试器附加")
   debugpy.wait_for_client()
   debugpy.breakpoint()
   print('在此行上设置断点')
   

3. 使用 终端：创建新终端打开一个终端，这将激活脚本选择的环境。

4. 在终端中，安装 debugpy 包。

5. 在终端中，使用脚本启动Python，例如，python3 myscript.py你应该会看到代码中包含的“等待调试器附加”消息，并且脚本在该处停止。debugpy.wait_for_client()呼叫。

6. 切换到运行和调试视图 (⇧⌘D (Windows, Linux Ctrl+Shift+D))，从调试器下拉列表中选择适当的配置，并启动调试器。

7. 调试器应该在...处停止debugpy.breakpoint()调用，从这一点开始，你可以正常使用调试器。你还可以通过用户界面在脚本代码中设置其他断点，而不是使用debugpy.breakpoint()输入：.

使用 SSH 进行远程脚本调试

远程调试允许您在远程计算机上运行程序时，在 VS Code 中本地逐步执行该程序。无需在远程计算机上安装 VS Code。为了增加安全性，您可能需要或需要在调试时使用到远程计算机的 secure 连接，例如 SSH。

注意：在Windows计算机上，您可能需要安装Windows 10 OpenSSH以拥有安全外壳协议命令。

以下步骤概述了设置 SSH 隧道的通用过程。SSH 隧道允许您在本地机器上工作，就像直接在远程机器上工作一样，比开放公共访问的端口更安全。

在远程计算机上：

1. 通过打开启用端口转发sshd配置文件配置文件（在下找到）/etc/ssh/在 Linux 下和在 之下%programfiles(x86)%/openssh/etc在Windows上) 并添加或修改以下设置：

   允许TCP转发 是
   

   注意：默认情况下，允许TCP端口转发，所以您可能不需要进行更改。

2. 如果你必须添加或修改允许TCP转发重启SSH服务器。在Linux/macOS上，运行请将以下文本翻译成中文: sudo service ssh restart在 Windows 上，运行services.msc, 选择 OpenSSH 或sshd在服务列表中，选择重启。

在本地计算机上：

1. 通过运行创建一个SSH隧道ssh -2 -L 源端口:本地主机:目标端口 -i 身份文件 用户@远程地址，使用选定的端口目的端口以及适当的用户名和远程计算机的IP地址用户@远程地址例如，要使用IP地址1.2.3.4上的5678端口，命令将是ssh -2 -L 5678:localhost:5678 -i identityfile user@1.2.3.4你可以指定身份文件的路径，使用-我旗帜。

2. 验证你能在SSH会话中看到提示。

3. 在你的 VS Code 工作区中，创建一个用于远程调试的配置launch.json文件，将端口设置为与所使用的端口匹配安全外壳协议命令和主机到本地主机. 你使用本地主机在这里，因为您已经设置好了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. 在源代码中，添加以下行，替换地址使用远程计算机的IP地址和端口号（这里仅作示例显示IP地址为1.2.3.4）。

      导入 debugpy
      
      # 允许其他计算机在此IP地址和端口附加到debugpy进行调试。
      debugpy.listen(('1.2.3.4', 5678))
      
      # 暂停程序，直到附加远程调试器
      debugpy.wait_for_client()
      

      使用的IP地址听应该是远程计算机的私有IP地址。然后你可以正常启动程序，使其暂停直到调试器附加。

   2. 通过 debugpy 启动远程进程，例如：

      python3 -m debugpy --listen 1.2.3.4:5678 --wait-for-client -m myproject
      

      这开始了一个软件包我的项目使用Python3，远程计算机的私有IP地址为1.2.3.4正在监听端口5678（您也可以通过指定文件路径而不是使用来启动远程Python进程-米例如./hello.py)。

4. 本地计算机：只有在你按照上述说明在远程计算机上修改了源代码，那么在源代码中，添加与远程计算机上添加的相同代码的注释副本。添加这些行确保两台计算机上的源代码逐行匹配。

   #导入 debugpy
   
   # 允许其他计算机在此IP地址和端口附加到debugpy进行调试。
   #debugpy.listen(('1.2.3.4', 5678))
   
   # 暂停程序，直到连接远程调试器
   #debugpy.wait_for_client()
   

5. 本地计算机：切换到运行和调试视图（⇧⌘D（Windows, Linux Ctrl+Shift+D））在VS Code中，选择Python调试器：附加配置

6. 本地计算机：在代码中设置一个断点，从该处开始调试。

7. 本地计算机：使用修改后的Python 调试器：附加 配置和“开始调试”按钮启动 VS Code 调试器。VS Code 应该在您本地设置的断点处停止，允许您逐步执行代码、检查变量并执行所有其他调试操作。您在调试控制台中输入的表达式也会在远程计算机上运行。

   文本输出到标准输出，自打印语句在两台计算机上都显示。然而，其他输出，例如像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}",
      "控制台": "外部终端"
    }
  ]
}

具体设置在以下各节中描述。您还可以添加其他设置，例如参数，不包括在标准配置中。

提示：在项目中，创建一个运行特定启动文件的配置通常很有帮助。例如，如果你总是想启动 startup.py使用参数--端口 1593当你启动调试器时，创建一个配置条目如下：

 {
     "name": "Python 调试器: startup.py",
     "type": "debugpy",
     "request": "launch",
     "program": "${workspaceFolder}/startup.py",
     "args" : ["--port", "1593"]
 },

名字

提供在 VS Code 下拉列表中显示的调试配置名称。

类型

标识要使用的调试器类型；将此设置保持为调试工具 debugpy用于调试Python代码。

请求

指定调试启动模式：

• 发射: 在指定的文件上启动调试器程序
• 附加：附加调试器到已运行的进程。参见远程调试 例子。

程序

提供到python程序入口模块（启动文件）的完全限定路径。该值${文件}，通常在默认配置中使用，使用编辑器中当前活动的文件。通过指定一个特定的启动文件，无论打开哪些文件，您都可以确保以相同的入口点启动您的程序。例如：

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

您还可以依赖于从工作区根目录的相对路径。例如，如果根目录是/用户/我/项目/我的项目然后你可以使用以下示例：

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

模块

提供指定要调试的模块名称的能力，类似于-米 在命令行中运行时的参数。有关更多信息，请参见 Python.org

Python

用于调试的Python解释器的完整路径。

如果没有指定，此设置默认为为您工作区选择的解释器，这相当于使用值${命令:python.解释器路径}要使用不同的解释器，请在 中指定其路径。Python调试配置的属性。

或者，您可以使用在每个平台上定义的自定义环境变量，该变量包含要使用的Python解释器的完整路径，这样就不需要其他文件夹路径。

如果你需要向Python解释器传递参数，可以使用python参数财产。

python参数

使用语法指定传递给Python解释器的参数"pythonArgs": ["输入：.

参数

指定传递给Python程序的参数。每个用空格分隔的参数字符串元素应包含在引号中，例如：

"参数": ["--安静", "--不重复", "--端口", "1593"],

如果你希望在每次调试运行时提供不同的参数，你可以设置参数至"${command:pickArgs}"这将每次在您开始调试会话时提示您输入参数。

注意：在如何"${command:pickArgs}"和["${命令:pickArgs}"]解析，特别注意到的使用[]作为数组时，所有参数作为一个字符串传递，不带括号。每个参数作为单独的字符串传递。

停止进入

当设置为真在调试程序的第一行处中断调试器。如果省略（默认）或设置为假调试器运行程序到第一个断点。

控制台

指定程序输出的显示方式，同时使用默认设置重定向输出没有被修改。

目的

配置运行 按钮的方法不止一种，可以使用 目的选项。将选项设置为调试测试定义了在 VS Code 中调试测试时应使用的配置。 然而，将该选项设置为在终端中调试，定义了该配置仅在访问编辑器右上角的运行Python文件按钮时使用（无论按钮提供的是运行Python文件还是调试Python文件选项）。 注意： 目的 选项不能通过 F5 或 运行 > 启动调试 来启动调试器。

自动重新加载

允许在调试器执行遇到断点后对代码进行更改时自动重新加载调试器。要启用此功能，请设置{"enable": true}如下代码所示。

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

注意：当调试器重新加载时，导入的代码可能会再次执行。为了避免这种情况，请尽量只在模块中使用导入、常量和定义，将所有代码放入函数中。或者，您也可以使用if __name__=='__main__'支票。

子过程

指定是否启用子进程调试。默认为假，设置为真 以启用。有关更多信息，请参阅 多目标调试。

当前工作目录

指定调试器的当前工作目录，该目录是代码中使用的所有相对路径的基目录。如果省略，则默认为${工作区文件夹}（在 VS Code 中打开文件夹）。

例如，假设${工作区文件夹}包含一个py代码文件夹包含app.py，和一个数据文件夹包含salaries.csv. 如果你开始在 上调试器py_code/app.py，则相对于数据文件的路径会根据 的值而变化当前工作目录输入：

重定向输出

当设置为真（内部控制台的默认设置），将使调试器将程序的所有输出打印到 VS Code 调试输出Windows。如果设置为假（集成终端和外部终端的默认设置），程序输出不会显示在调试器输出Windows中。

此选项在使用时通常禁用"控制台": "集成终端"或"控制台": "外部终端"因为不需要在调试控制台中重复输出。

只是我的代码

当省略或设置为真（默认），将调试限制在用户编写的代码。设置为假还能够调试标准库函数。

django

当设置为真激活特定于Django网络框架的调试功能。

超级用户权限

当设置为真并用于"控制台": "外部终端"允许调试需要提升权限的应用程序。使用外部控制台是捕获密码所必需的。

金字塔

当设置为真，确保启动一个 Pyramid 应用程序，具有 必要的 pserve 命令.

环境

为调试器进程设置可选的环境变量，这些环境变量超越系统环境变量，调试器总是继承这些环境变量。这些变量的值必须以字符串形式输入。

环境文件

可选的路径，指向包含环境变量定义的文件。见配置Python环境 - 环境变量定义文件.

绿风

如果设置为真，启用对gevent 猴子补丁代码的调试。

Jinja

当设置为真激活特定于Jinja模板框架的调试功能。

断点和日志点

Python 调试器扩展支持 断点 和 日志点 用于调试代码。有关基本调试和使用断点的简短示例，请参阅 教程 - 配置和运行调试器。

条件断点

断点也可以根据表达式、击中次数或两者的组合来触发。Python Debugger 扩展除了支持前面带有 ==、>、>=、<、<= 和 % 运算符的整数击中次数之外，还支持整数。例如，你可以通过设置击中次数为 5 来设置一个在出现五次后触发的断点。>5 有关更多信息，请参阅 条件断点 在 VS Code 调试主要文章中。

在代码中调用断点

在你的Python代码中，你可以调用debugpy.breakpoint()在任何你想暂停调试器的调试会话的点。

断点验证

Python 调试器扩展会自动检测在非可执行行上设置的断点，例如通过语句或跨行语句的中间。在这种情况下，运行调试器会将断点移动到最近的有效行，以确保代码执行在该点停止。

调试特定类型的应用程序

配置下拉菜单为各种通用应用类型提供了多种不同的选项：

对于远程调试和Google App Engine也需要采取具体步骤。有关测试调试的详细信息，请参见测试.

要调试一个需要管理员权限的应用程序，请使用"控制台": "外部终端"和'sudo": "True"输入：.

Flask 调试

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

如你所见，此配置指定了"env": { "FLASK_APP": "app.py" }和"args": ["run", "--no-debugger"]。"模块": "flask"属性被使用而不是程序。(您可能会看到"FLASK_APP": "${workspaceFolder}/app.py"在环境属性，在这种情况下修改配置以仅引用文件名。否则，您可能会看到“无法导入模块 C”错误，其中 C 是一个驱动器字母。

该"jinja": 真设置还启用了Flask默认的Jinja模板引擎的调试。

如果您想在开发模式下运行Flask的开发服务器，请使用以下配置：

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

故障排除

调试器无法工作有很多原因。有时调试控制台会揭示具体原因，但主要原因是如下所述：

• 确保安装并启用Python Debugger 扩展在 VS Code 中，通过打开扩展视图 (⇧⌘X (Windows, Linux Ctrl+Shift+X)) 并搜索@已安装的Python调试器输入：.

• Python 可执行文件的路径不正确：通过运行 Python: 选择解释器 命令并查看当前值来检查您选择的解释器的路径：

  

• 你有"类型"设置为已弃用的值"python"在你的launch.json文件：替换"python"与"debugpy"而是与Python调试器扩展一起使用。

• 观察Windows中有无效表达式：从观察Windows清除所有表达式并重新启动调试器。

• 如果你正在使用一个使用原生线程 API（例如 Win32 的多线程应用程序创建线程由于使用的是函数而不是Python的线程API，目前需要在您想要调试的文件顶部包含以下源代码：

  导入 debugpy
   debugpy.debug_this_thread()
  

• 如果您正在使用 Linux 系统，在尝试将调试器应用于任何正在运行的进程时，可能会收到“超时”错误消息。为了防止这种情况，您可以临时运行以下命令：

  回显 0 | 超级用户 转入 /proc/sys/kernel/yama/ptrace_scope
  

下一步

• Python 环境 - 控制用于编辑和调试的 Python 解释器。
• 测试 - 配置测试环境并发现、运行和调试测试。
• 设置参考 - 探索 VS Code 中所有与 Python 相关的设置。
• 一般调试 - 了解 VS Code 的调试功能。