Qt Creator 引入第三方库 OpenCV 配置指南

Qt Creator 引入第三方库 OpenCV 配置指南

引言

在软件开发中，集成第三方库是常见需求。对于使用 Qt 框架的 C++ 开发者，掌握如何高效地将 OpenCV（计算机视觉库）集成到项目中是一项核心技能。本教程将演示如何将 OpenCV 库集成到 Qt Widgets 项目中，解决路径配置、链接器错误及运行时 DLL 丢失等问题。

一、准备工作

1.1 获取并安装 OpenCV

从 OpenCV 官方网站下载适用于 Windows 的预编译版本。解压后，核心内容位于 build 子目录：

• opencv/build/include: 存放头文件（.h, .hpp）。
• opencv/build/x64/vc15/lib: 存放链接库文件（.lib），包含 Release 和 Debug 版本。
• opencv/build/x64/vc15/bin: 存放运行时依赖的动态链接库（.dll）。

1.2 创建新的 Qt 项目

打开 Qt Creator，创建新项目：

1. File -> New Project
2. 选择 Application (Qt) -> Qt Widgets Application
3. 命名项目（如 testqt），选择构建系统为 qmake
4. 保持默认设置完成创建

1.3 建立专业的项目目录结构

建议采用源码与依赖分离的结构，以增强可移植性。假设项目根路径为 D:/MyProjects/testqt/，结构如下：

D:/MyProjects/
|-- 3rdparty/
|   |-- opencv/
|       |-- include/  (OpenCV 头文件)
|       |-- lib/      (OpenCV .lib 文件)
|       |-- bin/      (OpenCV .dll 文件)
|-- testqt/           (Qt 项目目录)
    |-- testqt.pro
    |-- main.cpp
    |-- widget.h
    |-- widget.cpp
    |-- widget.ui

将 OpenCV 解压后的对应文件复制到 3rdparty/opencv/ 下对应的文件夹中。

二、配置.pro 文件

.pro 文件是 Qt 项目的核心，需配置头文件路径 (INCLUDEPATH) 和库文件路径 (LIBS)。

2.1 方式一：图形化向导

右键点击项目根节点，选择 Add Library...，添加外部库。注意勾选平台限制，取消自动添加 debug 后缀选项，以便手动控制。

2.2 方式二：手动编辑.pro 文件（推荐）

手动编辑能更好地控制相对路径和调试模式区分。在 testqt.pro 末尾添加以下代码：

# =================================================================== # OpenCV Configuration # =================================================================== 
# $$PWD 代表.pro 文件所在目录，../ 向上追溯至 3rdparty 目录
INCLUDEPATH += $$PWD/../3rdparty/opencv/include

CONFIG(debug, debug|release) {
    # Debug 模式
    LIBS += -L$$PWD/../3rdparty/opencv/lib -lopencv_world320d
} else {
    # Release 模式
    LIBS += -L$$PWD/../3rdparty/opencv/lib -lopencv_world320
}

说明：

• $$PWD/../3rdparty/opencv/lib: 使用相对路径，确保项目迁移后路径依然有效。
• CONFIG(debug, debug|release): 根据构建模式自动选择对应的库文件。
• -L: 指定库文件目录。
• -l: 指定库名称（去掉前缀和后缀）。

编辑完成后，务必执行 Run qmake 使配置生效。

三、编写代码并编译

3.1 修改 main.cpp

添加 OpenCV 头文件并调用简单函数验证集成效果：

// main.cpp
#include "widget.h"
#include <QApplication>
#include <opencv2/opencv.hpp>

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);
    
    // 测试代码：创建一个 OpenCV 窗口
    cv::namedWindow("open cv");
    
    Widget w;
    w.show();
    return a.exec();
}

3.2 编译项目

点击编译按钮。若配置正确，应能通过编译且无链接错误。

四、运行与问题排查

编译成功后，直接运行可能会遇到'丢失 opencv_world320d.dll'的错误。这是因为动态链接库需要在运行时被加载。

4.1 问题根源

编译器通过 .lib 文件确认函数存在，但程序运行时操作系统需要找到 .dll 文件。默认搜索路径通常不包含项目自定义的 3rdparty/bin 目录。

4.2 解决方案

方案一：手动复制 DLL

将对应的 .dll 文件复制到可执行文件所在的 debug 或 release 构建目录。此方法简单但每次清理项目后需重复操作。

方案二：配置运行环境

在 Qt Creator 的 Projects -> Build & Run -> Run 标签页中，设置 Working directory 为存放 DLL 的目录（如 3rdparty/opencv/bin）。此方法仅在 IDE 内运行有效。

方案三：编写构建后脚本（推荐）

修改 .pro 文件，利用 QMAKE_POST_LINK 在编译后自动复制 DLL 到输出目录：

# Post-build step: Copy DLLs
defineTest(copy_dll) {
    QMAKE_POST_LINK += $$quote(cmd /c copy /y $$shell_path($$1) $$shell_path($$2))
    return(true)
}

DLL_SOURCE_DIR = $$PWD/../3rdparty/opencv/bin
DEST_DIR = $$OUT_PWD

CONFIG(debug, debug|release) {
    copy_dll($$DLL_SOURCE_DIR/opencv_world320d.dll, $$DEST_DIR)
} else {
    copy_dll($$DLL_SOURCE_DIR/opencv_world320.dll, $$DEST_DIR)
}

此方案自动化程度高，适合发布部署。

总结

本文介绍了在 Qt Creator 中集成 OpenCV 的完整流程：

1. 规范目录结构：分离源码与依赖，提高可移植性。
2. 精确配置.pro：使用相对路径和条件编译区分 Debug/Release。
3. 解决 DLL 问题：理解运行时加载机制，推荐使用构建后脚本自动处理。

掌握此方法同样适用于其他第三方 C++ 库的集成。