Qt5

Qt 5.15 Windows 静态编译（支持 VS2022）

本文记录了 Qt 5.15.x 在 Windows 上静态编译（Static Build） 的完整过程，包括：

源码下载
编译环境准备
使用 MSVC（包含 VS2022）进行静态编译
修改配置以使用 MT 运行库
jom 多线程构建
配置 Qt Creator
在 VS2022 中使用静态 Qt
静态编译合法性说明（LGPL）
常见问题排查

本文主要针对 Windows + Qt 5.15 + MSVC（VS2019/VS2022） 场景，提供最完整的参考流程。

编译前注意事项

Qt 许可证（LGPL）与静态链接

Qt 5.15（社区版）为 LGPL：

静态编译（-static）会强制 LGPL 条款：只要你发布软件，就必须开放应用源码或购买 Qt 商业版。

如果你的项目是闭源商用，请慎用静态编译！

Qt 5.15 是否支持 VS2022？

官方支持：
✔ MSVC 2017
✔ MSVC 2019

非官方支持但可正常编译：
✔ MSVC 2022（你当前使用的版本）

VS2022 使用 MSVC 17.x，而 Qt 5.15 的构建脚本识别 MSVC 17.x 基本无问题。
如遇到异常，只需安装最新 Windows SDK 并确保 vcvars64.bat 可正常执行。

Qt 源码下载

可从官方存档下载：

Qt 5.15.x 源码下载

例如：

1
2
3


qt-everywhere-src-5.15.2.zip

解压到：


D:\Qt\qt-everywhere-src-5.15.2

````

---

## 编译环境准备

Qt 静态编译需要工具链支持，Windows 环境需准备：

```txt
Windows 编译工具：
------------------

确保以下工具已在 PATH 中：

* 支持的 MSVC 编译器（VS2017/2019/2022）
* Perl 5.12+           https://strawberryperl.com/
* Python 2.7+/3.x      https://www.python.org/downloads/windows/
* Ruby 1.9+            https://rubyinstaller.org/downloads/
````

推荐 **Strawberry Perl** → 安装后即可使用。

---

#### 使用 MSVC 编译（推荐）

你已经安装了 **Visual Studio 2022**，建议使用 MSVC，而不要使用 MinGW。

原因：

* MSVC 编译更稳定
* Windows 商业软件常见方案
* 第三方库（如 OpenCV、FFmpeg）大多提供 MSVC 版本

运行以下命令行：

###### ✔ 64 位环境：

x64 Native Tools Command Prompt for VS 2022

1
2
3


###### ✔ 32 位环境：

x86 Native Tools Command Prompt for VS 2022


---

## 修改 MSVC 运行库为静态（MT/MTd）

打开文件：

qtbase\mkspecs\common\msvc-desktop.conf


修改内容：

```conf
QMAKE_CFLAGS_RELEASE    = $$QMAKE_CFLAGS_OPTIMIZE -MD
QMAKE_CFLAGS_RELEASE_WITH_DEBUGINFO += $$QMAKE_CFLAGS_OPTIMIZE -Zi -MD
QMAKE_CFLAGS_DEBUG      = -Zi -MDd

改为静态链接 MT：

1
2
3

QMAKE_CFLAGS_RELEASE    = $$QMAKE_CFLAGS_OPTIMIZE -MT
QMAKE_CFLAGS_RELEASE_WITH_DEBUGINFO += $$QMAKE_CFLAGS_OPTIMIZE -Zi -MT
QMAKE_CFLAGS_DEBUG      = -Zi -MTd

含义：

MD / MDd → 动态 MSVC 运行库
MT / MTd → 静态 MSVC 运行库（你需要的）

若不修改这步，编译出来的 Qt 静态库仍会依赖 MSVC 的动态运行库（不是真正的全静态）。

配置 Qt 编译（configure）

进入 Qt 源码目录：

1	cd D:\Qt\qt-everywhere-src-5.15.2

执行：

configure.bat -mp -confirm-license -opensource ^
-platform win32-msvc ^
-debug-and-release ^
-static ^
-static-runtime ^
-force-asserts ^
-prefix "D:\Qt\Qt5.15.2_MSVC2022_static" ^
-opengl desktop ^
-qt-sqlite -qt-pcre -qt-zlib -qt-freetype -qt-harfbuzz ^
-qt-libpng -qt-libjpeg ^
-nomake examples -nomake tests -silent

参数说明（建议保留）

参数	说明
-static	静态构建 Qt
-static-runtime	使用 MSVC /MT 静态运行库
-mp	多核编译（配合 jom 很好用）
-prefix	Qt 安装输出路径
-opengl desktop	使用系统 OpenGL
-qt-xxx	使用 Qt 内置库，而非系统库
-nomake	不编译 examples/tests，加快速度

jom 多线程构建（强烈推荐）

下载：

jom.exe

放入 PATH 后执行：

1 2	jom jom install

时间约 10~40 分钟（视 CPU 而定）。

完成后，你的静态 Qt 安装位于：

1	D:\Qt\Qt5.15.2_MSVC2022_static

验证静态编译是否成功

方法 1：检查 EXE 依赖

1	dumpbin /dependents your_app.exe

无 Qt5xxx.dll 即为成功。

方法 2：EXE 体积变大

一般 20MB～40MB 左右。

方法 3：windeployqt 报错

静态 Qt 无需 windeployqt → 报错反而代表“成功”。

安装 Qt Creator

Qt Creator 需要单独下载安装：

https://www.qt.io/offline-installers

离线安装时如不想登录账号，可断网跳过。

在 Qt Creator 中配置静态 Qt（可选）

打开 工具 → 选项 → Kits（套件）：

kits

将 qmake 指向：

1	D:\Qt\Qt5.15.2_MSVC2022_static\bin\qmake.exe

叹号警告通常无影响，只要 qmake + 编译器 + 调试器 可以匹配即可成功编译项目。

在 Visual Studio 2022 中使用静态 Qt 库（重点）

安装插件 Qt VS Tools（推荐）

VS 扩展市场搜索：

1	Qt Visual Studio Tools

安装后重启 VS。

添加 Static Qt 版本到 Qt VS Tools

在 VS 菜单：

1	Qt → Qt Versions → Add

选择：

1	D:\Qt\Qt5.15.2_MSVC2022_static\bin\qmake.exe

VS 会自动生成一个 Qt Kits 配置。

在 MSBuild 项目中使用 Qt 静态库

(1) 添加包含目录：

1	$(QTDIR)\include

(2) 添加库目录：

1	$(QTDIR)\lib

(3) 需要链接的 Lib 文件示例：

Qt5Core.lib
Qt5Gui.lib
Qt5Widgets.lib
qtmain.lib

常见 MSVC 静态链接选项

在 VS 项目配置里确保：

1	C/C++ → 代码生成 → 运行库：多线程 (/MT)

如果之前 Qt 用 MT 编译，而项目用 MD，会报 LNK2038 mismatch 错误。

常见静态编译报错与解决

❌ error LNK2038: mismatch detected: runtime library

原因：项目使用 MD，Qt 使用 MT。
解决：统一为 MT。

❌ fatal error C1083: Cannot open include file

缺失 Perl / Python / Ruby / SDK
解决：检查 PATH 或修复 VS 环境。

❌ QtWebEngine 无法静态编译

WebEngine 不支持静态构建。
解决：剔除模块（常规做法）。

❌ jom: command not found

解决：把 jom.exe 放入源码目录或 PATH。

Qt6

前言

在开发 Windows 桌面工具（尤其是涉及底层、安全或便携式工具）时，我们往往希望生成的 EXE 是单文件的。

你是否遇到过这种情况：
在开发机上运行正常，一拖到虚拟机或别人电脑上，就报错：

The code execution cannot proceed because libjpeg-9.dll was not found.
The code execution cannot proceed because vcruntime140.dll was not found.

这通常是因为：

Qt 默认为动态编译。
VS 项目默认为动态运行时 (/MD)。
最坑的一点：开发环境中的 Strawberry Perl、MinGW 或 vcpkg 悄悄注入了动态库依赖，导致静态编译“不纯净”。

本文将提供一份保姆级教程，教你如何在 VS2022 下构建绝对纯净的 Qt 6.10.1 静态开发环境。

准备工作

Visual Studio 2022：安装“使用 C++ 的桌面开发”工作负载。
Qt 源码：下载 qt-everywhere-src-6.10.1.zip 并解压（假设路径为 D:\Downloads\qt-everywhere-src-6.10.1）。
Python 3：需安装纯净版 Python（建议官网下载），不要使用 Strawberry Perl 自带的 Python。
Ninja：VS2022 安装时通常已自带，如果没有，请自行下载并配置。

构建纯净编译环境（核心）

这是最关键的一步。Windows 的环境变量 (PATH) 往往被 Strawberry Perl、Git、MinGW 等工具污染。直接编译会导致 CMake 错误地链接到这些工具里的 DLL（如 libjpeg-9.dll），导致静态编译失败。

我们需要创建一个批处理脚本，强制清洗当前会话的环境变量。

在源码同级目录下（或桌面），新建 clean_build.bat，内容如下（注意修改 Python 路径）：

@echo off
REM 切换到 UTF-8 代码页，防止中文乱码
chcp 65001 >nul

echo ========================================================
echo        正在构建绝对纯净的 VS2022 x64 编译环境
echo ========================================================

REM 1. 【核弹级操作】强制重置 PATH
REM 只保留 Windows 基础路径，剔除 Strawberry Perl、MinGW、vcpkg 等所有干扰
set PATH=C:\Windows\System32;C:\Windows;C:\Windows\System32\Wbem

REM 2. 【设置 Python】(Qt6 编译必需，请修改为你的实际路径)
set "PYTHON_DIR=C:\Python311"
REM 检查 Python 是否存在
if not exist "%PYTHON_DIR%\python.exe" (
    echo [错误] 找不到 Python，请编辑脚本修改 PYTHON_DIR 路径！
    pause
    exit /b
)
set PATH=%PYTHON_DIR%;%PATH%

REM 3. 【启动 VS2022 环境】
REM 默认 Community 版路径，如果是 Pro/Enterprise 请自行修改
set "VS_SCRIPT=C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars64.bat"

if not exist "%VS_SCRIPT%" (
    echo [错误] 找不到 VS2022 启动脚本 vcvars64.bat。
    pause
    exit /b
)

echo 正在初始化 VS2022 x64 环境...
call "%VS_SCRIPT%" >nul

echo.
echo ========================================================
echo 环境净化完成！当前编译器状态：
echo ========================================================
where cl.exe
echo.
echo [检查干扰项] (以下应提示"找不到"才算成功)
where perl.exe 2>nul || echo [成功] Perl 已被屏蔽
where gcc.exe 2>nul || echo [成功] GCC 已被屏蔽

echo.
echo 准备就绪。按任意键开始...
pause

REM 4. 进入构建目录 (请修改为你的构建目录)
cd /d "D:\Downloads\qt-everywhere-src-6.10.1\build_static"
cmd /k

双击运行该脚本，你将获得一个纯净的黑色命令行窗口。接下来的所有编译命令都在这个窗口内执行。

配置与编译

在脚本打开的窗口中，执行以下操作：

1. 建立构建目录

永远不要在源码目录内编译。

1
2
3

REM 假设在源码根目录下
mkdir build_static
cd build_static

2. 执行 Configure

这是静态编译的参数配置。

-static: 静态库。
-static-runtime: 关键。链接静态 CRT (/MT)，摆脱 vcruntime140.dll。
-no-opengl: 禁用 OpenGL（可选）。如果你不需要 3D 加速，建议禁用，可以大幅减少显卡驱动依赖，提高兼容性。
-skip qtwebengine: 必须跳过，Chromium 内核很难静态编译。

1	..\configure.bat -static -static-runtime -release -prefix "D:\Qt\Qt6.10.1" -confirm-license -opensource -nomake examples -nomake tests -skip qtwebengine

3. 编译与安装

REM 多核编译，耗时较长
cmake --build . --parallel

REM 安装到 -prefix 指定的目录
cmake --install .

编译完成后，你的 D:\Qt\Qt6.10.1 就是一份完美的静态 Qt SDK。

Visual Studio 项目配置（避坑）

有了静态 Qt 还不够，你的 VS 项目配置如果不对，生成的 EXE 依然会依赖 DLL。

1. 添加 Qt 版本

在 VS 扩展（Qt Visual Studio Tools）中，添加新的 Qt 版本，指向 D:\Qt\Qt6.10.1。

2. 修改运行时库 (Runtime Library)

右键项目 -> 属性 -> C/C++ -> 代码生成 -> 运行库。
必须设置为 **多线程 (/MT)**。
注意：如果设置为 /MD，会与 Qt 的静态库冲突，或者依赖 vcruntime DLL。

3. 物理清除旧缓存

在修改完配置后，务必执行一次“物理清理”：

关闭 VS。
删除项目目录下的 .vs、x64、Debug、Release 文件夹。
重新打开 VS，重新生成解决方案。

验证成果

编译生成 EXE 后，打开“x64 Native Tools Command Prompt”，使用 dumpbin 工具检查依赖：

1	dumpbin /dependents "你的程序路径.exe"

完美的结果应该只包含系统核心库：

KERNEL32.dll
USER32.dll
GDI32.dll
SHELL32.dll
…

如果列表里没有任何 Qt6Core.dll、libjpeg-9.dll 或 VCRUNTIME140.dll，恭喜，已经成功编译了一个可以在任意 Windows 电脑（甚至纯净虚拟机）上直接运行的单文件程序！