Qt 下载与安装入门 – wiki基地

---

从零开始：Qt 下载与安装超详细入门指南

欢迎踏上跨平台应用开发之旅！Qt，作为一个功能强大、灵活易用的跨平台应用程序开发框架，被广泛应用于桌面应用、嵌入式设备、移动平台等多个领域。它允许开发者使用 C++、QML 等语言，只编写一次代码，即可在 Windows、macOS、Linux、Android、iOS 等不同操作系统上构建出原生体验的应用程序。

对于初学者而言，安装 Qt 是迈入这个精彩世界的第一步。虽然过程可能涉及多个选择和步骤，但请放心，本篇文章将带你一步一步详细完成整个过程，力求让你能够顺利搭建起自己的 Qt 开发环境。我们将覆盖从准备工作、下载安装器、运行安装程序，到最后的验证安装，甚至包括一些常见问题的解决。

让我们开始吧！

引言：为何选择 Qt 以及安装的重要性

在开始安装之前，快速了解一下 Qt 的魅力有助于增强学习的动力。Qt 不仅仅是一个 GUI 库，它是一个全面的开发框架，提供了丰富的模块，涵盖网络通信、数据库访问、XML/JSON 处理、多媒体支持、图形渲染、国际化等等。其“写一次，到处运行”（Write Once, Deploy Everywhere）的理念大大提高了开发效率。

然而，要享受 Qt 带来的便利，首先必须正确地安装它。Qt 的安装过程可能不像某些软件那样简单地一路“下一步”，因为它需要你根据自己的需求选择不同的版本、组件甚至编译器。正确的安装是后续学习和开发的基础，错误的配置可能导致项目无法构建、运行，甚至出现各种奇怪的错误。因此，请务必仔细阅读并按照以下步骤进行。

第一章：准备工作——确保你已万事俱备

在点击任何下载链接之前，做一些前期的准备可以避免很多不必要的麻烦。

1.1 了解你的操作系统

Qt 是一款跨平台框架，但安装过程会针对不同的操作系统有所区别（主要是针对编译环境的配置）。你需要明确知道你正在使用的操作系统及其版本。

• Windows: 需要知道是 Windows 10 或更高版本。在 Windows 上安装 Qt，你通常需要选择一个 C++ 编译器，常见的有 MinGW 和 MSVC（Microsoft Visual C++）。Qt 官方安装器通常会提供 MinGW 的选项，对于初学者来说这可能是最方便的选择，因为它通常是与 Qt 一起安装的。如果选择 MSVC，则需要确保你的系统已经安装了相应版本的 Visual Studio (包括 C++ 开发工作负载) 或 Visual C++ Build Tools。
• macOS: 需要知道你的 macOS 版本。在 macOS 上，通常使用 Clang 编译器，它是 Xcode 开发工具的一部分。在安装 Qt 之前，建议先安装 Xcode 或者至少是 Xcode Command Line Tools (xcode-select --install)，以确保系统中存在 Clang 编译器和必要的开发工具链。
• Linux: Linux 发行版众多（如 Ubuntu, Fedora, Debian, Arch Linux 等）。在 Linux 上，通常使用 GCC 或 Clang 编译器。在安装 Qt 之前，你需要确保你的系统已经安装了 C++ 开发环境，包括 GCC/G++ 或 Clang/Clang++ 编译器以及相关的构建工具（如 make、gdb 等）。这些通常可以通过你的发行版的包管理器安装，例如在 Ubuntu 上可以使用 sudo apt update && sudo apt install build-essential gdb。

1.2 检查硬件要求

Qt 本身对硬件的要求并不苛刻，但一个流畅的开发环境需要足够的内存（建议 8GB 或以上，16GB 更佳）和硬盘空间。Qt 的安装包和组件可能比较大，尤其是当你选择安装多个版本和组件时。预留至少 10-20 GB 的空闲硬盘空间是比较稳妥的。

1.3 确保网络连接稳定

Qt 官方推荐使用在线安装器。这意味着在安装过程中，安装程序会实时从网络下载所需的文件。因此，一个稳定且速度较快的网络连接至关重要。如果你的网络环境不稳定，可能会导致下载中断、安装失败等问题。如果网络条件实在太差，可以考虑寻找离线安装包（但离线包更新较慢，且获取可能不如在线方便）。

1.4 了解 Qt 的许可协议

Qt 提供了商业许可和开源许可。对于个人学习、开发开源项目或评估用途，通常可以选择开源许可（LGPL 或 GPL）。如果你计划开发闭源的商业软件并进行分发，则需要购买商业许可。在安装过程中，你需要选择相应的许可类型并同意条款。请务必阅读并理解你所选择许可的条款，以确保合法合规使用 Qt。初学者通常从开源版本开始。

1.5 创建 Qt 账户 (推荐)

使用在线安装器通常需要登录 Qt 账户。即使你是使用开源许可，也建议注册一个免费账户。这有助于安装器跟踪你的安装进度，并在需要时提供许可证信息（对于商业用户而言）。访问 https://account.qt.io/register 进行注册。

第二章：获取 Qt 安装器

准备工作完成后，下一步是前往 Qt 官方网站下载安装器。

2.1 访问 Qt 官方网站

打开你的网页浏览器，输入 Qt 官方网站地址：https://www.qt.io/

2.2 寻找下载页面

在官网首页，通常会有一个明显的“Download”或“Downloads”按钮或链接。点击进入下载页面。

2.3 选择适合你的安装器

在下载页面，你会看到不同的下载选项。

• Qt for Open Source (开源版本): 如果你是个人学习、开发开源项目或进行评估，请选择这个选项。找到对应你操作系统的“Download the Qt Online Installer”链接。这是最常见也是官方推荐的下载方式。
• Qt for Commercial Use (商业版本): 如果你已经购买了商业许可，请选择这个选项。通常需要登录你的商业账户来获取相应的安装包或许可证文件。

对于绝大多数初学者，选择“Qt for Open Source”下的在线安装器是正确的选择。点击下载链接，下载对应你操作系统的安装程序文件（例如：qt-unified-windows-x64-online.exe for Windows, qt-unified-macOS-x64-online.dmg for macOS, qt-unified-linux-x64-online.run for Linux）。

下载完成后，你就拥有了启动 Qt 安装过程的钥匙。

第三章：运行 Qt 安装程序——一步步详细指引

这是安装过程中最关键的部分，我们将详细分解每一步。注意：安装过程中的界面可能随 Qt 版本更新略有变化，但整体流程和需要选择的选项是类似的。

3.1 启动安装器

找到你下载的安装器文件，双击运行它。

• Windows: 可能需要管理员权限，点击“是”允许程序运行。
• macOS: 双击 .dmg 文件会挂载一个虚拟磁盘，里面有安装器应用程序，将应用程序拖到“Applications”文件夹或直接双击运行。
• Linux: 需要给.run文件执行权限。打开终端，导航到文件所在目录，运行 chmod +x qt-unified-linux-x64-online.run，然后运行 ./qt-unified-linux-x64-online.run。可能需要输入管理员密码。

安装器启动后，会首先进行一些初始化和自解压过程。请耐心等待。

3.2 Qt Account 登录

安装器会要求你登录你的 Qt 账户。输入你在第一章末尾创建或已有的 Qt 账户的邮箱和密码，然后点击“Next”（下一步）。

• 注意: 如果你是第一次安装或在新的设备上安装，即使是开源版本也通常需要登录。这是为了确认你正在以开源许可条款使用 Qt。如果你之前没有创建账户，通常也会有注册的选项。

3.3 Welcome 和 Introduction

登录成功后，通常会看到欢迎界面和关于 Qt 的一些介绍信息。点击“Next”继续。

3.4 Configuration of Installation (配置安装) – 核心步骤！

这是整个安装过程中最重要、最需要仔细选择的步骤。安装器会让你选择要安装的组件。这里有很多选项，选择正确的组件是确保后续开发环境可用的关键。

界面上通常会有一个树状结构，包含不同版本的 Qt 和各种工具。

3.4.1 选择 Qt 版本

• 在组件列表中，你会看到不同主要版本的 Qt (如 Qt 6.x.x, Qt 5.x.x)。每个主要版本下又包含不同的子版本。
• 推荐: 对于初学者，建议选择一个 LTS (长期支持) 版本。LTS 版本稳定性高，支持周期长，文档和社区资源相对丰富。例如，Qt 6.5 LTS 或最新的 Qt 6.6 LTS (如果可用)。避免选择一些标记为“Preview”或“Alpha/Beta”的版本，它们可能不稳定。
• 点击你想要安装的 Qt 版本旁边的复选框。展开该版本，你会看到更详细的组件选项。

3.4.2 选择编译器 (Compilers)

这可能是让初学者最困惑的部分。Qt 本身是框架和库，它需要一个 C++ 编译器来将你的 C++ 代码编译成可执行程序。你选择的编译器必须与你安装的 Qt 版本“匹配”，才能正确构建项目（这种匹配关系在 Qt Creator 中被称为“Kit”）。

在展开的 Qt 版本下，你会看到针对不同编译器和架构的选项。例如：

• Windows:
  • MinGW x.y.z 64-bit: 如果你没有安装 Visual Studio，或者希望使用一个与 Qt 集成度较高的轻量级编译器，选择这个。Qt 安装器通常会帮你安装这个 MinGW 环境。这是初学者在 Windows 上使用开源 Qt 的常见且方便的选择。
  • MSVC 20xx 64-bit: 如果你已经安装了 Visual Studio 20xx 版本，并且希望使用 MSVC 编译器来构建 Qt 应用，选择这个。请确保你安装的 Visual Studio 版本包含“Desktop development with C++”工作负载。选择此项后，Qt 安装器不会安装编译器本身，而是配置 Qt 以使用你系统中已有的 MSVC 编译器。
• macOS:
  • macOS (基于 Clang): 这是 macOS 上的标准选项，通常与 Xcode 提供的 Clang 编译器配合使用。
• Linux:
  • GCC 64-bit: 这是 Linux 上的标准选项，与系统中已安装的 GCC 编译器配合使用。
  • Clang 64-bit: 如果你更喜欢使用 Clang，并且系统中已安装，可以选择这个。

重要建议:
* Windows 初学者: 如果你没有特别的需求，并且是开源用户，强烈推荐选择 MinGW 选项。安装器会帮你搞定编译器，省去很多麻烦。
* 所有平台: 确保你选择的 Qt 版本至少有一个与你系统中已安装或由 Qt 安装器安装的编译器对应的组件。例如，如果你在 Windows 上选择了 Qt 6.6.0 版本，那么在其下方你至少需要勾选 MinGW 11.2.0 64-bit 或 MSVC 2019 64-bit 等其中一个编译器选项。通常，选择一个最新或推荐的即可。

3.4.3 选择开发工具 (Developer and Designer Tools)

在组件列表的独立区域，或者在某个特定版本下（取决于安装器版本），你会看到工具选项。

• Qt Creator x.y.z: 必选！这是 Qt 官方的集成开发环境 (IDE)，用于编写代码、设计界面、构建和调试项目。没有它，开发会非常不便。
• CMake x.y.z: 一个流行的跨平台构建系统，Qt 6 及其后续版本主要使用 CMake 进行项目构建。虽然 Qt Creator 通常会集成，但勾选它可以确保安装一个可用的版本。
• Ninja x.y.z: 另一个快速的构建系统，有时与 CMake 结合使用。
• Debugging Tools: 包含调试器（如 CDB for Windows, GDB for Linux/macOS）。建议勾选，方便后续调试程序。
• Documentation: 强烈推荐！ 安装 Qt 文档。离线文档非常方便，包含了 Qt 所有类、函数、模块的详细说明和示例。没有文档，学习 Qt 会非常困难。
• Examples: 强烈推荐！ 安装 Qt 提供的示例代码。这些示例涵盖了 Qt 的各种功能和用法，是学习 Qt 的宝贵资源。

必选组件总结: 对于初学者，请务必勾选：你选择的 Qt 版本 (至少一个与你的系统/编译器匹配的组件)、Qt Creator、Documentation 和 Examples。

3.4.4 选择附加库和工具 (Add-on Modules)

在 Qt 版本下，你可能还会看到一些可选的附加模块，如 Charts, Data Visualization, Multimedia, Network, Database, etc. 这些模块提供了 Qt 核心功能之外的特定功能。

• 建议: 初学者可以暂时不勾选这些附加模块，只安装核心的 GUI 和常用模块（通常在你选择了某个 Qt 版本后，核心模块会自动被包含或无法取消勾选）。这可以减少下载量和安装时间。等你后续需要用到特定功能时，可以再次运行安装器，选择“Add or remove components”来添加这些模块。

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

3.5 Installation Folder (安装目录)

选择 Qt 的安装路径。

• 建议: 使用默认路径通常是最好的选择，除非你有特定的分区或权限需求。默认路径通常是 C:\Qt (Windows), /Users/YourUsername/Qt (macOS), /opt/Qt 或 ~/Qt (Linux)。
• 确保所选目录有足够的空间（参考前面预留的硬盘空间）。
• 避免路径中包含中文、空格或特殊字符，这在某些编译工具链中可能引起问题。

选择好路径后，点击“Next”。

3.6 License Agreement (许可协议)

仔细阅读你选择的许可协议（开源或商业）。如果你同意条款，勾选“I have read and agree to the terms contained in the License Agreements”或类似的复选框。

• 注意: 如果选择开源许可，你需要遵守 LGPL v3 或 GPL v3 的条款。简单来说，LGPL 允许你在闭源商业软件中使用 Qt，但你需要遵守一些义务（比如动态链接 Qt 库，并提供修改 Qt 库源代码的权利）。GPL 则要求你的整个项目也必须开源。请根据你的项目性质选择合适的许可。

同意协议后，点击“Next”。

3.7 Start Menu Shortcuts (启动菜单快捷方式)

（Windows 特有）选择是否在开始菜单创建快捷方式。通常保持默认即可。点击“Next”。

3.8 Ready to Install (准备安装)

安装器会显示一个摘要，列出你选择的组件、安装路径等信息。这是最后一次确认的机会。如果发现任何问题，可以点击“Back”返回修改。

确认信息无误后，点击“Install”（安装）。

3.9 Installation Process (安装过程)

安装器现在开始下载和安装你选择的组件。这个过程可能需要一些时间，具体取决于你的网络速度和选择的组件数量。

• 界面上会显示下载进度和安装进度。
• 请保持网络连接稳定，不要中断安装器。
• 如果下载过程中断，有些安装器允许你稍后恢复，但有时可能需要重新运行安装器。

请耐心等待直到安装完成。

3.10 Installation Complete (安装完成)

安装完成后，你会看到一个完成界面。通常会有选项让你立即启动 Qt Creator 或查看 ReadMe 文件。

• 推荐: 勾选“Launch Qt Creator”并点击“Finish”。这将立即打开 Qt IDE，方便你进行下一步的验证。

恭喜！Qt 框架和开发环境的核心部分应该已经成功安装到你的计算机上了。

第四章：验证安装和迈出第一步

安装完成后，最重要的事情是验证它是否真正可用，并了解如何开始使用 Qt Creator。

4.1 启动 Qt Creator

如果你在安装完成界面勾选了启动 Qt Creator，它现在应该正在打开。如果没有，请通过你的操作系统菜单（Windows Start Menu, macOS Applications, Linux Application Menu）找到并启动 Qt Creator。

第一次启动 Qt Creator 时，它可能需要一些时间来初始化和检测系统中的工具链。

4.2 理解 Kits (工具套件)

在 Qt Creator 中，一个非常重要的概念是 Kit (工具套件)。一个 Kit 定义了构建和运行一个 Qt 项目所需的所有元素：

• 一个特定的 Qt 版本
• 一个 C++ 编译器
• 一个 调试器
• 一个 构建系统 (如 Make 或 CMake)
• 运行环境 (如设备类型)

Qt Creator 在启动时会尝试自动检测系统中已安装的 Qt 版本和编译器，并自动配置 Kits。

你可以通过菜单 “Tools” -> “Options” -> “Kits” (或类似路径，取决于版本) 来查看和管理你的 Kits。

• 在一个成功的 Qt 安装后，你应该能在这里看到一个或多个 Qt 版本被检测到，并且至少有一个有效的 Kit 被配置好（Kit 名称旁边有一个绿色的对勾）。
• 检查 Kit 中关联的 Qt Version、Compiler 和 Debugger 是否正确指向你安装的组件。

如果 Kit 没有被自动检测或配置，或者显示警告/错误（例如“No compiler set”），这表明安装可能存在问题，或者 Qt Creator 没有找到必要的工具。解决 Kit 问题通常是安装后最常见的配置步骤，我们将在下一章的故障排除中简要提及。

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

验证安装最直接的方式是创建一个简单的项目并尝试构建运行它。

1. 在 Qt Creator 欢迎界面或通过菜单 “File” -> “New Project”。
2. 选择项目模板。对于初学者，最简单的验证是创建一个 “Application” -> “Qt Widgets Application” (用于桌面 GUI 应用) 或 “Application” -> “Qt Console Application” (用于非 GUI 控制台应用)。选择其中一个，点击“Choose”。
3. 输入项目名称 (如 HelloWorld) 和项目存储路径。点击“Next”。
4. 选择 Kit。在这一步，你需要选择一个有效的 Kit 来构建你的项目。选择你在 4.2 步骤中确认有效的 Kit。点击“Next”。
5. 后续步骤通常是配置类名、UI 文件等。对于简单的测试，使用默认设置，一路点击“Next”直到“Finish”。
6. Qt Creator 会生成项目文件并打开编辑器。对于 Widgets 应用，你会看到一个主窗口类和一个 .ui 文件。对于 Console 应用，你会看到一个 main.cpp 文件。

4.4 构建并运行项目

1. 在 Qt Creator 界面的左侧或底部，找到“Build”或“Run”按钮。通常是一个锤子图标（构建）和绿色三角形图标（运行）。
2. 点击锤子图标 (Build)。Qt Creator 会使用你选定的 Kit 中的编译器和构建系统来编译你的项目。在下方的“Build Output”窗口中，你应该能看到编译过程的输出。如果构建成功，最后会显示“构建成功”或类似的提示。
3. 如果构建成功，点击绿色三角形图标 (Run)。你的应用程序应该会启动。
   • 对于 Widgets 应用，应该弹出一个简单的窗口。
   • 对于 Console 应用，应该在 Qt Creator 的“Application Output”窗口或一个新的终端窗口中看到控制台输出（如果你的代码有输出）。

如果你的项目成功构建并运行，那么恭喜你，Qt 开发环境已经成功搭建完毕！

第五章：常见问题与故障排除

尽管我们力求详细，但在安装过程中仍可能遇到问题。以下是一些常见问题及其可能的解决方案。

5.1 安装过程 stuck 或 failed (卡住或失败)

• 网络问题: 大部分在线安装问题是由于网络不稳定或中断引起的。检查你的网络连接。尝试暂停和恢复下载。如果频繁失败，考虑在网络较好的时段重新尝试，或者寻找离线安装包（如果可用）。
• 防火墙或代理: 你的防火墙或代理设置可能阻止安装器连接到 Qt 的服务器。尝试暂时禁用防火墙或配置安装器使用代理。
• 磁盘空间不足: 检查你选择的安装目录是否有足够的空闲空间。
• 管理员权限: 确保安装器是以管理员权限运行的。
• 安装器本身问题: 极少数情况下，下载的安装器文件可能损坏。尝试重新下载安装器。

5.2 Qt Creator 中“Kit is not configured”或 Kit 显示错误

这是最常见的安装后问题。

• 原因: Qt Creator 没有找到可用的编译器或 Qt 版本与编译器不匹配。
• 解决方案:
  1. 检查编译器: 确保你系统中已经安装了你选择的编译器（如果你选的是 MSVC/GCC/Clang），或者 Qt 安装器成功安装了 MinGW (如果你选的是 MinGW)。
  2. 检查 Qt 版本: 在 Qt Creator 的“Tools” -> “Options” -> “Kits” -> “Qt Versions” 中，确保你安装的 Qt 版本已经被正确检测到。如果没有，点击“Add”手动指定 Qt 安装目录下的 qmake 可执行文件路径（例如 C:\Qt\6.6.0\mingw_64\bin\qmake.exe）。
  3. 检查 Compilers: 在“Tools” -> “Options” -> “Kits” -> “Compilers” 中，确保你的编译器被正确检测到。如果没有，点击“Add”手动添加。
  4. 配置 Kit: 在“Tools” -> “Options” -> “Kits” 中，检查现有的 Kits 或点击“Add”创建一个新的 Kit。在一个 Kit 中，你需要正确关联“Qt Version”、“Compiler”、“Debugger”等。如果 Qt Creator 自动创建的 Kit 有问题，尝试删除它并手动创建一个。确保你选择的 Qt 版本和编译器是相互兼容的。
  5. 重启 Qt Creator: 有时重启 IDE 可以解决检测问题。

5.3 “Compiler path not set” 或类似错误

• 原因: Qt Creator 或构建系统找不到你的编译器可执行文件。
• 解决方案:
  • 如果你使用 MSVC，确保你在运行 Qt Creator 的环境中运行了 Visual Studio 的环境配置脚本（例如 vcvarsall.bat），或者确保 Qt Creator 知道 MSVC 的安装路径。
  • 如果你使用 GCC/Clang，确保它们的可执行文件路径在系统的 PATH 环境变量中，或者在 Qt Creator 的 Compiler 设置中指定了正确的路径。
  • 如果你使用 Qt 安装器安装的 MinGW，理论上 Qt Creator 应该能自动找到。如果不行，检查 MinGW 是否成功安装，并在 Qt Creator 中手动指定其路径。

5.4 Licensing Issues (许可证问题)

• 如果你选择了开源版本但安装器提示许可证问题，确保你登录了 Qt 账户，并且你的网络允许连接到 Qt 的许可证服务器。
• 如果你是商业用户，确保你登录了正确的商业账户，并且许可证文件已正确应用。

5.5 防火墙阻止程序运行

在 Windows 上，首次运行使用新编译器构建的 Qt 应用程序时，防火墙可能会弹出警告。允许该应用程序通过防火墙即可。

如果遇到其他问题，最有效的办法是：

1. 仔细阅读错误信息。错误信息通常会提供线索。
2. 查阅 Qt 官方文档和社区论坛。很多问题都已经有人遇到并解决了。
3. 在搜索引擎中搜索具体的错误信息。

第六章：安装完成后——迈向 Qt 开发

成功安装并验证了你的 Qt 环境后，你已经准备好开始学习和使用 Qt 进行开发了！

• 探索 Qt Creator: 花一些时间熟悉 Qt Creator 的界面和功能。了解如何创建、打开、编辑、构建、运行和调试项目。学习如何使用 Qt Designer 设计 UI 界面。
• 查阅文档: Qt 官方文档是学习 Qt 最好的资源。利用你在安装时勾选的离线文档（在 Qt Creator 中按 F1 即可快速查阅），或者访问 https://doc.qt.io/。从“Getting Started”或你感兴趣的模块开始。
• 研究示例: 运行和阅读安装时勾选的示例项目。这些示例覆盖了 Qt 的各种特性，是学习实际用法的极佳途径。你可以在 Qt Creator 的欢迎界面找到“Examples”或通过菜单“Help”->“Examples”。
• 学习 C++: 如果你对 C++ 不熟悉，建议花时间学习 C++ 基础。Qt 大部分核心功能是基于 C++ 的。
• 学习 QML (可选): Qt 还支持 QML 语言，用于创建动态、流畅的用户界面，尤其适合移动和嵌入式设备。如果你对现代 UI 开发感兴趣，可以学习 QML。
• 参与社区: 加入 Qt 开发者社区、论坛、邮件列表或社交媒体群组。在遇到问题时寻求帮助，也学习他人的经验。

结论

Qt 的下载和安装是开启跨平台应用开发之旅的第一步。虽然过程可能涉及一些选择和配置，但通过本篇文章的详细指引，相信你已经能够顺利完成环境搭建。请记住，选择正确的版本、编译器和必要的组件是确保安装成功的关键。安装完成后，不要忘记验证环境并立即开始动手实践，这是掌握 Qt 的不二法门。

祝你在使用 Qt 进行开发的道路上一切顺利！