VS Code 中的 Python 调试

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

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

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

Python 调试器扩展

Python 调试器扩展会随 VS Code 的 Python 扩展自动安装。它通过 debugpy 为脚本、Web 应用、远程进程等多种 Python 应用提供调试功能。

要验证其是否已安装，请打开扩展视图（⇧⌘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 选项）

选择 Attach using Process ID（通过进程 ID 附加）会产生以下结果：

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

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

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

基础调试

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

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

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

当尚未设置任何配置时，你将获得一个调试选项列表。在这里，你可以选择合适的选项来快速调试你的代码。

两个常用选项是：使用 Python 文件配置来运行当前打开的 Python 文件，或者使用 Attach using Process ID（通过进程 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 脚本。例如，你可能正在调试一个为特定处理作业运行不同 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 调试器：附加 配置

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

7. 本地计算机：使用修改后的 Python 调试器：附加 配置和“启动调试”按钮启动 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"]
 },

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

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 猴子补丁代码的调试。

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"，在这种情况下，请修改配置以仅引用文件名。否则，你可能会看到“Cannot import module 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：选择解释器命令并查看当前值，检查你所选解释器的路径

  

• 你在 launch.json 文件中将 "type" 设置为已弃用的值 "python"：将 "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 的调试功能。