Python调试在VS Code中

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

有关通用调试功能，例如检查变量、设置断点和其他与语言无关的活动，请参阅VS Code调试。

本文主要介绍Python特定的调试配置，包括特定应用类型和远程调试所需的步骤。

Python调试器扩展

与Python扩展一起自动安装Python调试器扩展。它为几种类型的Python应用程序（包括脚本、Web应用程序、远程进程等）提供使用debugpy的调试功能。

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

您可以参考扩展的README页面，了解有关支持的Python版本的信息。

初始化配置

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

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

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

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

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

1. 选择创建launch.json文件链接（如上图所示）或使用运行 > 打开配置菜单命令。

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

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

   

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

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

   

配置属性的详细信息将在本文的标准配置和选项下介绍。其他配置也在本文的调试特定应用类型下描述。

附加配置

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

选择使用进程ID附加会产生以下结果：

有关详细信息，请参阅调试特定应用类型。

在调试期间，状态栏显示当前配置和当前的调试解释器。选择配置会弹出一个列表，您可以从中选择不同的配置

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

基本调试

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

如果您希望使用Flask、Django或FastAPI调试Web应用程序，Python调试器扩展会根据您的项目结构在运行和调试视图下的显示所有自动调试配置选项中提供动态创建的调试配置。

但是，如果您希望调试其他类型的应用程序，可以通过单击运行视图中的运行和调试按钮来启动调试器。

如果没有设置配置，您将获得一个调试选项列表。在这里，您可以选择适当的选项来快速调试您的代码。

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

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

命令行调试

如果您的Python环境中安装了debugpy，也可以从命令行运行调试器。

安装debugpy

您可以使用python -m pip install --upgrade debugpy将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）和脚本使用以下语法启动调试器。此示例假定脚本是长期运行的，省略了--wait-for-client标志，这意味着脚本不会等待客户端附加。

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。

如果您想调试远程代码或在Docker容器中运行的代码，您需要在远程机器或容器上修改先前的CLI命令以指定主机。

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

关联的配置文件如下所示。

{
  "name": "Attach",
  "type": "debugpy",
  "request": "attach",
  "connect": {
    "host": "remote-machine-name", // replace this with remote machine name
    "port": 5678
  }
}

注意：请注意，当您指定除127.0.0.1或localhost以外的主机值时，您将打开一个端口以允许来自任何机器的访问，这会带来安全风险。您应该确保采取适当的安全预防措施，例如使用SSH隧道，进行远程调试。

命令行选项

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

通过网络连接进行调试

本地脚本调试

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

1. 运行 VS Code，打开包含脚本的文件夹或工作区，如果尚未存在，则为该工作区创建一个 launch.json。

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

   import debugpy
   
   # 5678 is the default attach port in the VS Code debug configurations. Unless a host and port are specified, host defaults to 127.0.0.1
   debugpy.listen(5678)
   print("Waiting for debugger attach")
   debugpy.wait_for_client()
   debugpy.breakpoint()
   print('break on this line')
   

3. 使用 Terminal: Create New Terminal 打开一个终端，这将激活脚本所选的环境。

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

5. 在终端中，使用 Python 运行脚本，例如，python3 myscript.py。您应该会看到代码中包含的“Waiting for debugger attach”消息，并且脚本将在 debugpy.wait_for_client() 调用处停止。

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

7. 调试器应在 debugpy.breakpoint() 调用处停止，从那时您可以正常使用调试器。您还可以选择使用 UI 而不是使用 debugpy.breakpoint() 在脚本代码中设置其他断点。

使用 SSH 进行远程脚本调试

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

注意：在 Windows 计算机上，您可能需要安装 Windows 10 OpenSSH 才能使用 ssh 命令。

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

在远程计算机上

1. 通过打开 sshd_config 配置文件（在 Linux 上位于 /etc/ssh/，在 Windows 上位于 %programfiles(x86)%/openssh/etc）并添加或修改以下设置来启用端口转发

   AllowTcpForwarding yes
   

   注意：AllowTcpForwarding 的默认值为 yes，因此您可能不需要进行更改。

2. 如果您必须添加或修改 AllowTcpForwarding，请重新启动 SSH 服务器。在 Linux/macOS 上，运行 sudo service ssh restart；在 Windows 上，运行 services.msc，在服务列表中选择 OpenSSH 或 sshd，然后选择 Restart。

在本地计算机上

1. 通过运行 ssh -2 -L sourceport:localhost:destinationport -i identityfile user@remoteaddress 创建 SSH 隧道，为 destinationport 选择一个端口，并在 user@remoteaddress 中使用适当的用户名和远程计算机的 IP 地址。例如，要使用 IP 地址 1.2.3.4 上的端口 5678，命令将是 ssh -2 -L 5678:localhost:5678 -i identityfile user@1.2.3.4。您可以使用 -i 标志指定身份文件的路径。

2. 验证您是否可以在 SSH 会话中看到提示。

3. 在您的 VS Code 工作区中，在 launch.json 文件中创建一个用于远程调试的配置，将端口设置为与 ssh 命令中使用的端口匹配，并将主机设置为 localhost。您在此处使用 localhost 是因为您已设置 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. 在源代码中，添加以下行，将 address 替换为远程计算机的 IP 地址和端口号（此处仅为说明目的显示 IP 地址 1.2.3.4）。

      import debugpy
      
      # Allow other computers to attach to debugpy at this IP address and port.
      debugpy.listen(('1.2.3.4', 5678))
      
      # Pause the program until a remote debugger is attached
      debugpy.wait_for_client()
      

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

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

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

      这使用 python3 启动 myproject 包，使用远程计算机的私有 IP 地址 1.2.3.4 并侦听端口 5678（您也可以通过指定文件路径而不是使用 -m 来启动远程 Python 进程，例如 ./hello.py）。

4. 本地计算机：仅当您按照上述步骤修改了远程计算机上的源代码时，然后在源代码中添加相同代码的注释副本，该代码已添加到远程计算机上。添加这些行可确保两台计算机上的源代码逐行匹配。

   #import debugpy
   
   # Allow other computers to attach to debugpy at this IP address and port.
   #debugpy.listen(('1.2.3.4', 5678))
   
   # Pause the program until a remote debugger is attached
   #debugpy.wait_for_client()
   

5. 本地计算机：切换到 VS Code 中的 Run and Debug 视图 (⇧⌘D (Windows, Linux Ctrl+Shift+D))，选择 Python Debugger: Attach 配置

6. 本地计算机：在您想要开始调试的代码中设置一个断点。

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

   来自 print 语句的 stdout 的文本输出将显示在两台计算机上。但是，来自 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}",
      "console": "externalTerminal"
    }
  ]
}

以下部分描述了具体设置。您还可以添加其他设置，例如 args，这些设置未包含在标准配置中。

提示：在项目中，创建一个始终使用相同的入口点启动程序的配置通常很有帮助。例如，如果您希望始终使用参数 --port 1593 启动 startup.py，请创建一个如下配置条目

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

name

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

type

标识要使用的调试器类型；对于调试 Python 代码，请将其设置为 debugpy。

request

指定开始调试的模式

• launch：在 program 中指定的文件的调试器上启动
• attach：附加到已经运行的进程的调试器。有关示例，请参阅 远程调试。

program

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

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

您还可以依赖于从工作区根目录的相对路径。例如，如果根目录是 /Users/Me/Projects/MyProject，则可以使用以下示例

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

module

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

python

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

如果未指定，此设置默认为您的工作区选择的解释器，这等效于使用值 ${command:python.interpreterPath}。要使用不同的解释器，请在调试配置的 python 属性中指定其路径。

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

如果您需要将参数传递给 Python 解释器，可以使用 pythonArgs 属性。

pythonArgs

指定使用语法 "pythonArgs": ["<arg 1>", "<arg 2>",...] 将参数传递给 Python 解释器。

args

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

"args": ["--quiet", "--norepeat", "--port", "1593"],

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

注意："${command:pickArgs}" 和 ["${command:pickArgs}"] 的解析方式不同，尤其要注意 [] 的使用。作为数组，所有参数都作为单个字符串传递，如果没有括号，则每个参数都作为其自己的字符串传递。

stopOnEntry

设置为 true 时，在正在调试的程序的第一个行中断调试器。如果省略（默认）或设置为 false，调试器将运行程序到第一个断点。

console

指定程序输出的显示方式，前提是不修改 redirectOutput 的默认值。

purpose

有多种方法可以使用 purpose 选项配置 Run 按钮。将选项设置为 debug-test，定义应在 VS Code 中调试测试时使用该配置。但是，将选项设置为 debug-in-terminal，定义应仅在使用编辑器右上角的 Run Python File 按钮时使用该配置（无论该按钮提供的 Run Python File 或 Debug Python File 选项使用哪个）。注意：不能使用 purpose 选项通过 F5 或 Run > Start Debugging 启动调试器。

autoReload

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

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

注意：当调试器执行重新加载时，可能会再次执行导入时运行的代码。为了避免这种情况，请尝试仅在函数中使用导入、常量和定义。或者，您也可以使用 if __name__=="__main__" 检查。

subProcess

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

cwd

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

例如，假设 ${workspaceFolder} 包含一个名为 py_code 的文件夹，其中包含 app.py，以及一个名为 data 的文件夹，其中包含 salaries.csv。如果在 py_code/app.py 上启动调试器，则数据文件的相对路径取决于 cwd 的值

redirectOutput

设置为 true（internalConsole 的默认值）时，调试器会将程序的所有输出打印到 VS Code 调试输出窗口中。如果设置为 false（integratedTerminal 和 externalTerminal 的默认值），则程序输出不会显示在调试器输出窗口中。

通常在将 "console": "integratedTerminal" 或 "console": "externalTerminal" 时禁用此选项，因为无需在调试控制台中重复输出。

justMyCode

如果省略或设置为 true（默认值），则将调试限制为用户编写的代码。设置为 false 可同时启用标准库函数的调试。

django

设置为 true 时，将激活特定于 Django Web 框架的调试功能。

sudo

设置为 true 且与 "console": "externalTerminal" 一起使用时，允许调试需要提升权限的应用程序。使用外部控制台是捕获密码的必要条件。

pyramid

设置为 true 时，可确保使用 必要的 pserve 命令 启动 Pyramid 应用程序。

env

设置调试器进程的附加环境变量，这些环境变量超出系统环境变量，调试器始终会继承系统环境变量。这些变量的值必须作为字符串输入。

envFile

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

gevent

如果设置为 true，则启用对 gevent monkey-patched 代码 的调试。

jinja

设置为 true 时，将激活特定于 Jinja 模板框架的调试功能。

断点和日志点

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

条件断点

断点也可以设置为基于表达式、命中计数或两者的组合来触发。Python 调试器扩展支持整数命中计数，以及以 ==、>、>=、<、<= 和 % 运算符为前缀的整数。例如，您可以设置一个断点，通过设置 >5 的命中计数，在发生五次后触发。有关更多信息，请参阅主 VS Code 调试文章中的 条件断点。

在代码中调用断点

在 Python 代码中，可以在调试会话期间希望暂停调试器的任何位置调用 debugpy.breakpoint()。

断点验证

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

调试特定应用类型

配置下拉菜单为常规应用程序类型提供了各种不同的选项

还需要针对远程调试和 Google App Engine 进行特定步骤。有关测试调试的详细信息，请参阅 测试。

要调试需要管理员权限的应用程序，请使用 "console": "externalTerminal" 和 "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"]。使用 "module": "flask" 属性代替 program。（您可能会看到 "FLASK_APP": "${workspaceFolder}/app.py" 在 env 属性中，在这种情况下，请修改配置以仅引用文件名。否则，您可能会看到“无法导入模块 C”错误，其中 C 是驱动器号。）

"jinja": true 设置还启用了 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 调试器扩展 并且已在 VS Code 中启用，方法是打开 扩展 视图 (⇧⌘X (Windows, Linux Ctrl+Shift+X)) 并搜索 @installed python debugger。

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

  

• 您的 launch.json 文件中 "type" 设置为已弃用的值 "python"：将 "python" 替换为 "debugpy" 以使用 Python 调试器扩展。

• 监视窗口中存在无效表达式：清除监视窗口中的所有表达式并重新启动调试器。

• 如果正在使用使用本机线程 API（例如 Win32 CreateThread 函数而不是 Python 线程 API）的多线程应用程序，则目前需要在要调试的任何文件的顶部包含以下源代码

  import debugpy
  debugpy.debug_this_thread()
  

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

  echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
  

后续步骤

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