# 调试配置文件

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

> **TL;DR**
> 操作系统 ：Windows、Linux、macOS

调试配置文件定义了 CLion 如何调试应用程序：使用哪个调试器以及如何配置。 配置文件可复用并且独立于 [工具链](how-to-create-toolchain-in-clion.html)，因此可以在不改变项目构建方式的情况下更换调试器。

每个调试配置文件都与 CMake 配置文件和运行/调试配置分离：

* [CMake 配置文件](cmake-profile.html)（及其工具链）定义了项目的构建方式。

* [运行/调试配置](run-debug-configuration.html)定义要运行的内容：目标、程序实参和环境。

* 调试配置文件定义了调试方式：调试器及其选项。

可以在主工具栏分别选择活动的 CMake 配置文件和调试配置文件，因此可以将任意构建与兼容调试器配对使用。

![CLion 工具栏中的配置文件切换器已打开，CMake 配置文件设置为 Debug，调试配置文件设置为活动 LLDB 配置文件。](https://resources.jetbrains.com/help/img/idea/2026.3/cl_profiles_switcher_popup.png)

> **Note:**
> 调试配置文件从 CLion 2026.2 起可用，并替代了之前分开的调试器设置：工具链中设置的调试器、 [DAP 调试器](dap-support.html)页面，以及 [调试服务器](debug-servers.html)页面。 打开由早期版本创建的项目时，CLion 会自动将这些设置转换为调试配置文件。 如需了解更多信息，请参阅 [从早期版本迁移](#migration)。

## 调试配置文件类型

CLion 将可用调试器类型分为两类。

通用调试器 ：

* [GDB](https://www.gnu.org/software/gdb)

* [LLDB](https://lldb.llvm.org)

* 支持 [调试适配器协议 (DAP)](dap-support.html)的调试器

用于嵌入式开发的调试器 ：

* GDB 服务器（通用 `gdbserver` 配置文件）

* [SEGGER J-Link](https://www.segger.com/products/debug-probes/j-link/)

* 用于 [STM32CubeMX](embedded-stm32.html) 项目的 ST-LINK

* 用于 [ESP-IDF](esp-idf.html) 项目的 ESP-IDF

在搭载 Apple Silicon 的 macOS 上，还可使用 Rosetta GDB 配置文件调试  `aarch64`  主机上的 x86 目标。

## 打开调试配置文件设置

转到  `设置 | 构建、执行、部署 | 调试器 | 调试配置文件},{` 。

![调试配置文件设置页面列出了 GDB 配置文件，并有图块可用于创建嵌入式和通用调试器配置文件。](https://resources.jetbrains.com/help/img/idea/2026.3/cl_debug_profiles_settings.png)

左侧列表显示已有配置文件。 右侧图块用于创建所选类型的新配置文件。 CLion 会检测适用于当前平台的默认配置文件，因此首次运行时该列表不会为空，例如 Linux 上为 GDB 配置文件，macOS 上为 LLDB 配置文件。

Procedure: 创建调试配置文件

1. 点击你需要的调试器类型图块，位于   通用调试器   或   用于嵌入式开发的调试器   下方。 CLion 会将该类型的新配置文件添加到列表中。

![调试配置文件创建图块，适用于嵌入式调试器 ESP-IDF、SEGGER J-Link、ST-LINK、GDB 服务器，以及通用 DAP、GDB、LLDB。](https://resources.jetbrains.com/help/img/idea/2026.3/cl_debug_profile_create.png)

2. 配置配置文件字段后，点击   确定  。

## 配置通用配置文件

GDB 或 LLDB 配置文件包含如下字段：

![CLion 调试配置文件设置，GDB 配置文件显示名称、可执行文件和高级字段，以及存储选项。](https://resources.jetbrains.com/help/img/idea/2026.3/cl_debug_profile_gdb.png)

名称
: 在列表及工具栏切换器中显示的配置文件名称。

可执行文件
: 调试器二进制文件的路径。 将该字段留空可使用捆绑的 GDB 或 LLDB（如果有），或  `PATH` 中的调试器。 在远程、Docker 或 WSL 工具链中，CLion 会从当前环境解析调试器。

高级
: 应用于调试会话的特定类型选项。 针对 DAP 配置文件，请使用   启动  和   附加  标签页，以 JSON 形式提供适配器配置。

> **Note:**
> 可执行文件   字段在 Windows 上的 LLDB 中不可用，CLion 会使用捆绑的 LLDB。

## 选择活动调试配置文件

在主工具栏的调试配置文件切换器中选择活动配置文件。 切换器以   调试 | <profile>   显示当前配置文件，并位于运行/调试配置选择器旁边。

![CLion 工具栏中的配置文件切换器已打开，CMake 配置文件设置为 Debug，调试配置文件设置为活动 LLDB 配置文件。](https://resources.jetbrains.com/help/img/idea/2026.3/cl_profiles_switcher_popup.png)

当项目有多个 CMake 配置文件时，切换器会分别显示 CMake 配置文件组和调试配置文件组。 每组分别选择一个配置文件：CMake 配置文件定义构建，调试配置文件定义调试器。 每组还提供到对应设置页面的链接。

调试配置文件将会应用于下次使用 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.startDebugger.svg) 启动的调试会话。 使用 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.execute.svg) 运行应用程序时不需要调试配置文件。

## 共享调试配置文件

默认情况下，配置文件存储在项目中。 你可以在配置文件设置中的两个选项中更改配置文件的存储位置：   在所有项目中可用   和   共享  。

![GDB 调试配置文件取消选中“适用于所有项目”并选中“共享”，以将该配置文件存储到版本控制中。](https://resources.jetbrains.com/help/img/idea/2026.3/cl_debug_profile_share.png)

在所有项目中可用
: 将配置文件存储到 IDE 设置中，可在你打开的任何项目中使用。

共享
: 将配置文件存储到  `.idea/debug-profiles.xml` 文件，就可以提交到 [版本控制](version-control-integration.html)并与团队成员共享。

上述选项只能单独使用：仅当   在所有项目中可用  未选中时，   共享  才可用。

## 支持的运行/调试配置

你可以在以下运行/调试配置中使用调试配置文件：

* [CMake 应用程序](run-debug-configuration-application.html)

* [本机应用程序](run-debug-configuration-makefile-application.html)

* [远程调试](remote-debug.html)

* [核心转储调试](core-dump-debug-configuration.html)

* C/C++ 文件

当 [附加到进程](attach-to-process.html)时，对话框会列出与所选主机兼容的调试配置文件。

## 从早期版本迁移

当打开由 CLion 2026.1 或更早版本创建的项目时，CLion 会将已有调试器设置转换为调试配置文件，该操作仅执行一次。 转换内容包括：

* 工具链中设置的调试器和 DAP 调试器会被转换为可用于所有项目的配置文件。

* 远程调试和核心转储调试配置中使用的自定义调试器，会被转换为项目配置文件。

* 已配置的调试服务器会被转换为项目配置文件。

转换仅在首次打开项目时执行一次，不会重复，因此配置文件无需额外设置即可直接使用。

## 工具链中设置的调试器

调试器   字段在  `设置 | 构建、执行、部署 | 工具链`  中已弃用，推荐使用调试配置文件。

![CLion 工具链设置，提示工具链调试器字段已弃用，建议使用调试配置文件。](https://resources.jetbrains.com/help/img/idea/2026.3/cl_toolchain_debugger.png)

启动调试会话时，CLion 会使用所选调试配置文件，而不是工具链调试器。

## See also

### 相关内容

[调试器选项](configuring-debugger-options.html) [调试服务器](debug-servers.html) [Debug Adapter Protocol (DAP)](dap-support.html) [Start a debug session](starting-the-debugger-session.html)

### 操作指南

[CMake 配置文件](cmake-profile.html) [工具链](how-to-create-toolchain-in-clion.html)

