# 远程调试配置

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

> **TL;DR**
> 本地操作系统  ：适用于 GDB 的 macOS / Linux / Windows，适用于 LLDB 的 macOS / Linux
>
>
>
> 远程操作系统  ：支持 gdbserver 的任何平台适用于 GDB，macOS / Linux 或支持 lldb-server 的其他平台适用于 LLDB
>
>
>
> 必需工具  ：目标上的 [gdbserver](https://sourceware.org/gdb/onlinedocs/gdb/Server.html) 或 [lldb-server](https://lldb.llvm.org/man/lldb-server.html)
>
>
>
> 二进制文件和符号文件同步  ：手动
>
>
>
> 客户端调试器  ：捆绑 GDB 或捆绑 LLDB，工具链的 GDB，自定义 GDB

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

> **Tip:**
> 下文中使用的术语：  本地计算机 （  主机 ）是运行 CLion 和 GDB/LLDB 客户端的位置，而  远程计算机 （  目标 ）是使用 gdbserver/lldb-server 启动应用程序的位置。

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

## 目标平台

GDB/gdbserver:

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

您的程序可以在任何操作系统上远程运行，包括基于 Linux 的嵌入式系统（如 [Raspbian OS](https://www.raspberrypi.org/software/operating-systems/)，参见 [Raspberry Pi OS 指南](https://www.pcwdld.com/raspbian-raspberry-pi-os-guide)）、云平台或 [Docker](docker.html) 容器中。 您可以连接到符合远程 gdbserver 协议的   任意 GDB stub  ，例如，使用 [Qemu](https://en.wikibooks.org/wiki/QEMU/Debugging_with_QEMU) 调试操作系统内核，或使用 [OpenOCD](https://openocd.org) 调试已刷写的固件。

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

Procedure: 捆绑 GDB 支持的远程目标

```CONSOLE
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

```

LLDB/lldb-server:

您可以以 macOS、Linux、Android、Apple TV/Apple Watch 以及其他支持 lldb-server 的平台为目标。 请参阅 LLDB 文档中的 [本地系统](https://lldb.llvm.org/use/remote.html#local-system)。

## 工作流程的一般步骤

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

1.

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

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

2.

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

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

> **Note:**
> 由于远程调试配置不会同步您的文件，您需要在任何更改时手动跟踪二进制文件和符号文件并进行同步。

3.

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

4.  [启动](#launch-remote-debug)程序在   远程机器上的 gdbserver/lldb-server   下运行。

5.  回到 CLion，开始 [调试您在步骤 3 中创建的配置](#start-remote-debug)。

Procedure: 创建远程调试配置

1. 转到   运行 | 编辑配置  ，点击 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg)，然后从模板列表中选择   远程调试  。

2. ![远程运行/调试配置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_remoteConfig.png)

选择客户端调试器（捆绑 GDB／捆绑 LLDB、某个工具链的 GDB 调试器或自定义 GDB 可执行文件），并提供相应设置：

GDB:

* 'target remote' 参数 ——远程系统地址需使用以下格式： ``` <host>:<port> ``` 例如： ``` 127.0.0.1:1234 ``` 您也可以使用 [替代格式](https://sourceware.org/gdb/onlinedocs/gdb/Connecting.html#Connecting)。

* 符号文件 . 这是包含调试符号的文件在本地计算机上的路径，可以是目标上运行的可执行文件的未剥离副本，或者仅包含调试信息的 [ELF](https://en.wikipedia.org/wiki/Executable_and_Linkable_Format) 文件。 > **Tip:** > 如果您正在调试 共享对象库 ，请避免将 `.so` 文件指定为符号文件。 使用 `.so` 作为符号文件时，调试器会将源位置解析为两个位置：一个是内存中的实际地址，另一个是 `.so` 文件中的文件地址，而该地址不是有效的内存地址。 因此，逐步执行和其他调试操作无法正常工作。 新版 GDB 客户端可自动从 gdbserver 传输符号，因此如果目标上的可执行文件是未剥离的，保留此字段为空也可能正常工作。

* Sysroot 供 GDB 客户端访问包含调试符号的目标库副本在本地系统上的路径，以便断点设置和查找库代码中的源代码行。 > **Tip:** > 大部分新版 GDB 会自动下载这些文件，因此此字段为可选项。但请注意，自动下载可能显著减慢调试过程。 但是，请注意，自动下载可能会显著减慢调试过程。 > > > > 您可以选择将库手动复制到非默认的本地目录。 如选择手动复制，请在此字段中提供路径，GDB 将使用该路径。

LLDB:

* 'process connect' url . 请使用以下表示法： ``` connect://<host>:<port> ``` 例如： ``` connect://127.0.0.1:1234 ```

* 符号文件 . 这是包含调试符号的文件在本地计算机上的路径，可以是目标上运行的可执行文件的未剥离副本，或者仅包含调试信息的 [ELF](https://en.wikipedia.org/wiki/Executable_and_Linkable_Format) 文件。 > **Tip:** > 如果您正在调试 共享对象库 ，请避免将 `.so` 文件指定为符号文件。 使用 `.so` 作为符号文件时，调试器会将源位置解析为两个位置：一个是内存中的实际地址，另一个是 `.so` 文件中的文件地址，而该地址不是有效的内存地址。 因此，逐步执行和其他调试操作无法正常工作。 CLion 使用 [g\[dbserver\]](https://lldb.llvm.org/man/lldb-server.html) 模式下的 lldb-server，此模式下需要您手动传输所有文件。

* Sysroot 供 LLDB 客户端访问包含调试符号的目标库副本在本地系统上的路径，以便断点设置和查找库代码中的源代码行。 > **Note:** > 如果在与主机不同的远程平台上调试未通过交叉编译生成的二进制文件，必须指定 sysroot（例如，若从 macOS 主机调试，而远程 Linux 机运行的二进制文件链接的是 Linux 系统库）。

*

* 路径映射 . 请使用此面板提供目标机上的路径（在 远程 列中），以映射到主机上的本地路径（在 本地 列中）。

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

如需在目标上启动应用程序，您可以使用远程终端，也可以启动 CLion 内置的 [SSH 终端](running-ssh-terminal.html) 并 [执行端口转发](security-model.html#port_forwarding)。

GDB:

使用以下命令运行 gdbserver：

```
gdbserver <TCP hostname>:<port> <program name & args>
```

![远程 ssh 终端](https://resources.jetbrains.com/help/img/idea/2026.3/cl_remoteTerminal.png)

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

```
gdbserver <device name> <program name & args>
```

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

LLDB:

对于 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
```

> **Tip:**
> 默认情况下，debugserver 位于  `/Applications/Xcode.app/Contents/SharedFrameworks/LLDB.framework/Versions/A/Resources/debugserver` （作为 Xcode 分发的一部分）或  `/Library/Developer/CommandLineTools/Library/PrivateFrameworks/LLDB.framework/Versions/A/Resources/debugserver` （作为命令行工具的一部分）。

gdbserver 或 lldb-server 启动后将会在程序入口暂停，并等待客户端调试器连接。

Procedure: 启动远程调试会话

在 CLion 中设置好断点后，选择   远程调试   配置并启动调试 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.startDebugger.svg) 会话。

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

现在您可以像本地运行一样检查代码（ [单步执行](stepping-through-the-program.html)、 [检查变量](examining-suspended-program.html) 等）。

![通过 gds/gdbserver 调试](https://resources.jetbrains.com/help/img/idea/2026.3/cl_remoteDebugWindow.png)

> **Note:**
> 如果程序未在 IDE 中设置的断点处停止，请仔细检查 Remote Debug 配置中的   符号文件   和   路径映射   是否设置正确。

Procedure: 调试共享库

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

* 为 GDB 设置 [solib-search-paths](http://visualgdb.com/gdbreference/commands/set_solib-search-path)

但是，默认情况下，此命令在调试器启动时执行，在附加到远程目标之前（请参阅相应的 [问题](https://youtrack.jetbrains.com/issue/CPP-7322)）。 作为此问题的解决方法，您可以使用 [GDB hooks](https://sourceware.org/gdb/onlinedocs/gdb/Hooks.html)：

```CONSOLE
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`

## See also

### 外部链接

[CLion Debugging Beyond the Basics - Part 3 - Beyond Local](https://blog.jetbrains.com/clion/2021/05/clion-debugging-beyond-the-basics-part-3-beyond-local) [Webinar Recording: Remote Development with CLion](https://blog.jetbrains.com/clion/2019/03/webinar-recording-remote-development-with-clion) [LLDB Remote Debugging](https://lldb.llvm.org/use/remote.html)

