调试Python/C++混合项目时C++断点无法命中的问题排查

1. 确保编译时保留调试符号并关闭优化 #

pybind11扩展编译时如果开启了优化或未生成调试符号，断点会直接被跳过。修改你的setup.py，添加调试编译参数：

from setuptools import setup, Extension
import pybind11

ext_modules = [
    Extension(
        "your_module",
        ["add.cpp"],
        include_dirs=[pybind11.get_include()],
        extra_compile_args=['-g', '-O0'],  # 生成调试符号+关闭优化
        language='c++'
    ),
]

setup(
    name="your_module",
    ext_modules=ext_modules,
    cmdclass={"build_ext": pybind11.setup_helpers.build_ext},
)

重新编译扩展：

python setup.py build_ext --inplace

用file your_module.so验证输出中包含with debug_info，确认调试符号已生成。

2. 配置Docker容器的调试权限与路径映射 #

• 启动容器时必须添加SYS_PTRACE权限，否则无法在容器内调试进程：

  docker run --cap-add=SYS_PTRACE -v $(pwd):/app -it your_docker_image bash
  

• 确保本地源码目录与容器内挂载路径完全一致，比如本地~/project/add.cpp挂载到容器/app/add.cpp，调试器的断点路径要对应容器内的/app/add.cpp，避免路径不匹配导致断点失效。

3. 修正调试器配置（以VS Code为例） #

修改launch.json，确保Python调试允许进入非自有代码，同时C++调试正确映射路径：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Debug pybind11 App",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "justMyCode": false  // 必须关闭，才能调试C++扩展
        },
        {
            "name": "C++: Attach to Python Process",
            "type": "cppdbg",
            "request": "attach",
            "program": "/usr/bin/python3",  // 容器内Python解释器路径
            "processId": "${command:pickProcess}",
            "MIMode": "gdb",
            "sourceFileMap": {
                "/app": "${workspaceFolder}"  // 容器路径映射到本地工作区
            }
        }
    ]
}

调试流程：先启动Python配置运行程序，再用C++配置attach到对应的Python进程。

4. 避免代码被编译器内联 #

简单函数（比如add）可能被编译器内联，导致断点无法命中。在add.cpp函数开头添加阻止内联的代码：

#include <pybind11/pybind11.h>

int add(int a, int b) {
    asm volatile("");  // 阻止编译器内联当前函数
    return a + b;
}

PYBIND11_MODULE(your_module, m) {
    m.def("add", &add, "Add two integers");
}

重新编译后再调试。

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