CLion 2025.3 Help

远程调试配置

远程调试 配置允许您在 gdbserver 或 lldb-server 下进行远程调试。 如果您已经拥有带有调试信息的可执行文件，并且不需要 CLion 为您构建项目，请使用此配置。 此配置独立于特定的构建系统或项目格式。

Remote Debug 配置允许您远程调试 使用任意构建系统构建的应用程序。 唯一的要求是本地机器上存在调试符号。

目标平台

如果目标环境支持 gdbserver，则没有任何限制。

您的程序可以在任何操作系统上远程运行，包括基于 Linux 的嵌入式系统（如 Raspbian OS ，参见 Raspberry Pi OS 指南 ）、云平台或 Docker 容器中。 您可以连接到符合远程 gdbserver 协议的 任意 GDB stub ，例如，使用 Qemu 调试操作系统内核，或使用 OpenOCD 调试已刷写的固件。

CLion 捆绑的 GDB 默认作为客户端调试器使用，并构建时带有 多架构 支持，使其适用于各种 Linux、Windows、macOS 及嵌入式场景下的远程跨平台调试。 在下方找到支持目标的完整列表。

捆绑 GDB 支持的远程目标

i686-pc-mingw32 i686-w64-mingw32 x86_64-w64-mingw32 i686-linux-gnu x86_64-linux-gnu aarch64-linux-gnu alpha-linux-gnu arm-linux-gnu arm-linux-gnueabi arm-linux-gnueabihf hppa-linux-gnu ia64-linux-gnu m68k-linux-gnu m68k-rtems mips-linux-gnu mipsel-linux-gnu mips64-linux-gnu mips64el-linux-gnu powerpc-linux-gnu powerpc-linux-gnuspe

    您可以以 macOS、Linux、Android、Apple TV/Apple Watch 以及其他支持 lldb-server 的平台为目标。 请参阅 LLDB 文档中的 本地系统。

    工作流程的一般步骤

    以下是远程 GDB/LLDB 调试步骤的简要说明。 每个步骤的更多详细信息将在后续章节中提供。

    1. 准备一个 带有调试信息的二进制文件。 如有需要，请使用跨平台工具链。

      在远程 LLDB 的情况下，调试器不会自动下载任何调试符号或系统库，因此它们应存在于本地机器上。 对于从 macOS 到 Linux 或从 Linux 到 macOS 的跨平台调试，请通过 musl （或其他替代方案）进行交叉编译，这将附带所需的库。

    2. 确保放置 远程机器上的二进制文件 和 本地机器上的符号文件。

      通常，调试可执行文件本身可以很好地用作符号文件，或者也可以是一个单独的文件。

    3. 在 CLion 中， 创建一个 远程调试 配置。 您指定的设置对于调试器能够在远程会话期间停止在断点处至关重要，因此我们建议您仔细检查配置设置。

    4. 启动程序在 远程机器上的 gdbserver/lldb-server 下运行。

    5. 回到 CLion，开始 调试您在步骤 3 中创建的配置。

    创建远程调试配置

    1. 转到 运行 | 编辑配置 ，点击 ，然后从模板列表中选择 远程调试。

    2. 远程运行/调试配置

      选择客户端调试器（捆绑 GDB / 捆绑 LLDB、工具链 GDB 调试器之一或自定义 GDB 二进制文件），并提供相应设置：

      • 'target remote' 参数—— 远程系统地址的格式如下：

        <host>:<port>

        例如：

        127.0.0.1:1234

        您也可以使用 其他格式。

      • 符号文件。 这是本地机器上包含调试符号的文件路径，可以是目标上运行的可执行文件的未剥离副本，或仅包含调试信息的 ELF 文件。

        新版本的 GDB 客户端可以自动从 gdbserver 传输符号，因此，如果目标上运行的可执行文件是未剥离的二进制文件，则留空此字段也可能正常工作。

      • 系统根目录 由 GDB 客户端使用，以访问本地系统上带有调试符号的目标库副本，从而可以设置断点并在库代码中定位源代码行。

      • 'process connect' url。 使用以下表示法：

        connect://<host>:<port>

        例如：

        connect://127.0.0.1:1234

      • 符号文件。 这是本地机器上包含调试符号的文件路径，可以是目标上运行的可执行文件的未剥离副本，或仅包含调试信息的 ELF 文件。

        CLion 在 g[dbserver] 模式下使用 lldb-server，这需要您手动传输所有文件。

      • Sysroot 由 LLDB 客户端使用，以访问本地系统上带有调试符号的目标库副本，从而可以设置断点并在库代码中定位源代码行。

      • 路径映射。 使用此窗格提供目标机器上的路径（位于 远程 列），以映射到主机上的本地路径（位于 本地 列）。

    在 gdbserver/lldb-server 下远程启动您的程序

    要在目标上启动应用程序，您可以使用远程终端，或调用 CLion 内置的 SSH 终端 并 执行端口转发。

    使用以下命令运行 gdbserver：

    gdbserver <TCP hostname>:<port> <program name & args>
    远程 ssh 终端

    或者，您可以通过串口进行连接：

    gdbserver <device name> <program name & args>

    如果您倾向于建立串行连接，请改为指定设备名称。

    对于 LLDB，使用类似 lldb-server g *:1234 ./binary 的命令启动 lldb-server。

    在 macOS 上，使用 debugserver 作为 lldb-server：

    debugserver <host>:<port> <program name & args>

    例如：

    debugserver 192.168.1.226:1234 ./binary

    gdbserver/lldb-server 启动后会在入口点挂起程序，并等待客户端调试器连接。

      启动远程调试会话

      在 CLion 中，当您在代码中设置好断点后，请选择 远程调试 配置，并启动调试 会话。

      CLion 的调试器将连接到正在运行的远程进程。 终端将显示 从主机进行远程调试.. 消息，您还可以在调试器控制台中检查 调试器已连接到.. 消息。

      现在，您可以像本地运行一样检查代码（逐步执行、 检查变量 等）。

      通过 gds/gdbserver 调试

        调试共享库

        要调试共享库，请在本地机器上的 ~/.gdbinit 或 .lldbinit 中添加以下命令。 有关访问和编辑脚本的更多信息，请参阅 使用 .gdbinit/.lldbinit 配置文件。

        • 为 GDB 设置 solib-search-paths

          但是，默认情况下，此命令在调试器启动时执行，在附加到远程目标之前（请参阅相应的 问题）。 作为此问题的解决方法，您可以使用 GDB hooks：

          define target hookpost-remote set solib-search-path /path/to/my.so:/path/to/sysroot:/path/to/vendorlibs break main # if you also need the debug sessions to pause at the beginning end

          通过这种方式，GDB 将在每次连接到远程目标时执行挂钩中指定的 set solib-search-path。

        • 适用于 LLDB 的 settings set target.exec-search-paths /path/to/libs

        最后修改日期： 2025年 12月 8日
        Remote GDB Server 配置WSL2