【QT开发】Windows 10 + Qt 5.15.2 手动编译安装 Qt OPC UA 模块完整记录

一、背景

• 操作系统：Windows 10

• Qt 版本：5.15.2 (MSVC 2019 64-bit)

• 目标：使用 Qt OPC UA 模块连接 OPC UA 服务器

• 问题：Qt 5.15.2 不自带 OPC UA 模块，需从源码编译安装

  二、整体流程

• 下载 Qt OPC UA 源码

• 安装依赖（OpenSSL、Perl）

• 配置编译环境

• 编译 Debug / Release 版本

• 安装库文件到 Qt 目录

• 复制后端插件

• 注册模块至 Qt（实现 QT += opcua）

• 验证

  三、详细步骤

  3.1 下载源码

  git clone https://github.com/qt/qtopcua.git
  cd qtopcua
  git checkout 5.15.2
  git submodule update --init --recursive

3.2 安装 OpenSSL

Qt OPC UA 依赖 OpenSSL 1.1.1 版本（3.x 不兼容）。

• 下载：Win64OpenSSL-1_1_1w.exe

• 安装路径：E:\OpenSSL\OpenSSL-Win64

• 安装时勾选 "Add to system PATH"

  3.3 安装 Perl

  编译过程需要 Perl 运行 syncqt.pl。

• 下载：Strawberry Perl 5.32.1.1 64-bit

• 安装路径：E:\strawberryPerl

• 手动添加至系统环境变量 PATH：

  • E:\strawberryPerl\perl\bin

  • E:\strawberryPerl\perl\site\bin

验证

perl -v

3.4 配置 OpenSSL 路径（重要）

编辑源码中的 src/opcua/opcua.pro，指定 OpenSSL 路径：

OpenSSL_Path = "E:/OpenSSL/OpenSSL-Win64"
INCLUDEPATH += $$OpenSSL_Path/include
LIBS += -L$$OpenSSL_Path/lib -llibcrypto -llibssl

3.5 编译与安装

注意：Qt Creator 图形界面

1. 打开 qtopcua.pro

2. 选择 Release 配置（Debug 也可，但 Release 更稳定）

3. 在 Projects → Build Environment 中添加：

   • OPENSSL_ROOT_DIR = E:/OpenSSL/OpenSSL-Win64

   • OPENSSL_INCLUDE_DIR = E:/OpenSSL/OpenSSL-Win64/include

   • OPENSSL_LIBRARY_DIR = E:/OpenSSL/OpenSSL-Win64/lib

   • PATH 追加 E:\strawberryPerl\perl\bin;E:\strawberryPerl\perl\site\bin

4. 点击 Run qmake → Build

5. 在 Make arguments 中输入 install，再次点击 Build （或 Build → Rebuild）

3.6 复制后端插件

即使安装成功，plugins/opcua 目录可能仍为空，需手动复制。

• 源目录：build-qtopcua-...-Release\plugins\opcua\open62541_backend.dll

• 目标目录：D:\Qt5.15\5.15.2\msvc2019_64\plugins\opcua\

手动创建 plugins\opcua 文件夹，复制 open62541_backend.dll。

3.7 注册模块（支持 QT += opcua）

复制模块配置文件，让 Qt 识别 opcua 模块。

• 源目录：build-qtopcua-...-Release\mkspecs\modules\

  • qt_lib_opcua.pri

  • qt_plugin_open62541_backend.pri

• 目标目录：D:\Qt5.15\5.15.2\msvc2019_64\mkspecs\modules\

复制后重启 Qt Creator。

3.8 验证

新建 Qt Console 项目，.pro 文件：

QT += core opcua
CONFIG += c++17
SOURCES += main.cpp

main.cpp：

#include <QCoreApplication>
#include <QtOpcUa/QOpcUaProvider>
#include <QDebug>

int main(int argc, char *argv[])
{
    QCoreApplication a(argc, argv);
    QOpcUaProvider provider;
    qDebug() << "Available backends:" << provider.availableBackends();
    return 0;
}

输出应包含 ("open62541")。

四、常见错误及解决

错误现象	原因	解决方法
openssl/asn1.h: No such file or directory	缺少 OpenSSL 或路径未设置	安装 OpenSSL 1.1.1，在 .pro 中指定 INCLUDEPATH 和 LIBS，并在构建环境中添加变量
'perl' 不是内部或外部命令	未安装 Perl 或 PATH 未包含	安装 Strawberry Perl，添加至 PATH，重启 Qt Creator
Cannot run compiler 'cl'	MSVC 环境未初始化	使用开始菜单中的 "Qt 5.15.2 MSVC 2019 64-bit" 命令行
Debug 可编译，Release 失败	Release 构建环境缺少 OpenSSL/Perl 路径	手动为 Release 配置添加相同的环境变量
示例程序 opcuaviewer.exe 缺失	示例未编译（不影响使用）	忽略，只关注库文件和插件
自己的项目无法 QT += opcua	缺少模块配置文件	复制 *.pri 到 mkspecs\modules 并重启 Qt Creator

五、最终确认清单

• Qt OPC UA 库已安装至 D:\Qt5.15\5.15.2\msvc2019_64\lib\Qt5OpcUa.*

• 后端插件 open62541_backend.dll 位于 plugins\opcua\

• 模块配置文件 qt_lib_opcua.pri 位于 mkspecs\modules\

• 测试项目输出 Available backends: ("open62541")

---

六、参考资源

• Qt OPC UA 官方文档：https://doc.qt.io/qt-5/qtopcua-index.html

• OpenSSL 1.1.1w 下载：https://slproweb.com/products/Win32OpenSSL.html

• Strawberry Perl：https://strawberryperl.com