# Qt 项目

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

[Qt](https://www.qt.io/) 是一个用于创建 GUI 应用程序的跨平台 C++ 框架。 Qt 使用其自有的构建系统 [qmake](https://wiki.qt.io/Qmake)，并且从 Qt4 版本开始支持 [使用 CMake 构建](https://doc.qt.io/qt-5/cmake-manual.html)。

纯 Qmake 项目无法直接导入到 CLion 中。 但是，当转换为 CMake 后，可以作为常规 [CMake 应用程序](quick-cmake-tutorial.html) 打开和管理。 您还可以使用新建项目向导在 CLion 中 [创建一个基于 CMake 的 Qt 项目](#qt-template)。

> **Tip:**
> 打开 Qt 项目的另一种方法是使用 [编译数据库](compilation-database.html)。 您可以通过 [scan-构建](https://github.com/rizsotto/scan-build) 或通过 Qt Creator 中的  `构建 | 生成编译数据库`  操作为您的 qmake 项目生成  `compile_commands.json` ，然后将此文件作为项目在 CLion 中打开，并为其添加 [自定义构建目标和自定义运行/调试配置](custom-build-targets.html)。

## 基于 CMake 的 Qt 项目

对于 CMake 3.0 及更新版本，Qt 提供了模块，使 CMake 能够找到并使用 Qt4 和 Qt5 库。 按照以下步骤为您的 Qt 项目配置 [CMakeLists.txt](cmakelists-txt-file.html)。

Procedure: Qt 项目的 CMakeLists.txt

1. 添加  `find_package`  命令以定位所需的库和头文件。 例如：

```CMAKE
find_package(Qt5Widgets REQUIRED)
                
```

然后，使用  `target_link_libraries`  使您的目标依赖于这些库和头文件：

```CMAKE
target_link_libraries(helloworld Qt5::Widgets)
```

2. 为了让  `find_package`  成功执行，CMake 应该被告知在哪里找到 Qt 安装。

其中一种方法是设置  `CMAKE_PREFIX_PATH`  变量。 您可以通过 [CMake 设置](#cmake-settings) 对话框中的  `-D`  或通过  `set`  命令在  `find_package`  之前传递它。

例如，在 Windows 上使用 MinGW 的情况下：

```CMAKE
set(CMAKE_PREFIX_PATH "C:\\Qt\\Qt5.14.0\\5.14.0\\mingw73_32\\")
```

或

```CMAKE
set(CMAKE_PREFIX_PATH "C:\\Qt\\Qt5.14.0\\5.14.0\\mingw73_32\\lib\\cmake\\")
```

3. 如果您的项目使用 [MOC](https://doc.qt.io/archives/qt-4.8/moc.html)、 [UIC](https://doc.qt.io/archives/qt-4.8/uic.html) 或 [RCC](https://doc.qt.io/qt-5/rcc.html)，请添加以下行以启用相应编译器的自动调用：

```CMAKE
set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTOUIC ON)
set(CMAKE_AUTORCC ON)

```

4. 在  `add_executable()`  命令中列出所有  `.ui`  和  `.qrc`  文件以及您的  `.cpp`  源文件：

```CMAKE
add_executable(
    helloworld
    main.cpp mainwindow.cpp
    application.qrc
)
                
```

以下是一个简单的 "Hello, world" 应用程序的完整  `CMakeLists.txt`  脚本：

```CMAKE
cmake_minimum_required(VERSION 3.10)
project(Qt-CMake-HelloWorld)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_INCLUDE_CURRENT_DIR ON)
set(CMAKE_PREFIX_PATH "C:\\Qt\\Qt5.14.0\\5.14.0\\mingw73_32\\")

find_package(Qt5Widgets REQUIRED)

set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTOUIC ON)
set(CMAKE_AUTORCC ON)

add_executable(helloworld main.cpp mainwindow.cpp application.qrc)
target_link_libraries(helloworld Qt5::Widgets)
        
```

## 在 CLion 中设置 Qt 项目

Procedure: Windows 上的工具链

1. 在 Windows 上安装 Qt 时，请选择与您在 CLion 中使用的环境相匹配的发行版，例如 MinGW 或 MSVC。

对于 MinGW，版本和位数（32 位 MinGW 或 MinGW-w64）都应与您的工具链设置匹配。

![Qt 安装程序](https://resources.jetbrains.com/help/img/idea/2026.3/cl_qt_installer.png)

2. 在 CLion 中，转到  `设置` （ `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `⌘ Comma` (Xcode), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (ReSharper), `⌘ Comma` (ReSharper (macOS)), `Ctrl+Alt+S` (QtCreator), `⌘ Comma` (QtCreator (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS))），导航到  `构建、执行、部署 | 工具链`  并选择与您的 Qt 安装匹配的工具链。

如果您有多个 Qt 安装，请确保选择与您在  `CMAKE_PREFIX_PATH`  中 [指定](#configure-cmakelists)的相同工具链。

例如，在 MinGW 的情况下：

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

> **Tip:**
> 有关 Windows 工具链的更多信息，请参阅我们 Windows 教程中的 [MinGW](quick-tutorial-on-configuring-clion-on-windows.html#MinGW) 或 [MSVC](quick-tutorial-on-configuring-clion-on-windows.html#MSVC) 部分。

Procedure: CMake 设置

* Qt 项目在 CLion 中被视为常规 CMake 项目，因此您可以根据需要在  `设置 | 构建、执行、部署 | CMake`  中配置 CMake 设置。

例如，您可以创建具有不同 [构建类型](cmake-profile.html#buildtypes) 的不同 CMake 配置文件，并设置您选择的 CMake [生成器](cmake-profile.html#cmake-generators)。

在此对话框中，您还可以指定 CMake 选项，例如  `CMAKE_PREFIX_PATH` ，而不是在  `CMakeLists.txt`  中设置它们：

![Qt 项目的 CMake 选项](https://resources.jetbrains.com/help/img/idea/2026.3/cl_qt_cmake_options.png)

Procedure: 调试器渲染器

根据所使用的平台和工具链，CLion 为 Qt 项目提供不同类型的调试器渲染器。

在 Windows MinGW、macOS 和 Linux 上，IDE 提供 Qt 调试器渲染器，也称为 Qt pretty printers 和 Qt 调试帮助程序。 它们允许你以易于阅读的形式视图 Qt 类型，比如  `QString`  或  `QByteArray` 。

如果你使用 [带有 MSVC 工具链的 Windows](quick-tutorial-on-configuring-clion-on-windows.html#msvc-debugger)，IDE 会提供 Natvis 渲染器，这些渲染器使用 Visual Studio 的原生可视化器格式。

两种渲染器类型在 CLion 中默认启用。 您可以在  `设置 | 构建、执行、部署 | 调试器 | 数据视图 | C/C++ | 渲染器`  中禁用它们。

> **Note:**
> Qt 渲染器尚不支持远程和 WSL 工具链。

Procedure: 在 Qt Designer 中打开 UI 文件

默认情况下，CLion 在 [Qt Designer](https://doc.qt.io/qt-5/qtdesigner-manual.html) 中打开  `.ui`  文件。

IDE 在  `设置 | 语言与框架 | QML`  中指定的  `Qt binaries`  文件夹中搜索 Qt Designer 的路径。

如果您单独安装了 Qt Designer 而不是 Qt，CLion 可能无法检测到它，并将在编辑器中打开  `.ui`  文件。 在这种情况下，请执行以下操作以在 Qt Designer 中打开它们：

1. 转到  `设置 | 编辑器 | 文件类型` 。

2. 从   识别的文件类型   列表中选择  Qt UI Designer Form ，并删除关联的文件扩展名：

![移除 .ui 文件的关联](https://resources.jetbrains.com/help/img/idea/2026.3/cl_qt_ui_removeassoc.png)

3. 选择  在关联应用程序中打开的文件 ，并添加  `.ui`  扩展名：

![将 .ui 重新分配给外部应用程序](https://resources.jetbrains.com/help/img/idea/2026.3/cl_qt_ui_externalapp.png)

4. 点击   重新分配通配符  。

5. 点击   Apply   并关闭对话框。

下次您在项目树中双击  `.ui`  文件时，它将在 Qt Designer 中打开。

## 创建基于 CMake 的 Qt 项目

CLion 提供了两个 Qt 项目模板：Qt 控制台可执行文件和 Qt 小部件可执行文件。

调用  `文件 | 新建项目`  并在左侧窗格中选择项目类型。 指定位置、语言标准和 Qt 版本。 您还可以提供在  `CMAKE_PREFIX_PATH`  中使用的路径。 点击   创建   即可。

![Qt 项目模板](https://resources.jetbrains.com/help/img/idea/2026.3/cl_qt_projectwizard.png)

CLion 将生成一个即用型的存根项目，其中  `CMakeLists.txt`  会自动填充，包括  `CMAKE_PREFIX_PATH`  变量：

![Qt 控制台可执行模板项目](https://resources.jetbrains.com/help/img/idea/2026.3/cl_qt_consoleexe_addprefixpath.png)

> **Tip:**
> 您可以在  `设置 | 编辑器 | 文件和代码模板`  的   其他   选项卡中编辑 Qt 项目的  `CMakeLists.txt`  模板。 有关更多信息，请参阅 [CMakeLists.txt 文件模板](cmakelists-txt-file.html#cmakelist-template)。

## Qt UI 类模板

您可以快速创建一个 Qt 类，并生成相应的  `.ui` 、  `.cpp`  和  `.h`  文件。

Procedure:

1. 在项目视图中，从上下文菜单中选择   新建   或按 `Alt+Insert` (Windows), `⌘ N` (macOS), `⌃ N` (IntelliJ IDEA Classic (macOS)), `⌘ N` (macOS System Shortcuts), `Alt+Insert` (XWin), `Alt+Insert` (GNOME), `Alt+Insert` (KDE), `Alt+Insert` (Emacs), `Ctrl+N` (Sublime Text), `⌘ N` (Sublime Text (macOS)), `⌘ N` (Xcode), `Ctrl+N` (Visual Studio), `⌘ N` (Visual Studio (macOS)), `Alt+Insert` (ReSharper), `⌥ Insert` (ReSharper (macOS)), `Alt+Insert` (QtCreator), `Alt+Insert` (QtCreator (macOS)), `Alt+Insert` (NetBeans), `Alt+Insert` (Eclipse), `⌘ N` (Eclipse (macOS))。 选择   Qt UI 类  ：

![新建 Qt UI 类菜单选项](https://resources.jetbrains.com/help/img/idea/2026.3/cl_qt_new_uiclass.png)

2. 在打开的对话框中，填写类名并配置以下设置：

* 文件名基础 - 指定要生成的 `.ui` / `.cpp` / `.h` 文件的名称。

* 父类 - 选择 `QWidget` 、 `QMainWindow` 、 `QDialog` 或自定义父类。

* 命名空间 - 如果需要，指定封闭命名空间。

* 添加到目标 - 勾选此复选框以自动将新文件添加到所选目标的源列表中。

![新建 Qt UI 类对话框](https://resources.jetbrains.com/help/img/idea/2026.3/cl_qt_new_uiclass_dialog.png)

3. CLion 将根据定义在  `设置 | 编辑器 | 文件和代码模板`  中的 [模板](using-file-and-code-templates.html) 生成  `.ui` 、  `.cpp`  和  `.h`  文件：Qt Designer Form、Qt Class 和 Qt Class Header。 如果需要，您可以根据需要调整这些模板。

![为新建 Qt UI 类生成的文件](https://resources.jetbrains.com/help/img/idea/2026.3/cl_qt_ui_generated.png)

## Qt 特定的代码智能感知

* CLion 为 [Qt 信号和槽](https://doc.qt.io/qt-5/signalsandslots.html) 提供 [代码补全](auto-completing-code.html)，过滤建议列表以仅显示相应的成员： ![Qt 信号的补全](https://resources.jetbrains.com/help/img/idea/2026.3/cl_qt_completion_signals.png) 代码补全同样适用于 `SIGNAL()` 和 `SLOT()` 宏： ![SLOT 宏的补全](https://resources.jetbrains.com/help/img/idea/2026.3/cl_qt_completion_slots.png)

* CLion 的自动导入支持 Qt 风格的头文件，提供最短的 `#include` ： ![Qt 风格的自动导入](https://resources.jetbrains.com/help/img/idea/2026.3/cl_qt_import.png)

## QtCreator 键位图

CLion 捆绑了 [QtCreator 键位图](https://doc.qt.io/qtcreator/creator-keyboard-shortcuts.html)。 您可以在  `设置 | 键位图`  中切换到它，或者通过从主菜单调用  `查看 | 快速切换方案` （ `Ctrl+`` (Windows), `⌃ `` (macOS), `⌃ `` (IntelliJ IDEA Classic (macOS)), `⌃ `` (macOS System Shortcuts), `Ctrl+`` (XWin), `Ctrl+`` (GNOME), `Ctrl+`` (KDE), `Ctrl+`` (Emacs), `Ctrl+`` (Sublime Text), `⌃ `` (Sublime Text (macOS)), `⌃ `` (Xcode), `Ctrl+`` (Visual Studio), `Ctrl+`` (Visual Studio (macOS)), `Ctrl+`` (ReSharper), `Ctrl+`` (ReSharper (macOS)), `Ctrl+`` (QtCreator), `⌃ `` (QtCreator (macOS)), `Ctrl+`` (NetBeans), `Ctrl+`` (Eclipse), `⌃ `` (Eclipse (macOS))）：

![切换到 Qt 键位图](https://resources.jetbrains.com/help/img/idea/2026.3/cl_qt_switch_keymap.png)

## 当前限制

* CLion 跟踪器中的两个总览票据： [Qt 项目支持 (CPP-318)](https://youtrack.jetbrains.com/issue/CPP-318) 和 [Qt 问题 (CPP-1897)](https://youtrack.jetbrains.com/issue/CPP-1897)。

* CLion 的某些代码生成功能可能无法用于 Qt 宏，例如 `Q_PROPERTY` 、 `Q_SIGNAL` 、 `Q_SLOT` 等。

## 故障排查

如果您在 MinGW 上运行时收到  Process finished with exit code -1073741515 (0xC0000135)  错误消息，问题可能与 [Windows 上的 Qt 部署](https://doc.qt.io/qt-5/windows-deployment.html) 有关：动态库和 Qt 插件必须从运行二进制文件的目录中找到。 尝试以下描述的解决方法之一。

Procedure: 选项 1

1. 将路径添加到 Qt 安装中的   MinGW   目录下的  `bin` （例如，  `C:\Qt\5.15.1\mingw81_64\bin` ）到系统  `PATH`  或配置设置的   环境变量   字段中。

如果这不能解决您的项目问题，请尝试   选项 2  。

Procedure: 选项 2

1. 将位于 Qt 安装中   MinGW   目录下的  `bin`  中的  `.dll` -s 复制到您的项目生成文件夹中，默认情况下是  `cmake-build-debug`  或  `cmake-build-release` 。

您最有可能需要的库是  `libstdc++-6.dll` 、  `Qt5Widgets.dll` 、  `Qt5Gui.dll`  和  `Qt5Core.dll` ，但您的设置可能还需要其他库。

2. 在您用于运行的配置设置中，将  `QT_QPA_PLATFORM_PLUGIN_PATH`  环境变量设置为  `plugins\platforms` ，位于   MinGW   目录下：

![Qt 插件路径的环境变量](https://resources.jetbrains.com/help/img/idea/2026.3/cl_qt_envvar_plugins_config.png)

> **Tip:**
> 另一种选择是将  `plugins\platforms`  的内容复制到  `cmake-build-debug(release)/platforms` （确保创建  `platforms`  目录）。

有关更多信息，请参阅 [Qt 插件](https://doc.qt.io/qt-5/windows-deployment.html#qt-plugins)。

## See also

### 快速开始

[快速 CMake 教程](quick-cmake-tutorial.html) [Quick Tutorial on Configuring CLion on Windows](quick-tutorial-on-configuring-clion-on-windows.html)

