VS Code 中的 Python 调试

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

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

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

Python 调试器扩展

面向 VS Code 的Python Debugger 扩展会随Python 扩展自动安装。它提供使用debugpy的调试功能，适用于多种类型的 Python 应用程序，包括脚本、Web 应用、远程进程等。

要验证它是否已安装，请打开扩展视图（⇧⌘X (Windows, Linux Ctrl+Shift+X)），然后搜索 @installed python debugger。您应该会在结果中看到 Python Debugger 扩展。

您可以参考此扩展的README 页面，以获取有关受支持 Python 版本的信息。

初始化配置

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

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

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

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

要生成包含 Python 配置的 launch.json 文件，请按照以下步骤操作

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

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

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

   

   注意：当没有配置时，通过调试面板、F5 或 运行 > 启动调试 启动调试会话也会打开调试配置菜单，但不会创建 launch.json 文件。

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

   

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

附加配置

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

选择附加到进程 ID 会得到以下结果：

有关所有这些配置的详细信息，请参阅调试特定应用程序类型。

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

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

基本调试

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

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

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

未设置配置时，您将看到一个调试选项列表。您可以在此处选择适当的选项来快速调试代码。

两种常用选项是使用Python File配置运行当前打开的 Python 文件，或者使用附加到进程 ID配置将调试器附加到已在运行的进程。

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

命令行调试

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

安装 debugpy

您可以使用 python -m pip install --upgrade debugpy 将debugpy安装到您的 Python 环境中。

提示：虽然不需要使用虚拟环境，但这是一种推荐的最佳实践。您可以通过打开命令面板（⇧⌘P (Windows, Linux Ctrl+Shift+P)）并运行Python: Create Virtual Environment命令（）在 VS Code 中创建虚拟环境。

命令行语法

调试器命令行语法如下

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 Debugger 扩展附加。

{
  "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 脚本。例如，您可能正在调试一个运行不同 Python 脚本来执行特定处理任务的 Web 服务器。在这种情况下，您需要在脚本启动后将 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. 使用终端: 创建新终端打开终端，这将激活脚本选定的环境。

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

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

6. 切换到运行和调试视图（⇧⌘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，然后选择重新启动。

在本地计算机上

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 中的运行和调试视图（⇧⌘D (Windows, Linux Ctrl+Shift+D)），选择Python Debugger: Attach配置

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

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

   输出到 stdout 的文本（例如来自 print 语句）会出现在两台计算机上。但是，其他输出（例如来自 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"]
 },

名称

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

类型

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

请求

指定启动调试的模式

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

程序

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

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

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

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

模块

提供指定要调试的模块名称的能力，类似于在命令行运行时使用 -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，调试器会运行程序直到第一个断点。

控制台

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

用途

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

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} 包含一个包含 app.py 的 py_code 文件夹，以及一个包含 salaries.csv 的 data 文件夹。如果在 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 时，确保 Pyramid 应用使用 必需的 pserve 命令 启动。

env

为调试器进程设置可选的环境变量，除了调试器总是继承的系统环境变量之外。这些变量的值必须作为字符串输入。

envFile

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

gevent

如果设置为 true，启用对gevent monkey 补丁代码的调试。

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。（您可能会在 env 属性中看到 "FLASK_APP": "${workspaceFolder}/app.py"，在这种情况下，请修改配置以仅引用文件名。否则，您可能会看到“无法导入模块 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
},

故障排除

调试器可能无法工作的原因有很多。有时调试控制台会显示具体原因，但主要原因如下：

• 通过打开扩展视图 (⇧⌘X（Windows、Linux Ctrl+Shift+X）) 并搜索 @installed python debugger，确保 VS Code 中已安装并启用 Python 调试器扩展。

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

  

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

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

• 如果您正在处理使用原生线程 API（例如 Win32 CreateThread 函数而非 Python 线程 API）的多线程应用，则当前需要在您要调试的任何文件的顶部包含以下源代码

  import debugpy
  debugpy.debug_this_thread()
  

• 如果您正在使用 Linux 系统，当尝试将调试器附加到任何正在运行的进程时，您可能会收到“timed out”错误消息。为了防止此问题，您可以暂时运行以下命令

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

后续步骤

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