跳到主要内容

Qt 开发环境配置

Qt 支持多种开发环境，本文将介绍两种最常用的配置方式：Qt Creator（官方IDE）和 VS Code。

安装 Qt​

方式一：在线安装器（推荐）​

Qt 官方提供在线安装器，可以灵活选择需要的组件：

  1. 下载安装器

  2. 运行安装器

    Windows 下直接运行 .exe 文件，Linux/macOS 需要给文件添加执行权限：

    chmod +x qt-unified-linux-x64-4.x.x-online.run
    ./qt-unified-linux-x64-4.x.x-online.run

  3. 选择组件

    安装过程中需要选择以下关键组件：

    组件说明建议
    Qt 6.x.xQt 库本身选择最新的 LTS 版本（如 6.8.0）
    Qt 5 Compatibility ModuleQt 5 兼容模块需要维护旧代码时选
    Qt Creator官方 IDE推荐安装
    MinGW / MSVCWindows 编译器二选一，MinGW 更轻量
    CMake / Ninja构建工具现代 Qt 项目推荐
    Qt SourcesQt 源码调试时需要

方式二：包管理器安装（Linux）​

Ubuntu/Debian：

# 安装 Qt6 基础开发包
sudo apt update
sudo apt install qt6-base-dev qt6-tools-dev qt6-tools-dev-tools

# 安装 Qt Creator
sudo apt install qtcreator

# 安装额外模块（根据需要）
sudo apt install qt6-multimedia-dev qt6-networkauth-dev

Fedora：

sudo dnf install qt6-qtbase-devel qt6-qttools-devel qt-creator

macOS（使用 Homebrew）：

brew install qt@6
brew install qt-creator

配置 Qt Creator​

Qt Creator 是 Qt 官方提供的集成开发环境，功能完善且开箱即用。

首次启动配置​

  1. 选择编译器

    打开 Qt Creator → 编辑 → 偏好设置 → Kits（套件）：

    • 检查是否自动检测到 Qt 版本
    • 确认编译器配置（GCC/Clang/MSVC）
    • 验证调试器（GDB/LLDB/CDB）

  2. 配置代码风格

    在 C++ → 代码风格中可以选择：

    • Qt 风格（推荐）
    • Google 风格
    • LLVM 风格
    • 自定义风格

创建第一个项目​

  1. 文件 → 新建文件或项目 → Application (Qt) → Qt Widgets Application
  2. 填写项目名称和路径
  3. 选择构建系统（qmake 或 CMake，推荐 CMake）
  4. 选择基类（QMainWindow、QWidget、QDialog）
  5. 完成创建

项目结构说明：

MyFirstApp/
├── CMakeLists.txt      # CMake 构建配置文件
├── main.cpp            # 程序入口
├── mainwindow.cpp      # 主窗口实现
├── mainwindow.h        # 主窗口头文件
└── mainwindow.ui       # UI 设计文件（XML格式）

运行项目​

点击左下角的运行按钮（绿色三角形）或按 Ctrl+R：

  • Debug 模式：包含调试信息，可断点调试
  • Release 模式：优化编译，用于发布

配置 VS Code​

如果你更喜欢 VS Code，也可以通过插件获得良好的 Qt 开发体验。

安装必要插件​

  1. C/C++（Microsoft 官方）- 提供 IntelliSense 和调试支持
  2. CMake Tools - CMake 项目支持
  3. Qt tools - Qt 特定功能支持

配置 CMake 工具链​

在项目根目录创建 .vscode/settings.json：

{
  "cmake.generator": "Ninja",
  "cmake.buildDirectory": "${workspaceFolder}/build",
  "cmake.configureSettings": {
    "CMAKE_PREFIX_PATH": "C:/Qt/6.8.0/mingw_64"
  },
  "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools"
}

注意：根据你的 Qt 安装路径修改 CMAKE_PREFIX_PATH。

配置调试器​

创建 .vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Qt App",
      "type": "cppdbg",
      "request": "launch",
      "program": "${command:cmake.launchTargetPath}",
      "args": [],
      "stopAtEntry": false,
      "cwd": "${workspaceFolder}",
      "environment": [
        {
          "name": "PATH",
          "value": "C:/Qt/6.8.0/mingw_64/bin;${env:PATH}"
        }
      ],
      "MIMode": "gdb",
      "miDebuggerPath": "C:/Qt/Tools/mingw1120_64/bin/gdb.exe"
    }
  ]
}

验证安装​

创建一个简单的测试程序验证环境是否正常：

#include <QApplication>
#include <QLabel>

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    
    QLabel label("Hello, Qt!");
    label.setWindowTitle("My First Qt App");
    label.resize(400, 300);
    label.show();
    
    return app.exec();
}

对应的 CMakeLists.txt：

cmake_minimum_required(VERSION 3.16)
project(HelloQt LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_AUTOMOC ON)

find_package(Qt6 REQUIRED COMPONENTS Core Gui Widgets)

add_executable(HelloQt main.cpp)

target_link_libraries(HelloQt Qt6::Core Qt6::Gui Qt6::Widgets)

如果能正常编译运行并显示窗口，说明环境配置成功。

常见问题​

1. 找不到 Qt 库​

错误信息：Could not find a package configuration file provided by "Qt6"

解决方案：

  • 检查 CMAKE_PREFIX_PATH 是否指向正确的 Qt 安装目录
  • 确保安装了 Qt 的开发组件（不只是运行时）

2. 编译器不匹配​

错误信息：The C++ compiler does not support C++17

解决方案：

  • 升级编译器到支持 C++17 的版本
  • 或修改 CMakeLists.txt 使用较低标准（不推荐）

3. 运行时缺少 DLL​

错误信息：无法找到 Qt6Core.dll 等动态库

解决方案：

  • Windows：将 Qt 的 bin 目录添加到系统 PATH
  • 或使用 Qt 的 windeployqt 工具部署依赖

4. Qt Creator 无法识别 Kit​

解决方案：

  • 工具 → 选项 → Kits → 检查编译器和 Qt 版本配置
  • 手动添加 Qt 版本（指向 qmake 或 Qt6Config.cmake）

下一步​

环境配置完成后，让我们开始编写 第一个 Qt 程序，了解 Qt 项目的基本结构和运行机制。