Qt 配置方法

FreeGuideOnline 最新 2026-07-14

第一步：准备工作——了解你需要什么

在开始配置 Qt 之前，请先明确你的开发目标。Qt 支持多种平台和编译器，选择合适的版本可以避免后续很多麻烦。

  • 桌面应用开发：大多数用户会选择 Qt for Desktop，并使用官方的 Qt Creator IDE。
  • 目标平台：Windows、macOS 或 Linux，本教程以 Windows + MinGW 编译器为例（无需安装庞大的 Visual Studio，开箱即用）。
  • Qt 版本：推荐使用最新的 LTS（长期支持）版本，例如 Qt 6.5 LTS 或 Qt 6.8，稳定且维护时间长。
  • 账户要求：从 Qt 5.15 开始，离线安装包逐步被线上安装器取代，你需要注册一个免费的 Qt 账号才能下载。

提示：如果你需要开发移动端或嵌入式应用，配置步骤会稍有不同，但本教程的在线安装器方法同样适用。

第二步：下载 Qt 在线安装器

Qt 官方提供统一的在线安装器，它会根据你的选择下载并安装所需组件。

  1. 访问 Qt 官网下载页面：https://www.qt.io/download-qt-installer
  2. 根据你的操作系统选择对应的安装器：
    • Windows：选择 .exe 文件（如 qt-unified-windows-x64-4.x.x-online.exe）
    • macOS：选择 .dmg 文件
    • Linux：选择 .run 文件（需要赋予可执行权限）
  3. 下载完成后，不要立即运行。如果你的网络环境不稳定，建议先设置代理或使用更加稳定的网络连接，避免下载中断。

第三步：安装 Qt 与必要组件

运行安装器，按照以下关键步骤执行操作，注意不要盲目点“下一步”。

3.1 登录 Qt 账户

打开安装器后，会提示你登录。使用注册好的 Qt 账号登录。如果没有，可以快速注册一个，完全免费。

3.2 选择安装路径与关联文件

  • 安装路径建议保持默认（如 C:\Qt），或者选择一个没有空格和特殊字符的路径，以避免某些工具链的兼容性问题。
  • 勾选“关联常见的 Qt 文件类型”通常是有用的，可以保留默认。

3.3 选择组件（最关键的一步）

这一屏决定了你最终安装哪些 Qt 库和开发工具。初学者很容易在这里选错，导致安装后无法编译。

Qt 版本选择

展开 Qt 分类，你会看到多个 Qt 版本。对于 Windows 桌面开发，推荐选择 Qt 6.5.3 或 Qt 6.8.x 下面的：

  • MSVC 2019/2022 64-bit：如果你已经安装了 Visual Studio 2019 或 2022，选这个。
  • MinGW 11.2.0 64-bit：纯新手首选。它自带 GCC 编译器和构建工具，无需额外安装任何 IDE 或编译器。
  • Sources：一般不需要勾选，除非你打算阅读源码或重新构建 Qt。
  • Qt Creator：通常会默认勾选最新的版本，保留即可。

如果使用 MSVC，你还需要单独安装 Visual Studio Build Tools 或完整的 Visual Studio。为了简化教程，我们以 MinGW 64-bit 为例进行后续配置。勾选 Qt 6.8.0 → MinGW 11.2.0 64-bit。

Developer and Designer Tools（必需）

展开该分类，确保以下组件被选中（安装器通常会默认勾选）：

  • Qt Creator：主 IDE 和调试器。
  • CMake：Qt6 默认的构建系统，必须安装。即使你后续会用 qmake，也建议安装。
  • Ninja：CMake 推荐的构建工具，同样建议安装。
  • MinGW：选择与上面 Qt 版本匹配的 MinGW 工具链（例如 MinGW 11.2.0 64-bit）。这一点极其重要，因为 Qt 库和编译器必须位数和版本严格匹配。

如果你的系统是 Windows，还建议勾选 Qt Debug Information Files (位于对应 Qt 版本下)，方便出问题时查看详细调用栈。

3.4 同意协议并开始安装

确认所有选择后，点击“下一步”同意许可协议，然后开始安装。根据你的网络速度，这个过程可能需要 30 分钟至 2 小时。确保安装过程中断网保护，不要休眠或关机。

第四步：配置 Qt Creator 并创建第一个工程

安装完成后，启动 Qt Creator。首次运行可能需要进行一些基础配置，IDE 通常会自动检测到已安装的 Qt 版本和编译器。

4.1 检查自动检测的 Kit（构建套件）

Qt Creator 使用“Kit”来组合 Qt 版本、编译器和调试器。

  1. 进入 编辑 → Preferences（Windows 为 Tools → Options）。
  2. 左侧选择 Kits。
  3. 在 Qt Versions 选项卡，确认自动检测到了一项，版本号正确，qmake 路径指向你安装目录下的 bin\qmake.exe（如 C:\Qt\6.8.0\mingw_64\bin\qmake.exe）。
  4. 切换到 编译器 (Compilers) 选项卡，确认 MinGW C++ 编译器（g++）被自动检测到，路径类似 C:\Qt\Tools\mingw1120_64\bin\g++.exe。
  5. 在 Kits 主选项卡，应该能看到一个名为 “Desktop Qt 6.8.0 MinGW 64-bit” 的条目。点选它，右侧的 Qt 版本和编译器是否都已正确关联。如果存在红色警告符号（通常表示编译器或 Qt 版本缺失），需要手动指定。

若工具没有自动检测到，点击 手动添加，定位到相应文件。通常只要第三部安装时选择了对应的 MinGW，就不会有问题。

4.2 创建一个测试项目

  1. 在欢迎界面点击 新建项目。
  2. 选择项目模板：Application (Qt) → Qt Widgets Application，然后点击“选择”。
  3. 输入项目名称和路径，路径中不能含中文和空格，构建系统默认使用 CMake 即可。
  4. 在 Kit Selection 页面，勾选你刚刚确认过的桌面 MinGW Kit，点击下一步。
  5. 类信息保持默认（QMainWindow），版本控制可不选。完成创建。

现在你应该看到一个包含 main.cpp、mainwindow.h、mainwindow.cpp 和 mainwindow.ui 的基础工程结构。

4.3 编译并运行

直接点击左下角的绿色三角形按钮（Run）或按下 Ctrl+R。如果一切配置正确，会出现一个空白的窗口程序。

如果编译失败，请查看 编译输出 窗口末尾的红色错误信息：

  • “No valid kits found”：Kit 没有正确设置，回到 4.1 检查。
  • 找不到’qmake’：Qt 版本路径错误。
  • 编译器内部错误或头文件找不到：通常是 MinGW 路径包含空格、安装被中断文件不全，或 Kit 中编译器选择错误。
  • 运行时提示缺少 DLL：不要直接双击 exe，在 Qt Creator 中运行会自动设置环境变量。如果你希望在文件管理器中运行，需要配置环境变量或使用 windeployqt 工具。

第五步：进阶配置（可选）

当基础示例跑通后，你可以根据需求进行一些增强配置。

5.1 配置 MSVC 编译器 (替代 MinGW)

如果你更喜欢微软的工具链或需要使用某些与 MSVC 绑定的库：

  1. 先安装 Visual Studio 2019/2022，并勾选“使用 C++ 的桌面开发”工作负载。
  2. 在 Qt 维护工具（位于安装目录下）中添加对应 MSVC 版本的 Qt 组件。
  3. Qt Creator 会自动检测到 MSVC 编译器并生成新的 Kit。切换 Kit 即可。

5.2 静态编译与自定义构建选项

通常不需要。若你有减小发布体积或单文件部署的需求，需要重新编译 Qt 源码并进行静态配置，这超出初级教程范围，可参考 Qt 官方文档中的《Building Qt from Source》。

5.3 环境变量配置

如果要在命令行中使用 qmake 或 CMake 直接构建 Qt 项目，需要将以下路径添加到系统 PATH 中（以 MinGW 为例）：

  • C:\Qt\6.8.0\mingw_64\bin（qmake、动态库依赖）
  • C:\Qt\Tools\mingw1120_64\bin（g++、make）
  • C:\Qt\Tools\CMake_64\bin（如果使用 CMake 命令行）

完成后重启终端，输入 qmake --version 应显示版本信息。

常见错误与解决方法

  • 安装过程中网络频繁失败：可以考虑提前下载 Qt 官方提供的离线安装包（部分第三方镜像提供旧版本），或使用科学上网工具连接到稳定的服务器源。
  • Qt Creator 界面乱码/中文显示异常：在 工具→选项→环境 中设置界面语言为 English 可避免，或设置合适的系统区域。
  • 编译通过但程序闪退：在 Qt Creator 的项目中，添加 CONFIG += console (qmake) 或 set(CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS ON) 等仅在需要时使用。更常见的原因是缺少动态库，使用 Qt Creator 调试运行并查看“应用程序输出”窗格。
  • 项目路径或用户名包含中文：这是 Qt(尤其是 Qt5) 上一个经典问题，务必保持全英文路径。

总结

完成以上步骤后，你已经拥有了一个可用的 Qt 桌面开发环境。整个流程的核心在于：

  • 选择与 Qt 版本严格匹配的编译器（MinGW 或 MSVC）
  • 安装时选中对应的 Tools 组件（MinGW 或 CMake）
  • 确保在 Qt Creator 中 Kit 的三个组件（Qt Version、Compiler、Debugger）均正常关联且无警告

至此，你可以开始编写自己的第一个图形界面程序，或继续学习 Qt 的信号槽机制、布局管理器和自定义控件。配置环境是开发路上的第一个小门槛，跨过去之后就会顺畅许多。