智能家居实训项目环境搭建

主要是讲如何搭建一个 QT 6 版本加上 C++ 的开发环境。搭建过程中主要遇到了 mingw 版本冲突等问题。

#type / howto #status / evergreen #tech / dev

[!info] related notes

智能家居实训项目环境搭建

知识笔记：Qt 6 + C++ 现代化开发环境搭建指南（2026版）

0. 核心理念：优雅与隔离

  • 不污染系统环境：尽量不修改全局 PATH，通过 IDE 或脚本按需调用。
  • 配置即代码：利用包管理器（Scoop/aqt）实现环境的快速复现。
  • 版本一致性：编译器（MinGW）与库（Qt Library）必须严格匹配，避免 ABI 冲突。

1. 基础工具链：包管理先行

在 Windows 上，不再手动去官网找 .exe，而是使用开发者友好的包管理器。

  • Scoop/Winget：安装基础组件。
# 安装构建工具
scoop install cmake ninja python
# 安装 IDE
winget install Microsoft.VisualStudioCode
  • aqtinstall (aqt)：Qt 官方安装器的完美替代品，支持命令行安装指定版本的 Qt 库和工具。
pip install aqtinstall

2. 环境安装：精准匹配是关键

这是整个流程中最容易出错的地方。Qt 库的版本必须与编译器的版本对齐。

Step 1: 安装 Qt 核心库

选择最新的 LTS 版本（如 6.8.0），并指定国内镜像（阿里云/清华）以加速下载。

# 目标：Windows 桌面版, Qt 6.8.0, MinGW 64-bit 架构
aqt install-qt windows desktop 6.8.0 win64_mingw --base https://mirrors.aliyun.com/qt/ -O D:\opt\Qt

Step 2: 安装配套工具链 (MinGW)

重点：不要直接用系统最新的 MinGW（如 15.x），要用 Qt 官方测试通过的配套版本。对于 Qt 6.8.0，配套的是 MinGW 13.1.0。

# 查找匹配的工具 ID
aqt list-tool windows desktop tools_mingw1310
# 安装
aqt install-tool windows desktop qt.tools.win64_mingw1310 --base https://mirrors.aliyun.com/qt/ -O D:\opt\Qt

vscode 安装以下核心插件：

  • C/C++ Extension Pack (微软官方)
  • CMake Tools (项目构建核心)

mqtt-source-code-compilation

安装依赖

# 将 -m multimedia 改为 -m qtmultimedia
aqt install-qt windows desktop 6.8.0 win64_mingw -m qtmultimedia --base https://mirrors.aliyun.com/qt/ -O D:\opt\Qt

3. 项目配置：让代码跑起来

编译环境的“临时激活”

为了避免多个 MinGW 冲突，建议在当前终端会话中手动指定路径：

# 将编译器和 Qt bin 目录加入临时 Path
$env:PATH = "D:\opt\Qt\Tools\mingw1310_64\bin;D:\opt\Qt\6.8.0\mingw_64\bin;" + $env:PATH

构建命令流 (qmake 方案)

  1. 清理：Remove-Item build -Recurse -Force（确保没有旧编译器的残余）。
  2. 生成 Makefile：qmake.exe project.pro。
  3. 编译：mingw32-make -j8。

4. 典型问题排查 (Case Study)

报错：undefined reference to __imp___argc

  • 现象：编译最后阶段报错，无法生成 .exe。
  • 原因：ABI 冲突。使用了不匹配的编译器（如 Scoop 版 MinGW 15.2.0）去链接 Qt 官方库（由 MinGW 13.1.0 编译）。两者的运行时库（CRT）处理程序入口的方式不同。
  • 解法：卸载第三方编译器，安装并使用 aqt 提供的 tools_mingw1310。

报错：Unknown module(s) in QT: mqtt

  • 原因：Qt MQTT 属于附加模块，默认安装不包含。
  • 解法：由于官方有时不提供 MinGW 的 MQTT 二进制包，可采用源码集成方式，将 qtmqtt 源码直接加入项目文件夹编译。

5. 部署：制作绿色版程序

编译出的 .exe 无法直接在其他电脑运行（缺少 DLL）。使用 Qt 自带的部署工具：

D:\opt\Qt\6.8.0\mingw_64\bin\windeployqt.exe .\bin\YourApp.exe

该命令会自动抓取所有依赖项，形成一个可分发的文件夹。

6. 进阶建议：物联网实训联调

  • 仿真网页端：使用 WebSocket 或 MQTT.js 模拟硬件。
  • 大模型接口：在 mainwindow.cpp 中通过 QNetworkAccessManager 发送 HTTP POST 请求，将语音识别的文字发给 LLM 获取 JSON 指令。
  • 调试神器：安装 MQTT Explorer 监控数据流。

总结：环境搭建不是简单的点击“下一步”，而是对编译器版本、链接库、环境变量三者关系的精准把控。现在你的环境已经固若金汤，可以开始享受智能管家的代码开发了！

创建于 2026/1/2 更新于 2026/5/27