# 调试 Python 扩展

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/zh-cn/help/clion/llms.txt).

CLion 当前不支持混合 Python 和 C/C++ 代码的交叉调试（ [CPP-5797](https://youtrack.jetbrains.com/issue/CPP-5797)）。 但是，您可以使用以下描述的选项之一，在处理 Python [扩展模块](https://docs.python.org/3/extending/extending.html)时解决此问题。

为了调试扩展的 C/C++ 代码，您需要使用本机调试器 GDB 或 LLDB，并调试加载脚本并运行应用程序的解释器进程。 为此，您可以选择 [附加到正在运行的 Python 进程](#attach-py) 或 [调试正确配置的自定义构建应用程序](#debug-custom-py)。

Procedure: 选项 1：使用本机调试器附加到正在运行的 Python 进程

> **Tip:**
> 请参阅 [附加到进程](attach-to-process.html) 以获取一般信息。

1. 设置 [断点](using-breakpoints.html)，并确保在您附加到进程  之后 它们会被命中。

2. 启动 Python 脚本。 您可以通过系统终端、CLion 的 [内置终端](terminal-emulator.html) 或运行 [Python 配置](run-debug-configuration-python.html) 来完成此操作。

3. 从主菜单调用   运行 | 附加到进程   或按 `Ctrl+Alt+F5` (Windows), `⌥ ⇧ F5` (macOS), `⌥ ⇧ F5` (IntelliJ IDEA Classic (macOS)), `⌥ ⇧ F5` (macOS System Shortcuts), `Ctrl+Alt+5` (XWin), `Ctrl+Alt+5` (GNOME), `Ctrl+Alt+5` (KDE), `Ctrl+Alt+F5` (Emacs), `Ctrl+Alt+F5` (Sublime Text), `⌥ ⇧ F5` (Sublime Text (macOS)), `⌥ ⇧ F5` (Xcode), `Ctrl+Alt+P` (Visual Studio), `⌘ ⌥ P` (Visual Studio (macOS)), `Ctrl+Alt+F5` (ReSharper), `⌃ ⌥ F5` (ReSharper (macOS)), `Ctrl+Alt+F5` (QtCreator), `⌥ ⇧ F5` (QtCreator (macOS)), `Ctrl+Alt+F5` (NetBeans), `Ctrl+Alt+F5` (Eclipse), `⌥ ⇧ F5` (Eclipse (macOS))。

4. 在条目列表中，搜索与进程的 PID 对应的条目，该条目位于  Native  节点下：

![附加到正在运行的 Python 进程](https://resources.jetbrains.com/help/img/idea/2026.3/cl_python_ext_attach.png)

> **Note:**
> 将有两个与进程对应的条目：一个允许使用 Python 调试器附加（用于逐步执行 Python 脚本），另一个允许使用本机调试器附加。 请确保选择后者。

5. 调试器成功附加后，您将能够像往常一样调试本机代码。 有关更多信息，请参阅 [调试](debugging-code.html)部分。

6. 完成后，调用  `运行 | 停止`  或点击工具栏或 [调试工具窗口](debug-tool-window.html) 中的 ![挂起](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.suspend.svg) 以从进程中分离。

Procedure: 选项 2：调试自定义构建应用程序配置

作为附加本机调试器的替代方法，您可以在其下启动 Python 解释器。 如果您知道调用脚本的确切解释器命令，则可以使用此选项。

您需要创建一个 [自定义目标](custom-build-targets.html)，用于重建本机扩展，以及一个 [自定义构建应用程序](custom-build-application.html)配置，该配置将调用自定义目标并使用适当的参数执行 Python 解释器。

1. 在主菜单中，转到   运行 | 编辑配置  ，点击 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg)，然后选择   自定义构建应用程序  。

2. 点击  配置自定义构建目标 ，位于   目标  字段下方。 这将打开  `设置 | 构建、执行、部署 | 自定义构建目标` 对话框。

3. 点击 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg) 以添加新目标并设置目标名称。

4. 选择工具链。 CLion 将使用所选工具链中的调试器。

5. 设置用于构建项目的工具。 点击 ![“浏览”按钮](https://resources.jetbrains.com/help/img/idea/2026.3/app.general.ellipsis.svg)，位于   构建   字段旁边，然后点击 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg) 以添加新工具。

> **Tip:**
> 您还可以在此处设置用于清理项目的工具。

指定工具的配置。 下面的截图说明了使用  `pip install -e` 的情况：

![将 Pip 安装为外部工具](https://resources.jetbrains.com/help/img/idea/2026.3/cl_python_ext_pip_tool.png)

6. 在   编辑工具  和   自定义构建目标  对话框中保存更改，并返回设置运行/调试配置。

![自定义构建应用程序](https://resources.jetbrains.com/help/img/idea/2026.3/cl_python_ext_custom_config.png)

指定以下设置：

* 可执行文件 - 提供 Python 解释器的路径。

* 程序参数 - 指定脚本名称以及必要的附加参数。

* 工作目录 - 设置项目根目录的路径。 您可以在此处使用宏（ ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.general.add_dark.svg)）和 [路径变量](absolute-path-variables.html)。

7. 保存配置后，您可以像往常一样为其 [启动调试会话](starting-the-debugger-session.html)：

![调试 Python 扩展](https://resources.jetbrains.com/help/img/idea/2026.3/cl_python_ext_debug.png)

## See also

### 操作指南

[Debugger options](configuring-debugger-options.html) [Stepping through](examining-suspended-program.html) [Debug tool window](debug-tool-window.html) [调试反汇编代码](disassembly-view.html) [附加到进程](attach-to-process.html)

