如何在远程机器上用PyCharm调试Python调用的C++代码

前置准备要求 #

• 编译C++扩展时必须禁用所有优化、开启完整调试符号：编译参数必须带-g -O0，不能用Release模式编译，避免符号被剥离、函数被内联导致断点失效。如果是用setuptools编译Python扩展，需要在配置里传入对应编译参数，比如在setup.py中添加extra_compile_args = ['-g', '-O0']。
• 远程机器安装gdb的同时，需要安装对应Python版本的调试支持包，确保gdb可以识别Python内部的栈结构，比如Debian/Ubuntu系需要安装和当前解释器版本匹配的python3.x-dbg包。
• 提前记录Python入口脚本的绝对路径、待调试C++扩展动态库的实际加载路径，避免调试时路径解析错误。

针对Python-C++混合场景的gdb专属操作流程 #

普通gdb调试原生程序的流程无法直接适配Python嵌入解释器的场景，因为Python解释器会将原生栈做多层封装，直接attach或者打断点会只能看到解释器内部的通用函数栈，看不到业务层的C++逻辑和Python调用上下文，必须按以下步骤操作：

1. 带参数启动gdb，关联Python解释器
   不要直接在运行中的Python进程上attach，尤其是脚本启动阶段就触发C崩溃的场景，直接在远程终端执行：
   gdb --args python3 你的Python入口脚本绝对路径
   这种启动方式可以捕获从Python解释器初始化、C扩展加载到业务逻辑执行全流程的问题，不会遗漏早期加载阶段的崩溃。
2. 加载Python配套的gdb调试脚本
   进入gdb交互界面后，首先执行source命令加载Python解释器自带的gdb辅助脚本，这一步是混合调试的核心：
   脚本路径一般是Python安装路径下的python3.x-gdb.py，可以通过python3 -c "import sys; print(sys.path)"定位实际路径，执行示例：
   source /usr/lib/python3.8/libpython3.8.so-gdb.py

   跳过这一步会出现gdb只识别解释器通用栈、看不到Python业务调用上下文的问题，是很多人用gdb调试Python-C++混合代码失败的核心原因
   加载完成后gdb会自动识别Python的内部对象结构，新增专属的Python调试命令，不会再将Python解释器的栈当成无意义的原生栈。

3. 设置C++侧断点
   直接使用gdb原生的断点命令给C业务函数下断点即可，不管是暴露给Python调用的扩展函数，还是C内部的工具函数都适用：
   • 普通全局函数断点示例：break CalculateImageFeature
   • 带命名空间的C++类成员函数断点示例：break cv::dnn::Net::forward
   • 因为C扩展是Python运行时动态加载的，需要提前开启延迟断点支持，避免gdb因为找不到加载中的动态库符号报错，执行命令：
     set breakpoint pending on
     开启后不管C扩展什么时候加载完成，gdb都会自动匹配符号挂上断点。
4. 启动调试流程
   在gdb交互界面输入run，解释器就会带着调试权限启动Python脚本，当代码执行到预设的C++断点位置时，程序会自动中断。
5. 中断后的上下文查看操作
   程序中断后，可以结合gdb原生命令和Python专属调试命令查看全链路上下文：
   • 用bt查看完整栈回溯，能看到从Python脚本调用层一路到C++当前断点的完整调用链
   • 用frame 栈帧编号命令切换栈帧，既可以切到C++内部函数查看变量值、内存地址，也可以切到Python对应的解释器栈帧
   • 使用gdb加载Python辅助脚本后提供的专属命令查看Python侧上下文：
     • py-bt：打印Python侧的业务调用栈，和Python原生backtrace效果一致
     • py-list：显示当前Python执行位置的代码行
     • py-locals：列出当前Python栈帧下的所有本地变量值，无需手动解析Python对象结构
6. 常见调试异常处理
   • 断点触发失效：首先检查C++扩展是否真的用-g -O0编译，有没有被strip工具剥离符号，确认开启了延迟断点选项，避免断点打在被编译器内联消除的函数上。
   • 多线程场景下找不到C代码：用info threads列出所有运行中的线程，用thread 线程ID切换到实际执行业务C代码的线程即可。
   • gdb无法识别Python对象：确认已经正确source了和当前Python解释器版本完全匹配的gdb辅助脚本，不要混用不同版本的脚本。

可选辅助调试方式 #

如果需要结合PyCharm的界面化调试能力，可以在远程机器上启动gdbserver :1234 你的Python启动命令，在本地PyCharm配置远程C调试连接，IP填远程机器地址、端口填1234，就能把本地调试器连接到远程的Python-C进程上，操作逻辑和前面命令行的gdb流程完全一致，只是把命令行操作换成了PyCharm的图形界面。

内容的提问来源于stack exchange，提问作者user3541631