安装 Qt：从零开始 – wiki基地

作者： /

安装 Qt：从零开始，迈出你的跨平台开发第一步

欢迎踏上 Qt 开发之旅！如果你正打算使用 Qt 强大的框架来构建令人惊艳的跨平台应用程序，那么安装 Qt 是你迈出的第一步。对于初学者而言，这个过程可能看似复杂，涉及下载、选择组件、配置环境等多个环节。别担心，本文将为你提供一个从零开始、详尽而耐心的安装指南，带你一步步完成 Qt 的安装，并进行基本的验证，确保你顺利启动你的第一个 Qt 项目。

我们将主要聚焦于使用官方提供的在线或离线安装包进行安装，这是对于新手最直接、最推荐的方式。

第一章：认识 Qt 及其安装的必要性

在深入安装细节之前，让我们先简要回顾一下 Qt 是什么，以及为什么需要进行安装。

什么是 Qt？

Qt 是一个强大的跨平台 C++ 图形用户界面应用程序开发框架，但它的能力远不止于此。它提供了一整套丰富的 API，涵盖了从 GUI 界面、网络通信、数据库访问、多媒体处理、XML 解析到国际化等众多领域。使用 Qt，开发者可以使用同一套代码库，轻松地将应用程序部署到 Windows、macOS、Linux、Android、iOS 以及嵌入式系统等多个平台。

为什么需要安装 Qt？

Qt 本身是一系列库文件、头文件、开发工具和文档的集合。你的代码需要引用这些头文件来使用 Qt 提供的类和函数，然后在编译时链接到相应的库文件。此外，为了方便开发，Qt 提供了一个集成开发环境（IDE）叫做 Qt Creator，它集代码编辑、UI 设计、编译、调试等功能于一体。安装 Qt 的过程，本质上就是将这些必要的文件和工具安装到你的计算机上，并进行必要的配置，以便你的开发环境能够找到并使用它们。

对于新手来说，理解以下几个核心概念对于顺利安装和后续开发至关重要：

  • Qt Libraries (库文件): Qt 框架本身的核心，包含各种模块的实现。
  • Qt Headers (头文件): 包含了 Qt 类和函数的声明，你的代码需要包含这些头文件。
  • Qt Creator: Qt 官方推荐的集成开发环境 (IDE)，用于编写、编译、调试 Qt 应用程序。
  • Qt Documentation (文档): 极其重要的资源，包含了 Qt 所有类、函数、工具的使用说明和示例。
  • Compilers (编译器): 你的 C++ 代码需要通过编译器转换成可执行程序。Qt 安装时需要与系统已安装的或随 Qt 一起安装的 C++ 编译器（如 GCC, Clang, MSVC, MinGW）协同工作。
  • Kits (套件): 在 Qt Creator 中，一个 Kit 代表了一个完整的开发环境配置，它将一个特定的 Qt 版本、一个特定的编译器、一个特定的调试器以及其他设置关联起来。你的项目需要选择一个 Kit 来进行构建和运行。

理解这些概念有助于你在安装过程中做出正确的选择，并理解安装后的配置。

第二章：安装前的准备工作

在开始下载和安装之前，请确保你的计算机满足以下条件：

  1. 操作系统: Windows (推荐 Win 10/11 或更高), macOS, 或支持的 Linux 发行版。请确认你的操作系统版本在 Qt 支持的范围内。
  2. 足够的磁盘空间: Qt 安装包和后续的组件可能占用数 GB 到十几 GB 的空间，请确保安装盘有足够的剩余空间。
  3. 稳定的网络连接: 如果使用在线安装器，整个安装过程需要从服务器下载文件，稳定的网络连接至关重要。即使使用离线安装器，部分组件或更新可能仍需要网络。
  4. C++ 编译器: Qt 依赖于 C++ 编译器。根据你使用的操作系统和选择的 Qt 版本，可能需要预先安装或确认系统已安装兼容的 C++ 编译器：
    • Windows: 通常使用 Microsoft Visual C++ (MSVC) 或 MinGW (Minimalist GNU for Windows)。如果你选择 MSVC 版本的 Qt，你需要安装相应版本的 Visual Studio (至少包含 C++ 桌面开发工作负载)。如果你选择 MinGW 版本的 Qt，安装器可能会提供捆绑的 MinGW 编译器，或者你可以选择使用系统已有的 MinGW。
    • macOS: 通常使用 Xcode 自带的 Clang 编译器。安装 Xcode 并同意其许可协议即可获得。
    • Linux: 通常使用 GCC 或 Clang。大多数 Linux 发行版默认安装了 GCC。
    • 重要提示: 选择的 Qt 版本必须与你使用的编译器版本兼容。例如，你不能尝试用旧版本的 GCC 编译针对 MSVC 2019 构建的 Qt 库。官方安装器通常会提供与特定编译器版本绑定的 Qt 版本，或者捆绑推荐的编译器。

确保这些准备工作都已完成，特别是编译器部分，这能避免很多安装后配置的问题。

第三章：获取 Qt 安装包

Qt 的安装包主要通过官方网站提供。你可以选择在线安装器或离线安装器。对于初学者，推荐使用在线安装器，因为它体积较小，并且在安装过程中你可以根据需要选择下载哪些组件。

访问 Qt 官方网站

打开你的浏览器，访问 Qt 的官方网站：https://www.qt.io/

导航到下载页面

在官网上找到“Download”（下载）或类似的链接。通常它位于首页的显眼位置或者菜单栏中。

选择合适的下载选项：Open Source vs. Commercial

Qt 提供开源 (Open Source) 和商业 (Commercial) 两种许可。
* Open Source (开源): 适用于开发遵循 GPL 或 LGPL 协议的免费软件或开源软件。如果你是个人学习或者开发开源项目，通常选择这个选项。需要注意的是，使用开源版本开发闭源商业软件可能违反其许可协议，具体请仔细阅读 LGPL/GPL 协议条款。
* Commercial (商业): 适用于开发闭源商业软件或需要更灵活许可的项目。商业许可需要付费购买。

对于初学者和个人学习用途，请选择下载开源版本。

点击进入开源下载页面。你可能会看到“Download the Qt Online Installer”等按钮。

下载在线安装器

点击下载在线安装器。网站会根据你的操作系统（Windows, macOS, Linux）自动推荐相应的安装器下载。下载的文件名类似 qt-unified-windows-x64-online.exe (Windows), qt-unified-macOS-x64-online.dmg (macOS), 或 qt-unified-linux-x64-online.run (Linux)。

关于离线安装器: 离线安装器包含了所有或大部分组件，下载体积巨大（可能数GB），但安装时不需要网络连接。如果你网络条件很差，或者需要在多台没有网络的机器上安装，可以考虑离线安装器。但其下载链接可能不如在线安装器那么直观，有时需要到特定页面查找。对于第一次安装，在线安装器更为灵活，推荐使用。

下载完成后，你将获得一个可执行文件（或 macOS 上的 DMG 文件）。

第四章：运行在线安装器并进行安装

现在，找到你下载的安装器文件并运行它。以下是跨平台通用的主要步骤，不同操作系统或版本的安装器界面可能略有差异，但核心流程是相似的。

步骤 1: 运行安装器

双击下载的安装器文件。在 Windows 上，可能会弹出用户账户控制（UAC）提示，点击“是”允许运行。在 Linux 上，可能需要先给予执行权限 (chmod +x filename.run) 后再运行 (./filename.run)。

步骤 2: Qt Account 登录或注册

安装器会首先要求你登录或注册 Qt Account。这是使用开源版本 Qt 的必要步骤，用于跟踪使用情况并允许你下载组件。

  • 如果你已经有 Qt Account，输入邮箱和密码登录。
  • 如果你没有 Qt Account，点击“Sign up for a new account”或类似的按钮进行注册。注册过程通常很简单，只需要提供邮箱、设置密码并验证邮箱地址。

完成登录/注册后，点击“Next”。

3. 安装许可协议 (EULA)

仔细阅读 Qt 的许可协议（特别是开源许可的条款）。如果你同意，勾选“I have read and agree to the terms and conditions”并点击“Next”。

4. 选择安装目录

选择 Qt 的安装路径。建议使用一个简单、不包含中文、空格或特殊字符的路径，例如 C:\Qt (Windows), /opt/Qt (Linux/macOS)。避免安装在系统盘的 Program Files (x86) 或 Program Files 目录下，以减少权限问题。记住这个路径，后续配置可能会用到。

点击“Next”。

5. 选择组件（最关键的一步！）

这是安装过程中最重要、也是最容易让新手困惑的步骤。安装器会列出所有可用的 Qt 版本、附加组件和工具。你需要根据自己的需求选择。

Qt 组件通常按 Qt 版本和架构（编译器）组织。例如，你可能会看到：

  • Qt 6.5.3
    • MSVC 2019 64-bit (或其它 MSVC 版本，如 2022)
    • MinGW 8.1.0 64-bit (或其它 MinGW 版本)
    • Android
    • macOS (或 iOS)
    • …
  • Qt 5.15.2 (LTS)
    • MSVC 2019 64-bit
    • MinGW 8.1.0 64-bit
    • …
  • Developer and Designer Tools
    • Qt Creator 10.0.2 (或更新版本)
    • Qt Designer
    • …
  • Additional Libraries (附加库)
    • Qt Charts
    • Qt Data Visualization
    • …
  • Source Code (源代码)
  • Documentation (文档)

对于初学者，以下是推荐的选择指南：

  1. 选择 Qt 版本:

    • 推荐选择一个最新的稳定版本 (如 Qt 6.x 的最新 LTS 或非 LTS 版本) 和/或一个 LTS (长期支持) 版本 (如 Qt 5.15.x)。 最新版本通常有新特性和改进，而 LTS 版本更稳定， bug 修复支持时间长。选择哪个取决于你的具体需求，但对于学习，最新稳定版通常是个不错的开始。
    • 不要一次选择所有版本。 这会占用大量磁盘空间和下载时间。选择一两个你打算使用的版本即可。

  2. 选择架构 (编译器):

    • 这是最容易出错的地方。你需要选择与你系统中已安装或打算安装的 C++ 编译器匹配的 Qt 版本。
      • Windows:
        • 如果你打算使用 Visual Studio，选择对应的 MSVC 版本 (例如 MSVC 2019 64-bit)。确保你已经安装了 Visual Studio 对应版本并勾选了“使用 C++ 的桌面开发”工作负载。
        • 如果你不想安装 Visual Studio，或者更喜欢 MinGW，选择对应的 MinGW 版本 (例如 MinGW 8.1.0 64-bit)。安装器通常会提供一个捆绑的 MinGW 版本，选择这个通常是最简单的，可以省去手动安装 MinGW 的麻烦。
        • 不要同时选择所有架构，尤其不要选择你不了解或不打算使用的架构。
      • macOS: 选择 macOS 架构。你需要先安装 Xcode。
      • Linux: 选择对应的 Linux 架构。你需要先安装 GCC 或 Clang。
    • 总结: 根据你的操作系统和你将使用的 C++ 编译器，只选择对应的 64 位或 32 位架构。对于大多数现代开发，选择 64 位版本。

  3. 选择工具:

    • 强烈建议勾选 Qt Creator。 它是 Qt 开发的核心 IDE，非常方便。
    • Developer and Designer Tools 下的其他工具，如 Qt Designer（用于可视化设计 UI 文件）、Qt Linguist（用于国际化）等，通常也很有用，可以根据需要选择。对于初学者，选择 Qt Creator 通常就足够开始。

  4. 选择文档和源代码:

    • 强烈建议勾选 Documentation。 离线文档在没有网络时查阅非常方便，可以极大地提高学习效率。
    • Source Code (源代码) 对于调试和深入理解 Qt 内部实现非常有帮助，但占用空间较大。初学者可以暂时不选，等后续有需要时再通过安装器或在线获取。

  5. 附加库 (Add-ons): 这些是 Qt 的额外模块，提供特定功能（如图表、3D、网络、数据库驱动等）。根据你的项目需求选择。对于初学者，开始时可以不选，只安装核心模块（选择某个 Qt 版本和架构时，其核心模块会自动被选中）。核心模块包含了基本的 GUI、网络、文件操作等功能，足够开始学习。

示例选择 (Windows 10/11 用户):

  • 勾选 Qt 6.5.3 (或最新稳定版)
    • 勾选 MSVC 2019 64-bit (如果你使用 Visual Studio 2019 或更新版，并安装了 C++ 桌面开发工作负载)
    • 或者 勾选 MinGW 8.1.0 64-bit (如果你不想安装 Visual Studio，或者想使用 MinGW)
  • 勾选 Developer and Designer Tools
    • 勾选 Qt Creator X.Y.Z (通常是最新版本)
  • 勾选 Documentation

请根据你的实际情况（操作系统、编译器偏好）进行选择。

选择完成后，安装器会显示总下载大小和安装所需空间。确认无误后，点击“Next”。

6. 准备安装

安装器会显示一个摘要，列出即将安装的组件和安装路径。确认信息正确后，点击“Install”。

7. 下载和安装过程

安装器会开始下载选定的组件并安装到指定目录。这个过程可能需要一段时间，具体取决于你的网络速度和选择的组件数量。你可以看到下载进度和安装进度。

注意: 在此过程中，不要中断网络连接或强制关闭安装器。

8. 完成安装

安装完成后，安装器会显示完成页面。通常会有一个选项让你立即启动 Qt Creator。你可以选择勾选或取消勾选。

点击“Finish”退出安装器。

第五章：安装后的配置与验证

安装器通常会自动配置好大部分东西，但为了确保一切正常工作并为后续开发打好基础，我们需要进行一些检查和配置。

1. 启动 Qt Creator

从你的应用程序菜单或安装目录中找到并启动 Qt Creator。

首次启动时，Qt Creator 可能会询问你导入设置或同意许可协议。按照提示进行即可。

2. 检查 Kits (套件) 配置

Kits 是 Qt Creator 中一个非常重要的概念。它定义了构建和运行你的项目所需的环境：使用哪个 Qt 版本、哪个编译器、哪个调试器等等。如果 Kit 配置不正确，你将无法编译和运行项目。

在 Qt Creator 中，导航到：
* 菜单栏 -> Tools (工具) -> Options (选项) -> Kits (套件)

在 Kits 页面，你会看到三个主要的 Tab 页：Kits (套件), Qt Versions (Qt 版本), Compilers (编译器), Debuggers (调试器)。

  • Compilers (编译器): 切换到这个 Tab 页。Qt Creator 应该已经检测到了你系统中安装的兼容编译器（如 MSVC, MinGW, GCC, Clang）以及随 Qt 安装器一起安装的编译器。检查列表是否正确。如果没有检测到你期望的编译器，你可以手动点击“Add”并指定编译器的路径。
  • Qt Versions (Qt 版本): 切换到这个 Tab 页。你应该能看到你通过安装器安装的所有 Qt 版本（例如 Qt 6.5.3 (MSVC 2019 64-bit), Qt 5.15.2 (MinGW 8.1.0 64-bit)）。检查路径是否正确指向你的 Qt 安装目录下的对应版本。
  • Debuggers (调试器): 切换到这个 Tab 页。Qt Creator 应该检测到了相应的调试器（如 CDB for MSVC, GDB for MinGW/GCC/Clang）。
  • Kits (套件): 切换回 Kits Tab 页。Qt Creator 应该已经根据检测到的 Qt Versions, Compilers, 和 Debuggers 自动创建了一些 Kits。每个 Kit 都会显示它关联的 Qt 版本、编译器、调试器等信息。

重要: 确保至少有一个有效的 Kit 存在，并且它关联了你安装的 Qt 版本和兼容的编译器/调试器。如果某个 Kit 显示警告或错误（通常是黄色感叹号或红色叉号），说明配置有问题。点击该 Kit，检查其关联的组件是否正确，并修正它们。常见的错误是找不到编译器或调试器。

3. 创建一个简单的测试项目 (“Hello World”)

为了最终验证安装是否成功，我们将创建一个最简单的 Qt GUI 项目并运行它。

  1. 在 Qt Creator 中，选择 菜单栏 -> File (文件) -> New Project (新建项目)。
  2. 在弹出的对话框中，选择 Application (应用程序) -> Qt Widgets Application (Qt Widgets 应用程序)。点击“Choose…”。
  3. 项目位置和名称:
    • Name (名称): 输入项目名称，例如 MyFirstQtApp。
    • Create in (创建于): 选择一个目录来存放你的项目文件。
    • 勾选 Use as default project location (使用为默认项目位置) 可以方便以后创建项目。
    • 点击“Next”。
  4. Define Build System (定义构建系统): 选择 CMake (现代推荐) 或 QMake (传统)。对于新手，两者皆可，CMake 是趋势。点击“Next”。
  5. Choose Kit (选择套件): 这是关键步骤！ 选择你在上一步检查过的那个有效的 Kit。如果你的 Kit 配置正确，这里应该能看到一个绿色的勾。如果你有多个 Kits，选择你打算使用的那个。点击“Next”。
  6. Class Information (类信息): Qt Creator 会为你创建一个主窗口类。使用默认的 MainWindow 类名即可。基类通常是 QMainWindow。勾选 Generate form (生成界面文件)。点击“Next”。
  7. Project Management (项目管理): 使用默认设置。点击“Next”。
  8. Summary (摘要): 确认项目设置。点击“Finish”。

Qt Creator 会自动创建项目文件并在编辑器中打开。

4. 构建并运行测试项目

  1. 在 Qt Creator 左侧的导航栏中，找到项目视图。你可以看到 Forms 文件夹下的 mainwindow.ui (界面文件) 和 Sources 文件夹下的 main.cpp, mainwindow.h, mainwindow.cpp (代码文件)。
  2. 在 Qt Creator 左下角，你会看到几个按钮：Build (构建), Run (运行), Debug (调试)。它们旁边有一个下拉菜单，显示当前选中的 Kit。确保这里显示的是你刚才选择的那个 Kit。
  3. 点击绿色的 Build (构建) 按钮（或菜单栏 Build -> Build Project “MyFirstQtApp”）。观察下方 Output (输出) 窗口的 Compile Output (编译输出) 标签页。如果一切顺利，你应该会看到编译和链接成功的消息，没有错误。
  4. 如果编译成功，点击绿色的 Run (运行) 按钮（或菜单栏 Build -> Run “MyFirstQtApp”）。

此时，你应该看到一个空的桌面窗口弹出，窗口标题是 “MyFirstQtApp”（或你在项目创建时设定的窗口标题）。

恭喜！ 如果你能成功构建并运行这个空白窗口，说明你的 Qt 环境已经基本安装并配置成功了。

第六章：常见问题及故障排除

尽管我们力求提供详细的步骤，但安装过程可能因系统环境差异而遇到各种问题。以下是一些常见问题及其解决方案：

  1. “Cannot find compiler…” 或 Kit 出现红色叉号/黄色警告:

    • 原因: Qt Creator 找不到关联 Kit 所需的编译器。
    • 解决方案:
      • 确保你已经安装了与你选择的 Qt 版本兼容的 C++ 编译器（MSVC, MinGW, GCC, Clang）。
      • 在 Qt Creator 的 Options -> Kits -> Compilers 中，检查是否检测到了正确的编译器。如果没有，点击“Add”手动添加编译器的路径。
      • 在 Kits Tab 页中，编辑有问题的 Kit，确保它关联了正确的 Qt Version, Compiler, 和 Debugger。

  2. 下载组件速度非常慢或中断:

    • 原因: 网络连接不稳定、Qt 服务器负载高或防火墙/代理问题。
    • 解决方案:
      • 检查你的网络连接。
      • 暂停并重新开始下载。
      • 如果你使用了代理，检查 Qt 安装器是否有代理设置选项，或配置系统代理。
      • 考虑换一个时间段进行下载。
      • 如果网络实在不行，可以考虑下载体积巨大的离线安装器（前提是你能找到并下载完成）。

  3. 安装过程中出现权限错误:

    • 原因: 安装目录权限不足。
    • 解决方案:
      • 确保你以管理员身份运行安装器（在 Windows 上右键点击安装器，选择“以管理员身份运行”）。
      • 选择一个非系统目录（如 C:\Qt 或用户目录下的自定义文件夹）作为安装路径，避免 Program Files 等需要较高权限的目录。

  4. 运行测试项目时找不到库文件或出现链接错误:

    • 原因: 环境配置问题，系统找不到 Qt 库。虽然 Qt Creator 构建的项目通常会自动处理路径，但在某些复杂情况下或手动编译时可能出现。
    • 解决方案:
      • 对于 Qt Creator 构建的项目，首先检查 Kits 配置是否正确。
      • 确保你运行的是在 Qt Creator 中构建的可执行文件。
      • 在某些情况下，可能需要将 Qt bin 目录添加到系统的 PATH 环境变量中（例如 C:\Qt\6.x.y\msvcXXXX_64\bin 或 C:\Qt\6.x.y\mingwXXXX_64\bin）。但对于使用 Qt Creator 开发，通常不需要手动修改 PATH。

  5. Qt Creator 无法启动或界面显示异常:

    • 原因: 安装文件损坏、系统兼容性问题或图形驱动问题。
    • 解决方案:
      • 尝试重新启动计算机。
      • 检查你的显卡驱动是否最新。
      • 如果问题持续，考虑卸载 Qt 并重新下载安装器后再次安装。

第七章：接下来做什么？

恭喜你成功安装了 Qt！现在，你的开发环境已经准备就绪。接下来你可以：

  • 探索 Qt Creator: 熟悉它的界面、菜单、快捷键。尝试使用 UI 设计器 (.ui 文件) 拖拽创建界面。
  • 阅读 Qt 文档: 这是学习 Qt 最重要的资源。在你安装的 Qt 版本目录下找到 Docs 文件夹，或者在 Qt Creator 的 Help (帮助) 模式下查阅。从介绍性文章开始，然后深入到你感兴趣的模块（如 Widgets, Layouts, Signals & Slots）。
  • 学习 C++: 如果你还不熟悉 C++，需要花时间学习 C++ 的基础知识，因为 Qt 是一个 C++ 框架。
  • 寻找 Qt 教程和示例: 网上有大量优质的 Qt 教程和示例代码。从简单的 GUI 程序开始，逐步学习如何处理用户输入、事件、布局、文件操作等。Qt 安装包本身也包含了丰富的示例项目，可以在 Qt Creator 中打开和学习。
  • 了解 Qt 的信号与槽机制: 这是 Qt 的核心特性，用于对象之间的通信。理解它是使用 Qt 的关键。

结语

从零开始安装 Qt 可能需要一些耐心，涉及选择正确的组件并确保环境配置正确。通过本文的详细步骤和指南，你应该能够顺利完成安装，并成功运行你的第一个 Qt 应用程序。记住，Qt 是一个功能强大的工具，其广阔的应用领域等待你去探索。不要被起步阶段的复杂性吓倒，一步一个脚印，你将能够利用 Qt 轻松创建出令人印象深刻的跨平台应用程序。祝你开发愉快！

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部