# 教程：在 Windows 上配置 CLion

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

在 Windows 上，CLion 工具链包括构建工具、C 和 C++ 编译器、调试器可执行文件以及环境。 您可以选择一个预定义的工具链设置（ [MinGW](#MinGW)、 [Cygwin](#Cygwin)、 [Microsoft Visual C++](#MSVC) 或 [WSL](#WSL)、 [Remote Host](remote-projects-support.html#remote-toolchain)、 [Docker](clion-toolchains-in-docker.html)），或者配置一个自定义工具链（ [System](#system)）：

![Windows 工具链选项](https://resources.jetbrains.com/help/img/idea/2026.3/cl_toolchain_options.png)

观看此视频以了解 Windows 工具链选项的概述：

[Video](https://www.youtube.com/v/Vj06cfj6LyI)

> **Tip:**
> 如果不需要配置自定义工具，或不想在系统上安装其他软件，请继续使用 [MinGW](#MinGW)（默认），因为它可以使用 CLion 捆绑的 MinGW 工具包开箱即用。

有关   远程主机  工具链的更多信息，请参阅 [本地源的远程](remote-projects-support.html#remote-toolchain)。 如果您使用的是 Docker 容器，请参阅 [Docker 工具链](clion-toolchains-in-docker.html)。

## MinGW

CLion 捆绑了一个 MinGW 工具集版本以便快速设置。 捆绑的确切版本是 MinGW-w64 13.1，包括  `languages=c,c++` 、  `posix`  线程和  `seh`  异常。 可以使用此捆绑工具链，也可以切换到自定义 MinGW 安装。

### 安装 MinGW（可选）

MinGW-w64（64 位和 32 位）:

Procedure:

1. 下载并运行 [MinGW-w64](https://jb.gg/clion-mingw) 安装程序。 它提供了 64 位和 32 位选项。

2. 在   MinGW-w64   安装向导中，请确保选择所需的架构。 请注意，默认建议的选项是 32 位。

![为 MinGW 选择 64 位架构](https://resources.jetbrains.com/help/img/idea/2026.3/cl_mingw_64_arch.png)

3. 等待安装完成。

MinGW（仅限 32 位）:

尽管 MinGW-w64 提供了 64 位和 32 位选项，您也可以安装 [MinGW](https://osdn.net/projects/mingw/)，仅限 32 位版本。

Procedure:

1. 在   MinGW   安装向导中，从   基本设置   列表中选择以下软件包：  `mingw-developer-tool` 、  `mingw32-base` 、  `mingw32-gcc-g++` 、  `mingw32-msys-base` 。

![MinGW 安装](https://resources.jetbrains.com/help/img/idea/2026.3/cl_MinGWInstall.png)

2. 等待安装完成。

Procedure: 配置 MinGW 工具链

1. 转到  `文件 | 设置 | 构建、执行、部署 | 工具链` 。

点击 ![添加工具链](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg) 并选择   MinGW   以添加新的 MinGW 工具链。

2. 在   工具集   字段中，您将看到  Bundled MinGW ，这是默认选项。 如果需要，打开该字段，从其他可用安装列表中进行选择：

![MinGW 安装列表](https://resources.jetbrains.com/help/img/idea/2026.3/cl_mingw_bundled_list.png)

3. 等待工具检测完成。

![捆绑的 MinGW 工具链](https://resources.jetbrains.com/help/img/idea/2026.3/cl_mingw_bundled_tools_detected.png)

4. 选择   调试器  ：您可以使用捆绑的 GDB、您的 MinGW GDB 或自定义 GDB 二进制文件。

> **Note:**
> * 推荐使用捆绑的 GDB，因为它保证包含 CLion [data renderers](configuring-debugger-options.html#debugger-renderers) 所需的 Python 支持。
>
> * GDB 尚不支持在 Windows ARM64 上进行调试。 对于此类系统，CLion 捆绑的 GDB 仅用于远程调试。

5. 如果需要， [指定用于初始化环境的脚本](how-to-create-toolchain-in-clion.html#env-scripts)。

6. 当所有工具设置正确时，点击   Apply  。

> **Tip:**
> 使用自定义 MinGW 安装时，如果 CLion 无法检测到编译器，请仔细检查   MinGW 安装管理器   中安装的软件包。

## Cygwin

Procedure:

1. 下载 [Cygwin](https://jb.gg/clion-cygwin) 安装程序，版本为 2.8 或更高。

2. 运行安装程序并选择以下软件包：

* `gcc-g++`

* `cmake`

* `gdb`

CLion 不附带适用于 Cygwin 的 CMake 构建，因此 Cygwin 工具链会使用 Cygwin 安装中的  `cmake`  软件包。

要选择软件包，请在   搜索   字段中输入其名称，并在   新建   列中设置版本：

![Cygwin 安装](https://resources.jetbrains.com/help/img/idea/2026.3/cl_CygwinSetup.png)

3. 安装完成后，打开 CLion 并转到  `文件 | 设置 | 构建、执行、部署 | 工具链` 。

4. 点击 ![添加工具链](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg) 并选择   Cygwin   以添加新的 Cygwin 工具链。

CLion 将尝试自动检测 Cygwin 安装。 检查   工具集   字段，并在需要时手动指定路径。

5. 等待工具检测完成。

在   CMake   字段中，CLion 会选择   Cygwin 版 CMake  ，它是 Cygwin 安装中的  `cmake`  可执行文件。 如果 CLion 未找到它，请安装  `cmake`  软件包，或打开该字段并选择另一个 CMake 安装。

点击   Apply  。

6. 如果需要， [指定用于初始化环境的脚本](how-to-create-toolchain-in-clion.html#env-scripts)。

## Windows Subsystem for Linux（Windows 子系统 Linux）

可以在 Windows 10 上使用 [WSL](https://docs.microsoft.com/en-us/windows/wsl/about), 适用于 Linux 的 Windows 子系统, 作为 CLion 中的工作环境 (从 Fall Creators Update 版本 1709, 构建 16299.15 开始)。

WSL 工具链启用了使用 CMake 和 Linux 中的编译器构建项目，并在 WSL 上运行/调试的功能，而无需离开 Windows 计算机上运行的 CLionLion。

> **Note:**
> 有关在系统上设置 WSL 和配置 WSL 工具链的更多信息，请参阅 [WSL guide](how-to-use-wsl-development-environment-in-product.html)。

![WSL 工具链](https://resources.jetbrains.com/help/img/idea/2026.3/cl_wsl_new_toolchain.png)

## Microsoft Visual C++

Procedure:

1. 在系统上安装 [Visual Studio](https://jb.gg/clion-msvs) 2017、2019 或 2022。

2. 在 CLion 中，转到  `文件 | 设置 | 构建、执行、部署 | 工具链` 。

3. 点击 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg) 并从工具链模板列表中选择   Visual Studio  。

4. 检查   工具集   字段。 CLion 将尝试自动检测已安装的 Visual Studio 发行版。 如果检测失败，请手动设置 Visual Studio 的路径。

5. 如果需要，指定   架构  （  x86 、  amd64 、  x86_arm  或其他）、   平台  （  store 、  uwp 、  onecore  或留空）和   Version  。 为了针对所选架构构建项目，CLion 将调用脚本，以使用指定参数配置环境。

> **Tip:**
> 如果编译器工具包的版本早于 Visual Studio 安装版本，请在   Version   字段中通过  `vcvars_ver`  标志传递该版本，例如  `-vcvars_ver=14.16` 。

6. 等待工具检测完成：

![MSVC 工具链](https://resources.jetbrains.com/help/img/idea/2026.3/cl_msvc_toolchain.png)

7. 如果需要， [指定用于初始化环境的脚本](how-to-create-toolchain-in-clion.html#env-scripts)。

### MSVC 编译器

CLion 支持随 Visual Studio 2017、2019 和 2022 一起提供的 Microsoft Visual C++ 编译器。

如果代码包含 [MSVC 扩展程序](https://docs.microsoft.com/cpp/build/reference/microsoft-extensions-to-c-and-cpp)，CLion 将提供以下支持：

* `__uuidof` 、 `__forceinline` 、 `__unaligned` 和 `__alignof` 关键字；

* 指针类型属性： `__ptr32` 、 `__ptr64` 、 `__uptr` 、 `__sptr` ；

* MSVC 内置数据类型： `(unsigned) __int8` 、 `(unsigned) __int16` 、 `(unsigned) __int32` 、 `(unsigned) __int64` 、 `__wchar_t` ；

* 其他格式说明符，例如 `%I32` 和 `%I64` ；

* [clang](https://clang.llvm.org/) 的 `-fms-extensions` 标志。

### Clang-cl 编译器

作为替代编译器，您可以使用 [clang-cl](https://clang.llvm.org/docs/UsersManual.html#clang-cl)——Clang 的 MSVC 兼容编译器驱动程序。 CLion 支持   clang-cl   版本 8.0 及更高版本。

Procedure:

1. 从 [LLVM site](http://llvm.org/releases/download.html) 或与 Visual Studio 工具一起安装   clang-cl  。

从 LLVM 网站安装时，可以在 64 位版本的标准位置  `C:\Program Files\LLVM\bin\clang-cl.exe`  或 32 位版本的标准位置  `C:\Program Files (x86)\LLVM\bin\clang-cl.exe`  找到   clang-cl   二进制文件。

2. 在 CLion 中，转到  `文件 | 设置 | 构建、执行、部署 | 工具链` ，然后选择要配置的   Visual Studio   工具链，或 [创建](#new-toolchain)一个新的工具链。

3. 将   C 编译器   和   C++ 编译器   字段指向  `clang-cl.exe` 。 CLion 将建议自动检测到的路径。

![Clang-cl 编译器](https://resources.jetbrains.com/help/img/idea/2026.3/cl_msvc_toolchain_clang.png)

请注意，如果使用捆绑的 CMake 与 Visual Studio 工具链设置（ [CPP-18848](https://youtrack.jetbrains.com/issue/CPP-18848)），当前无法拾取  `-T clangcl`  选项。

### MSVC 调试器

MSVC 工具链调试器基于 LLDB 实现，可以使用 Visual Studio 安装或项目中的原生可视化器。

本地可视化器或 Natvis 渲染器在 CLion 中默认启用。 要设置所需的诊断级别，请转到  `设置 | 构建、执行、部署 | 调试器 | 数据视图 | C/C++ | 渲染器` ：

![MSVC Natvis](https://resources.jetbrains.com/help/img/idea/2026.3/cl_msvc_natvis.png)

CLion 会自动为所有未被 Natvis 覆盖的结构生成单行摘要，并高亮显示以提高可读性。 此外，内置格式化程序为宽/Unicode 字符串（  `wchar_t` 、  `char16_t` 、  `char32_t` ）提供可视化。

默认情况下，CLion 会自动查找并加载添加到项目模型、属于所选 MSBuild 或 MSVC 工具链，或位于  `%USERPROFILE%\Documents\Visual Studio Version\Visualizers`  中的  `.natvis`  文件。

![使用自定义 NatVis 进行 MSVC 调试](https://resources.jetbrains.com/help/img/idea/2026.3/cl_msvc_debug_natvis.png)

您还可以为  `.natvis`  文件指定自定义位置。 转到  `设置 | 构建、执行、部署 | 调试器 | 数据视图 | C/C++`  并添加一个包含 Natvis 渲染器的额外目录：

![Natvis 文件的自定义位置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_msvc_natvis_location.png)

CLion 支持大多数 Natvis 自定义功能，例如 [ArrayItems](https://docs.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects#BKMK_ArrayItems_expansion)、 [IndexListItems](https://docs.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects#BKMK_IndexListItems_expansion)、 [LinkedListItems](https://docs.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects#BKMK_LinkedListItems_expansion)、 [TreeItems](https://docs.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects#BKMK_TreeItems_expansion)、 [Inheritable attribute](https://docs.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects#inheritable-attribute)、 [Format specifiers](https://docs.microsoft.com/en-us/visualstudio/debugger/format-specifiers-in-cpp) 和 [CustomListItems](https://docs.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects#customlistitems-expansion)。

使用 MSVC 工具链调试器时，您可以启用符号服务器支持，这将帮助调试器正确解析库符号。 欲了解更多信息，请参阅 [在 Windows 上调试时使用符号服务器](using-symbol-servers-when-debugging-on-windows.html)。

## 系统工具链

Windows 上的   系统   工具链允许配置构建工具、编译器和调试器，而无需选择预定义的工具包或环境，类似于 Linux 和 macOS。 对于使用 ARM 等 [嵌入式开发](embedded-stm32.html)场景或其他自定义设置，请使用此工具链选项。

Procedure:

1. 在主菜单中，进入  `文件 | 设置 | 构建、执行、部署 | 工具链` .

2. 点击 ![添加工具链](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg) 并选择   系统   以添加新的系统工具链。

3. 配置工具，并在需要时提供 [环境脚本](how-to-create-toolchain-in-clion.html#env-scripts)：

![系统工具链配置示例](https://resources.jetbrains.com/help/img/idea/2026.3/cl_system_toolchain_example.png)

## 通过脚本初始化工具链环境

与手动设置环境相比，您可以将 CLion 指向一个环境文件——一个为您的项目初始化环境的 shell 脚本。 例如，当您需要初始化编译器变量、添加自定义变量或修改  `PATH`  时，这会很有帮助。

支持以下环境文件：

* `bat` 文件 — Windows MinGW 和 MSVC 工具链。

* `ps1` 文件 — Windows MinGW、Cygwin 和 MSVC 工具链。

* `shell` 文件 — Windows Cygwin、本地 Linux／macOS、WSL、Docker 和远程工具链。 > **Tip:** > 参见 [设置备用 shell](#set-shell)。

大多数框架都包含环境脚本，您可以直接使用。 请参阅 [ESP-IDF on macOS](esp-idf.html#env-vars-macos) 的示例。 您还可以创建自己的脚本，例如，当您需要源多个环境文件时：请参阅 [ESP-IDF on Windows](esp-idf.html#env-vars-windows) 的示例。

> **Note:**
> * 工具链环境会影响使用该特定工具链执行的所有步骤，包括 CMake 生成、构建和二进制启动。
>
> * 对于除 [Docker](clion-toolchains-in-docker.html) 之外的所有工具链，环境加载仅发生一次：第一次在 [CMake profile](cmake-profile.html) 中使用工具链或加载 [Makefile](makefiles-support.html) 时。 对于 Docker，每次使用工具链时都会加载环境。
>
> * 当您对环境文件进行更改时，CLion 默认会自动重新加载它。 您可以通过取消选中 设置 | 高级设置 中的 根据文件修改时间戳缓存环境文件中的环境 选项来防止环境状态被自动缓存。 此外，请注意， [重置 CMake](cmake-cache.html#reset-cache) 会使环境文件缓存失效。

Procedure:

1. 在工具链设置中，点击   添加环境  ，然后点击   从文件  ：

![设置脚本以初始化环境](https://resources.jetbrains.com/help/img/idea/2026.3/cl_toolchain_env_script.png)

2. 在   环境文件   字段中，指定脚本的路径：

![通过脚本初始化环境](https://resources.jetbrains.com/help/img/idea/2026.3/cl_toolchain_env_script_file.png)

3. 如果脚本加载出现问题，您将收到通知。 CLion 还会检查脚本加载时间，并在执行时间过长时终止执行。

![环境脚本加载报告](https://resources.jetbrains.com/help/img/idea/2026.3/cl_env_script_error.png)

Procedure: 设置备用 shell

* 要在 Linux（本地或远程）、 [WSL](how-to-use-wsl-development-environment-in-product.html) 和 [Docker](clion-toolchains-in-docker.html) 上加载环境文件，CLion 会在默认登录 shell 中调用  `source`  或  `.` ，具体取决于  `$SHELL`  变量。

如果  `$SHELL`  为空，CLion 将使用   用于加载环境的回退 shell   字段中 [高级设置](advanced-settings.html) 指定的 shell。

## Windows 上的 Clang 编译器

从 CMake [3.15](https://cmake.org/cmake/help/latest/release/3.15.html) 开始，可以在 Windows 上将 Clang 编译器与 MinGW-w64/MinGW 工具链一起使用。

然而，Windows 的 LLVM Clang 是使用 Microsoft Visual Studio 构建的，所有内置宏和包含搜索路径都设置为与 Visual Studio 一起使用。 因此，如果从 [LLVM 仓库](https://github.com/llvm) 获取 Clang，在使用 MinGW 工具链配置时，它将无法正常工作。 以下描述了一种可能的解决方法。

Procedure: 为 MinGW 设置 Clang 编译器

1. 安装 [MSYS2](https://www.msys2.org/)。

2. 在 MSYS 终端中，运行以下 [pacman](https://wiki.archlinux.org/index.php/pacman) 命令以下载使用 clang 构建的完整 [set of packages](https://packages.msys2.org/groups/mingw-w64-clang-x86_64-toolchain)：

```CONSOLE
pacman -S mingw-w64-clang-x86_64-toolchain

```

再运行一个命令以获取 MinGW-w64 GDB 调试器：

```CONSOLE
pacman -S mingw-w64-clang-x86_64-gdb

```

3. 转到  `设置 | 构建、执行、部署 | 工具链`  并创建一个   MinGW   工具链。

将   工具集   设置为  `C:\msys64\clang64` 。 如果其他路径未被自动检测到，请手动设置。

![MSYS MinGW 工具链](https://resources.jetbrains.com/help/img/idea/2026.3/cl_clang_mingw.png)

> **Note:**
> 配置好这个新工具链后，可以构建项目并开始使用 Clang 的高级工具，例如 [配置文件引导优化](https://clang.llvm.org/docs/UsersManual.html#profile-guided-optimization)。 请查看 [这篇博文](https://blog.jetbrains.com/clion/2020/12/setting-up-clang-on-windows/#using_advanced_tools_provided_by_the_clang_compiler) 获取说明。

## Windows 上的 GDB

对于 MinGW，CLion 包含捆绑的 GDB（版本 17.1）。 对于 Cygwin，需要在 Cygwin 软件包管理器中安装 GDB 软件包，如本指南的 [Cygwin](#Cygwin) 部分所述。

还可以切换到自定义 GDB 二进制文件。 在这种情况下，支持的 GDB 版本为 7.8.x-17.1。

请注意，对于 GDB 8.0 及更高版本，调试器输出默认会重定向到 CLion 控制台。 要启用打开外部控制台窗口以进行应用程序输入/输出，请转到   帮助 | 查找操作   或按 `Ctrl+Shift+A` (Windows), `⌘ ⇧ A` (macOS), `⌘ ⇧ A` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ P` (macOS System Shortcuts), `Ctrl+Shift+A` (XWin), `Ctrl+Shift+A` (GNOME), `Ctrl+Shift+A` (KDE), `Escape, X` (Emacs), `Ctrl+Shift+P` (Sublime Text), `⌘ ⇧ P` (Sublime Text (macOS)), `⌘ ⇧ A` (Xcode), `Ctrl+Shift+A` (Visual Studio), `⌘ ⇧ A` (Visual Studio (macOS)), `Ctrl+Shift+A` (ReSharper), `⌘ ⇧ A` (ReSharper (macOS)), `Ctrl+Shift+A` (QtCreator), `⌘ ⇧ A` (QtCreator (macOS)), `Ctrl+I` (NetBeans), `Ctrl+Shift+A` (Eclipse), `⌘ 3` (Eclipse (macOS))，搜索  Registry ，并设置以下键：    cidr.debugger.gdb.workaround.windows.forceExternalConsole   。

## See also

### 操作指南

[安装 CLion](installation-guide.html) [快速 CMake 教程](quick-cmake-tutorial.html) [工具链](how-to-create-toolchain-in-clion.html) [编译器](how-to-switch-compilers-in-clion.html) [Working with WSL](how-to-use-wsl-development-environment-in-product.html) [远程开发](remote-development.html) [Debugger options](configuring-debugger-options.html)

### 语言、框架与技术

[Qt Projects](qt-tutorial.html) [CUDA Projects](cuda-projects.html)

### 外部链接

[CLion blog: Setting up the Clang Compiler in CLion on Windows](https://blog.jetbrains.com/clion/2020/12/setting-up-clang-on-windows/)