Qt5 项目的构建与部署详细讲解

个人博客：blogs.wurp.top

第一部分：项目构建

Qt5 项目主要可以使用两种构建系统：qmake 和 CMake。qmake 是 Qt 自家传统且紧密集成的工具，而 CMake 是一个更现代、更通用的跨平台构建系统，Qt 官方从 Qt6 开始也大力推荐使用 CMake。

1. 使用 qmake 构建

qmake 使用 .pro 文件来定义项目。

一个基础的 *.pro 文件结构：

# 指定所需的模块。core 和 gui 是基础，widgets 用于传统桌面UI。
QT       += core gui widgets# 如果目标程序版本大于 4，我们需要添加 widgets 模块（如上所示），在 Qt5 中通常需要。
greaterThan(QT_MAJOR_VERSION, 4): QT += widgets# 指定目标文件的名称：生成的可执行文件名为 MyApp
TARGET = MyApp# 指定构建类型：app 表示应用程序，lib 表示库
TEMPLATE = app# 指定编译的语言标准（C++11 或更高版本）
CONFIG += c++11# 指定源代码文件
SOURCES += \main.cpp \mainwindow.cpp# 指定头文件
HEADERS += \mainwindow.h# 指定UI文件（由Qt Designer创建）
FORMS += \mainwindow.ui# 指定资源文件（如图标、翻译文件等）
RESOURCES += \resources.qrc# 平台特定的设置
win32 {# Windows 平台特有的设置，例如链接某个库LIBS += -lOpengl32
}unix:!macx {# Linux 平台特有的设置LIBS += -lGL
}macx {# macOS 平台特有的设置
}

构建步骤：

1. 生成 Makefile：在项目根目录（包含 .pro 文件的目录）打开终端/命令行。

   qmake
   

   这条命令会读取 .pro 文件并生成一个与你的编译器和平台对应的 Makefile。

2. 执行编译：

   make           # 在 Linux/macOS 上使用 make
   # 或者
   nmake          # 在 Windows 上使用 Visual Studio 编译器时使用 nmake
   # 或者
   mingw32-make   # 在 Windows 上使用 MinGW 编译器时使用 mingw32-make
   

   这一步会调用编译器，编译源代码并链接生成最终的可执行文件（如 MyApp.exe 或 MyApp）。

3. (可选) 清理构建：

   make clean     # 清理生成的对象文件和目标程序，但保留 Makefile
   # 或者
   make distclean # 彻底清理，包括 Makefile（需要重新运行 qmake）
   

2. 使用 CMake 构建

CMake 使用 CMakeLists.txt 文件，它更灵活，功能也更强大。

一个基础的 CMakeLists.txt 文件结构：

# 指定所需的 CMake 最低版本
cmake_minimum_required(VERSION 3.16)# 设置项目名称
project(MyApp VERSION 1.0 LANGUAGES CXX)# 设置 C++ 标准
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)# 自动处理 UI、资源文件等 (MOC, UIC, RCC)
set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTOUIC ON)
set(CMAKE_AUTORCC ON)# 查找所需的 Qt 库
find_package(Qt5 REQUIRED COMPONENTS Core Widgets)# 如果你的程序需要网络、多媒体等功能，在这里添加
# find_package(Qt5 REQUIRED COMPONENTS Core Widgets Network Multimedia)# 添加可执行文件目标，并指定源文件
add_executable(MyAppmain.cppmainwindow.cppmainwindow.hmainwindow.uiresources.qrc # 直接包含资源文件
)# 将找到的 Qt 库链接到你的可执行文件
target_link_libraries(MyApp Qt5::Core Qt5::Widgets)# (可选) 设置可执行文件的输出目录
# set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)

构建步骤（通常采用 Out-of-Source Build，即外部构建）：

1. 创建构建目录并进入：

   mkdir build
   cd build
   

2. 运行 CMake 生成构建系统文件：

   # .. 表示上一级目录，即 CMakeLists.txt 所在的位置
   cmake .. -G "Your Generator"
   

   -G 用于指定生成器，通常可以省略，CMake 会自动选择。常见生成器：

   • Unix/Linux/macOS: 默认生成 Unix Makefiles，只需 cmake ..
   • Windows (Visual Studio): -G "Visual Studio 16 2019" (版本号根据你的VS版本变化)
   • Windows (MinGW): -G "MinGW Makefiles"

3. 执行编译：

   cmake --build .  # 通用命令，CMake 会调用底层的构建工具（make, nmake, msbuild等）
   # 或者直接使用底层工具
   make             # 对于 Makefiles
   # 或者
   msbuild MyApp.sln # 对于 Visual Studio
   

---

第二部分：项目部署

部署意味着让你的程序可以在没有安装 Qt 开发环境的机器上运行。核心问题是处理程序所依赖的 Qt 运行时库和插件。

1. Windows 部署

方法一：使用 windeployqt 工具（官方推荐，最常用）

windeployqt 是 Qt 安装时自带的一个命令行工具，它能自动分析你的可执行文件，并将其依赖的所有 Qt 库、插件和翻译文件复制到该可执行文件所在的目录。

步骤：

1. 使用 Release 模式编译你的项目（CONFIG += release in .pro，或在 CMake 中设置 -DCMAKE_BUILD_TYPE=Release）。
2. 在编译输出的目录（包含你的 *.exe 文件的 release/ 或 bin/ 目录）打开 Qt 命令行（开始菜单中的 “Qt 5.15.2 (MinGW 7.3.0 64-bit)” 或类似的），或者确保你的普通命令行能找到 windeployqt.exe（它在 Qt 安装目录的 bin 文件夹下）。
3. 运行命令：

   windeployqt --compiler-runtime MyApp.exe
   

   • --compiler-runtime 选项会同时打包 VC++ Redistributable 的运行库（如果你用的是 MSVC 编译器），这非常有用。
   • 工具会自动填充所有必要的 .dll 文件、plugins 文件夹（如 platforms/qwindows.dll）和 translations 文件夹。

现在，整个文件夹就可以打包分发了。你可以双击 MyApp.exe 测试是否能够独立运行。

方法二：手动复制（不推荐，用于理解或调试）

1. 将你的 MyApp.exe 复制到一个空文件夹。
2. 运行它，你会看到类似 无法找到 Qt5Core.dll 的错误。
3. 根据错误提示，从 Qt安装目录/5.15.2/msvc2019_64/bin/（你的路径会不同）找到对应的 .dll 文件并复制过来。
4. 最重要的是，需要复制 平台插件。创建一个 platforms 文件夹，并将 qt安装目录/plugins/platforms/qwindows.dll 复制过来。
5. 如果程序使用了图片（jpeg, png）、数据库等功能，还需要复制相应的插件（imageformats, sqldrivers 等目录）。

2. Linux 部署

Linux 部署相对复杂，因为系统本身可能已安装部分 Qt 库，但版本可能不匹配。

方法一：使用 linuxdeployqt（推荐）

linuxdeployqt 是一个类似 windeployqt 的第三方工具，它可以打包 AppImage。

1. 从 GitHub 下载 linuxdeployqt-continuous-x86_64.AppImage。
2. 给你的可执行文件设置 AppDir 结构：

   mkdir -p MyApp.AppDir/usr/bin
   mkdir -p MyApp.AppDir/usr/lib
   mkdir -p MyApp.AppDir/usr/share/applications
   cp MyApp MyApp.AppDir/usr/bin/
   # 创建 .desktop 文件
   # 复制图标等
   

3. 运行 linuxdeployqt：

   ./linuxdeployqt-continuous-x86_64.AppImage MyApp.AppDir/usr/bin/MyApp -appimage
   

   它会自动收集依赖并生成一个可自包含的 MyApp-x86_64.AppImage 文件。

方法二：静态编译（最干净，但最复杂）

你需要从源码静态编译整个 Qt 库，然后用这个静态版的 Qt 来编译你的程序。这样生成的可执行文件几乎不依赖外部动态库，但体积巨大，且需要遵守 Qt 的许可证（LGPL 协议的约束）。

方法三：使用包管理器分发（如 Snap, Flatpak）

这些是更现代的 Linux 软件分发方式，它们将程序及其所有依赖打包在一个沙盒环境中，解决了依赖问题。

3. macOS 部署

使用 macdeployqt 工具

macOS 的部署体验是最好的，macdeployqt 会帮你创建一个完美的 .app 捆绑包（Bundle）甚至 .dmg 磁盘映像。

步骤：

1. 在 Release 模式下编译你的程序，你会得到 MyApp.app。
2. 在终端运行：

   macdeployqt MyApp.app -dmg
   

3. 这个命令会：
   • 将所需的 Qt 框架复制到 MyApp.app/Contents/Frameworks/ 目录。
   • 修正这些框架的安装名称（install_name）和路径，使其指向应用程序包内部。
   • （使用 -dmg 参数时）最终创建一个整洁的 MyApp.dmg 文件，用于分发。

---

总结与建议

任务	工具/方法	说明
构建 (qmake)	qmake && make	Qt传统方式，简单直接，适合小型或传统项目。
构建 (CMake)	cmake && cmake --build .	现代方式，功能强大，是未来的趋势，适合新项目和复杂项目。
部署 (Windows)	windeployqt	首选。自动化程度高，几乎一键完成。
部署 (Linux)	linuxdeployqt	生成 AppImage，是相对简单的分发方式。
部署 (macOS)	macdeployqt	首选。完美创建 .app 和 .dmg。

通用部署检查工具：

• Windows: Dependency Walker (depends.exe) 或 ldd (MinGW) 可以查看可执行文件的依赖。
• Linux: ldd MyApp 命令可以列出程序依赖的所有动态库。
• macOS: otool -L MyApp.app/Contents/MacOS/MyApp 可以查看依赖的框架。