Visual Studio 2019 + Qt + MySQL 开发调试全过程问题详解
Visual Studio 2019 + Qt + MySQL 开发调试全过程问题详解
一、项目未启用 Qt 支持导致构建失败
问题现象
- 项目右键未出现 “Enable Qt Build Steps” 选项；
- 添加
.ui文件后不生成ui_xxx.h； - 包含
Q_OBJECT的类提示metaObject、qt_metacast、qt_metacall等未定义链接错误（LNK2001）； - 添加
.cpp/.h文件后，即使书写无误，也仍然编译失败。
原因分析
- 当前项目是以普通 C++ 模板（如 Empty Project 或 Console Project）创建的，不包含 Qt 的构建支持；
- Visual Studio 的 Qt 插件（Qt VS Tools）只能对通过 Qt 模板创建的项目自动启用构建规则；
- 缺少 moc/uic/rcc 的自动生成步骤。
解决方案
方法一：重新用 Qt 模板创建项目（推荐）
- 在 Visual Studio 中点击“新建项目”；
- 搜索并选择
Qt Widgets Application（或 QML 项目等）； - 创建后 Qt 插件会自动配置 Qt 构建步骤和生成规则。
方法二：手动添加 Qt 支持
- 打开
.vcxproj项目文件； - 在
<Project>标签中添加：
<PropertyGroup Label="QtSettings"><EnableQtBuild>true</EnableQtBuild><UseQt>true</UseQt>
</PropertyGroup>
- 保存后返回 Visual Studio，重新加载项目；
- 此时右键项目，已出现 “Enable Qt Build Steps”，并支持自动生成 moc/ui 文件。
方法三：右键启用 Qt 生成步骤
- 在 Visual Studio 中右键项目 → Qt Project Settings；
- 勾选
Use Qt和Enable Qt Build Steps； - 保存并重新构建。
二、QObject 子类链接错误
错误现象
error LNK2001: unresolved external symbol "public: virtual struct QMetaObject const * __cdecl ClassName::metaObject(void)const"
原因
- 使用了
Q_OBJECT宏但没有生成对应的moc_xxx.cpp文件； - 项目未启用 Qt Build Steps，导致 moc 步骤未执行。
解决方案
- 按上一节启用 Qt Build Steps；
- 手动添加
moc_xxx.cpp和.h 到项目。
三、MySQL Connector 配置问题
错误现象
fatal error C1083: 无法打开包括文件: "jdbc/mysql_driver.h": No such file or directory
解决方法
-
添加头文件目录：
-
打开 项目属性 → C/C++ → 常规 → 附加包含目录：
D:\vs2019\mysql-connector-c++-8.0.30-winx64\include\jdbc
-
-
添加库目录：
-
链接器 → 常规 → 附加库目录：
D:\vs2019\mysql-connector-c++-8.0.30-winx64\lib64
-
-
链接库文件：
-
链接器 → 输入 → 附加依赖项：
mysqlcppconn.lib
-
四、运行时找不到 DLL
错误现象
程序编译成功但运行时报错，提示找不到 libmysql.dll。
原因
- 可执行文件无法加载动态库；
- 系统路径未包含库路径。
解决方式
方法一：将以下 DLL 复制到 exe 所在目录
D:\vs2019\mysql-connector-c++-8.0.30-winx64\lib64
需要的 DLL 包括：
- libmysql.dll
- libssl-1_1-x64.dll
- libcrypto-1_1-x64.dll
方法二：添加至系统环境变量 PATH
-
打开“系统属性” → “高级” → “环境变量”；
-
找到系统变量
Path→ 编辑； -
添加路径：
D:\vs2019\mysql-connector-c++-8.0.30-winx64\lib64 -
重启 Visual Studio。
五、数据库连接失败错误 1049
错误信息
1049 (Unknown database 'Group')
原因
- 数据库
Group不存在；
解决办法
-
使用正确已存在的数据库名；
-
或在 MySQL 中创建数据库：
CREATE DATABASE Group;
六、手动添加 .cpp/.h/.ui 后无法识别类
表现
- 类
SettingParamDialog添加后仍然报错未定义；
解决
- 确保通过 项目右键 → 添加 → 现有项 正确添加；
- 若为
*.ui文件，添加后应自动生成ui_xxx.h文件，需启用 Qt 构建步骤； - 不要复制文件到目录后直接手动引用，要通过 VS 添加。
七、不要将项目改为 Makefile 工程
- 会导致 Qt 插件不再生效，丧失自动构建能力；
- 无法在 IDE 中看到 Qt 的右键菜单；
- 推荐始终使用
.vcxproj工程结构。
总结
- 使用 Visual Studio 搭配 Qt 开发必须确保项目启用了 Qt Build 支持；
- Qt 的 moc/uic/rcc 都需要工具链支持自动生成，不应手动编写；
- 与 MySQL 连接需要配置头文件、库文件和运行时 DLL；
- 所有路径建议加入系统 PATH，避免运行失败；
- 项目建议通过 Qt 模板创建，或手动修复
.vcxproj。
如需自动脚本、模板项目、示例代码，可以在团队中保存此文档或向我进一步索取。