上个月帮一个朋友收拾他那个半途而废的桌面工具，打开工程一看，主窗口里所有控件都是手写setGeometry定死坐标的，换个屏幕分辨率整个界面就散架了。这事让我想起自己刚接触 Qt 那会儿，也是从拖控件开始的，觉得可视化的东西嘛，拖一拖就完事了。后来项目越做越大，窗口从三个变成三十个，才慢慢明白 Qt窗口程序 这套体系真正的价值不在于"能画界面"，而在于它把界面、逻辑、数据、线程、资源这些东西用一套统一的模型串了起来。这篇就把我这些年做 Qt 窗口程序攒下来的东西整理一遍，从工程骨架怎么搭、布局和信号槽怎么用、到绘图刷新、线程协作、打包发布，再到那些让人半夜爬起来查日志的报错，都会讲到。刚上手的朋友可以照着走一遍，已经做过几个项目的，可以挑着看后半部分的排查和优化部分，那里面的坑基本都是真金白银换来的。

1. 开工之前：Qt窗口程序的骨架到底怎么搭

很多人拿到需求第一反应是打开 Qt Creator 新建工程，然后就开始往窗口上拖按钮了。这个顺序其实反了。窗口程序这种东西，界面是最容易改的部分，真正难改的是工程结构和数据流向。我见过太多项目，界面做得挺漂亮，结果加一个新功能要动五六个文件，这就是骨架没搭好。所以在动手之前，先把下面三件事想清楚，后面能省掉大量返工。

1.1 三种窗口基类，选错了后面全是补丁

新建工程的时候 Qt Creator 会问你继承哪个基类，选项是 QWidget、QMainWindow、QDialog，很多人随手选了第一个，结果做到一半发现要加菜单栏和状态栏，又回头去改继承关系，这时候已经写了几百行代码，改起来全是坑。

这三个基类的定位其实非常清晰。QWidget是最基础的窗口部件，它本身不带任何附加结构，就是一个纯粹的矩形区域。如果你做的是工具面板、嵌入式设备的小屏界面，或者需要嵌到别人程序里的组件，选它。QMainWindow是给"完整应用"准备的，它自带菜单栏、工具栏、状态栏、中央部件区和停靠窗口区这五块区域，你在构造函数里调一下menuBar()、statusBar()就能直接拿到，不用自己从零拼。绝大多数桌面软件的主窗口都该用这个。QDialog则是为对话框场景设计的，它有自己的exec()模态循环和返回值机制，适合做设置项、确认框、参数输入这类"弹出来、填完、关掉"的交互。

我个人的判断标准是这样的：如果这个窗口需要长期存在并承载主要业务，用 QMainWindow；如果它只是临时弹出收集一次输入，用 QDialog；如果它要被复用成组件塞进别的容器，用 QWidget。听起来很简单，但实际项目里最常见的错误是把主窗口做成了 QDialog，然后发现模态循环把整个程序卡住了，主界面的其他操作全都点不动。

注意：QMainWindow 的中央部件只能有一个，通过setCentralWidget()设置。如果你需要在一个主窗口里切换多个页面，别去反复替换中央部件，那会导致旧部件的父子关系混乱，正确做法是中央放一个 QStackedWidget，页面切换只改索引。

还有一个容易忽略的点是窗口的父子关系。Qt 里 QObject 有一套自动析构机制，父对象销毁时会连带销毁所有子对象。窗口部件继承自 QWidget，而 QWidget 继承自 QObject，所以窗口上的所有控件只要正确设置了 parent，就不需要手动 delete。反过来，如果你在堆上 new 了一个控件却没给 parent，那就是内存泄漏，而且这种泄漏在开发期完全看不出来，上线跑几天才暴露。

1.2 工程目录怎么分，决定了半年后你还能不能看懂

Qt Creator 默认生成的工程是平铺的，所有文件堆在根目录下，三五个文件的时候还好，二十个文件之后就彻底乱了。我的习惯是在项目一开始就分好目录，哪怕当前只有一个窗口也这么分，因为改目录比改代码便宜多了。

常见的分法是这样几层：src/放所有源码，下面再按模块分ui/、core/、utils/、network/之类；resources/放图片、图标、qss 样式文件和 qrc 资源描述文件；third_party/放外部依赖的库源码或头文件；docs/放设计文档。这不是什么硬性规定，核心原则只有一条：跟界面相关的代码和跟业务逻辑相关的代码必须物理隔离。

为什么这么强调隔离？因为界面代码的变更频率极高，产品经理今天说按钮往左挪两像素，明天说这个输入框换成下拉框，而业务逻辑相对稳定。如果两者混在一个文件里，每次改界面都要重新编译整个业务模块，而且在代码审查的时候很难判断这次改动到底动没动逻辑。更实际的问题是，当你哪天想把核心逻辑抽出来做成命令行工具或者给别的程序调用，界面和逻辑缠在一起的话，你只能复制粘贴然后再删一遍。

.pro 文件或者 CMakeLists 里也要对应地配置好包含路径，这样代码里引用头文件就不用写一堆相对路径的../..。用 qmake 的话，在 .pro 里加INCLUDEPATH += $$PWD/src这种，用 CMake 就是target_include_directories，配置一次，后面所有文件都能直接#include "mainwindow.h"。

1.3 要不要用 .ui 文件，这是个真问题

Qt Designer 生成的 .ui 文件本质是一个 XML，编译时通过 uic 工具转成 C++ 头文件。它的好处是所见即所得，布局调整快，特别适合做那种控件数量多、排列规整的表单类界面。但它也有明显的问题：生成的代码你不完全可控，复杂的自定义控件塞不进去，而且多个人同时改一个 .ui 文件冲突起来非常难受，因为它是 XML，diff 出来全是噪音。

我这几年的实际做法是混合使用。布局简单、控件固定的窗口直接用 .ui，比如登录框、关于对话框、参数设置页；而那些需要动态增删控件、或者有大量自定义绘制的窗口，纯代码写，因为代码里能精确控制创建时机和生命周期。

如果决定用 .ui，有个细节值得注意：控件的 objectName 就是你在代码里通过ui->xxx访问的名字，起名要有规范，别用pushButton、pushButton_2这种默认名，做到后面你根本分不清哪个是哪个。建议用功能加类型的命名，比如btnStartCapture、editOutputPath、listDeviceItems，一眼就能看出用途。

2. 核心机制：布局、信号槽和事件循环这三根柱子

骨架定好之后，真正决定程序好不好用的就是这三个机制了。布局决定界面在各种分辨率下长什么样，信号槽决定模块之间怎么通信，事件循环决定整个程序怎么响应外部输入。这三个东西如果理解不到位，写出来的程序能跑，但一定不好维护。

2.1 布局管理器：手写坐标为什么迟早要返工

前面提到朋友那个项目就是手写坐标的典型。setGeometry(10, 20, 80, 30)这种写法在开发机上看着挺整齐，因为你的屏幕尺寸、系统缩放比例、字体大小都是固定的。但用户的机器上这些全都不确定：有人用 1080P 100% 缩放，有人用 4K 150% 缩放，有人把系统字体调成了大字体。手写坐标的程序在这些环境下必然是错位的，要么控件重叠，要么大片空白。

Qt 提供了一套布局管理器来解决这个问题，原理是布局对象负责计算每个子部件的位置和大小，子部件只需要声明自己的尺寸策略，位置的事情交给布局。用生活化的说法，手写坐标像是你在纸上用尺子量着画表格，纸张大小一变就废了；布局管理器像是用 Excel 做表格，列宽自适应，窗口拉大拉小内容永远填满。

常用的几种布局各司其职。QVBoxLayout和QHBoxLayout是垂直和水平排列，最简单也最常用。QGridLayout是网格布局，适合做那种行列整齐的表单，可以通过setColumnStretch()控制某一列占多大比例。QFormLayout专门做"标签加输入框"这种两列结构，用它比用 GridLayout 省事得多，而且跨平台时标签对齐方式会自动适配。QStackedLayout是层叠的，同一时间只显示一个，做多页面切换非常好用。

布局是可以嵌套的，这一点是做出复杂界面的关键。比如一个典型的窗口结构是：最外层垂直布局，上面放工具栏区域，中间放一个水平布局，水平布局里左边是树形导航，右边是一个 QStackedWidget 装各个页面，最下面是状态栏。这样搭出来的界面，拖拽窗口边缘时所有部分都会按比例调整。

尺寸控制上有几个参数需要理解清楚。setContentsMargins()控制布局四周留白的距离，setSpacing()控制子部件之间的间隙，这两个参数决定了界面的"呼吸感"，全设成 0 的话界面会挤成一团，看着非常业余。QSizePolicy更关键，它描述了部件在水平和垂直方向上的伸缩意愿，有 Fixed、Minimum、Maximum、Preferred、Expanding、MinimumExpanding、Ignored 七种取值。想让某个部件吃掉所有多余空间就设成 Expanding，想让它保持固定大小就设成 Fixed。setStretch()则是同一个布局内各部件分配多余空间的比例，比如两个部件 stretch 是 1 和 2，那多出来的空间就按三分之一和三分之二分。

实操心得：调布局的时候有个技巧，先用不同颜色的 stylesheet 给各个容器加上临时背景色，比如background-color: rgba(255,0,0,0.2)，这样一眼就能看出每个布局实际占据的区域，比反复猜要快得多。调完之后把这些样式删掉就行。

2.2 信号与槽：几种连接方式的取舍

信号槽是 Qt 最有辨识度的机制，本质是一种类型安全的观察者模式。对象在状态变化时发出信号，关心这个变化的对象把自己的槽函数连上去，变化发生时槽自动被调用。这套机制解耦了发送方和接收方，发送方不需要知道谁在听，接收方也不需要知道谁在说。

连接语法上，Qt5 之后主推函数指针写法：connect(btn, &QPushButton::clicked, this, &MainWindow::onBtnClicked)。这种写法的最大好处是编译期检查，信号名写错、参数不匹配，编译直接报错，不会像老式的SIGNAL()/SLOT()宏那样拖到运行时才炸，而且报错信息还是一句"QObject::connect: No such signal"让人摸不着头脑。

Lambda 写法也很常用，特别适合一次性的小逻辑，比如：connect(btn, &QPushButton::clicked, this, [this](){ doSomething(); });。但这里有个坑必须提，Lambda 捕获了 this 之后，如果这个 lambda 连接的发送方对象活得比接收方长，就会出现悬空指针访问。解决方式是给 connect 加上第三个参数作为上下文对象：connect(btn, &QPushButton::clicked, this, [this](){...})，这样当 this 被销毁时连接会自动断开。这个细节我在一个长期运行的服务程序里吃过亏，窗口关了但后台对象还在发信号，结果访问已经释放的成员变量，程序直接崩。

连接类型是另一个容易被忽略的维度。默认的Qt::AutoConnection会在发送方和接收方处于同一线程时用直连（立即同步调用），跨线程时自动切换成队列连接（把调用封装成事件投递到接收方线程的事件队列）。这个自动判断很方便，但也意味着你不能想当然地假设槽函数在哪个线程执行。如果你明确知道需要同步等待，可以用Qt::BlockingQueuedConnection，但这个只能在跨线程时用，同线程用会直接死锁。Qt::UniqueConnection可以防止重复连接，在做动态绑定的时候很有用，能避免一个信号触发多次槽的情况。

2.3 事件循环与重绘：程序为什么"卡住"了

很多人写 Qt 遇到的第一个"玄学问题"就是界面卡死。按钮点不动，进度条不刷新，窗口拖不动，但程序明明还在跑。这背后基本都是事件循环被阻塞了。

Qt 程序的主线程里跑着一个事件循环QApplication::exec()，所有鼠标键盘事件、定时器、网络回调、重绘请求都以事件的形式排队，由这个循环逐个取出处理。如果你在某个槽函数里写了一个耗时十秒的循环，这十秒内事件循环完全停摆，所有界面操作都得不到响应，操作系统甚至会认为你的程序无响应而弹出提示。

正确的处理方式有三种。第一种是把耗时任务放到工作线程里，主线程只负责更新界面，这是最规范的做法。第二种是用QTimer把大任务切分成小块，每次事件循环转一圈处理一小部分。第三种是手动调QCoreApplication::processEvents()，但这招要慎用，因为它会递归处理事件，很容易引发重入问题，比如用户在循环还没结束时又点了一次按钮。

重绘这块也有讲究。update()是请求重绘，它不会立即执行，而是把重绘事件投递到队列，等事件循环转到的时候批量处理，多次调用会被合并成一次。repaint()是强制立即重绘，会打断当前流程同步执行 paintEvent，除非有特殊需求否则不建议用，频繁调用会严重拖慢性能。还有个Qt::WA_OpaquePaintEvent属性，设置之后 Qt 知道你的绘制会覆盖整个区域，就不会先填充背景，能省一点开销，适合动画或高频刷新的场景。

2.4 资源和样式：qrc 与 qss 怎么配合

程序做好了总得有点样子。Qt 里管这个的叫样式表，语法和网页 CSS 高度相似，写起来上手很快。你可以给整个应用设置qApp->setStyleSheet(...)，也可以只给某个部件设widget->setStyleSheet(...)。选择器支持类型选择器、类选择器、ID 选择器、属性选择器，还能用伪状态比如:hover、:pressed、:checked、:disabled。

资源文件系统 qrc 是另一块。它把图片、图标、字体这些二进制资源编译进可执行文件，好处是发布的时候不用带一堆散落的文件，程序拷到哪都能跑。用法是建一个 .qrc 文件，里面用 XML 列出资源路径，然后在代码里用:/images/logo.png这种冒号开头的路径访问。

这里有个实践中的权衡值得说一下。资源全打进可执行文件会让体积变大，尤其是放了几张高清背景图之后，exe 可能从几兆涨到几十兆。但好处是部署简单，不会出现"用户把 exe 拷走了但没拷图片，界面一片空白"的情况。我的做法是图标、小图片走 qrc，大尺寸的素材文件放外部目录动态加载，兼顾体积和维护性。

注意：qrc 里的资源是只读的。有些朋友想通过 qrc 路径写文件，比如QFile(":/config.ini")然后 open 写模式，这会失败。需要在运行时写入的配置，应该放到QStandardPaths::writableLocation(QStandardPaths::AppConfigLocation)返回的目录里，这个路径在不同系统上会自动指向合适的位置。

3. 动手实操：从零跑起一个能用的主窗口

前面讲的是决策和原理，这一节直接上操作。我按一个典型的"数据查看工具"来走，主窗口带菜单、工具栏、侧边导航、内容区和一个图表页，功能包括读取本地 JSON 配置、列出目录文件信息、绘制实时曲线。这套结构能覆盖大部分中小型桌面程序的需求。

3.1 工程创建和构建配置

打开 Qt Creator，新建 Application (Qt Widgets Application)，命名为 DataViewer，构建系统我选 qmake，因为中小项目 .pro 写起来比 CMakeLists 简短得多，如果团队有统一要求用 CMake 也行，逻辑是一样的。基类选 QMainWindow，勾上 Generate form 先不勾，我们主要用代码写。

生成的 .pro 文件里，核心配置大概是这样：

QT += core gui widgets QT += charts CONFIG += c++17 TARGET = DataViewer TEMPLATE = app INCLUDEPATH += $$PWD/src SOURCES += src/main.cpp \ src/ui/mainwindow.cpp \ src/core/configloader.cpp HEADERS += src/ui/mainwindow.h \ src/core/configloader.h RESOURCES += resources/resources.qrc

这里QT += charts是引入图表模块，如果你还需要串口功能就是QT += serialport。这两个模块有个高频报错必须提前说：编译时如果提示unknown module(s) in Qt: serialport或者:-1: error: unknown module(s) in qt: serialport，九成九是你的 Qt 安装里没有勾选这个组件。Qt 官方安装器是模块化下载的，默认只装核心部分，serialport、charts、sql 这些都要手动勾。解决办法有两个，要么重新运行安装器补上对应模块，要么在 Linux 上用包管理器装libqt5serialport5-dev这类开发包。改完 .pro 之后一定要重新执行一次 qmake（构建菜单里选 Run qmake），因为模块变更不会自动触发重新解析。

Linux 环境下还有个特别容易踩的坑：系统里装了多个 Qt 版本，程序启动时报cannot mix incompatible qt library (5.15.3) with this library (5.15.2)。这是链接期用了一个版本、运行期加载到另一个版本的库导致的。排查方式是用ldd看可执行文件到底依赖哪些 Qt 库的路径，然后用LD_LIBRARY_PATH或者 rpath 明确指定，或者干脆清理掉系统里多余的版本。

3.2 主窗口搭建和菜单工具栏

主窗口的构造函数里，我一般按"先建中央区，再建动作，最后建菜单和工具栏"的顺序来，因为菜单项本质上是对 QAction 的引用，动作得先存在。

MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) { setWindowTitle("DataViewer"); resize(1200, 760); // 中央区域：左导航 + 右页面栈 auto *central = new QWidget(this); auto *hLayout = new QHBoxLayout(central); hLayout->setContentsMargins(0, 0, 0, 0); hLayout->setSpacing(0); navList = new QListWidget(central); navList->setFixedWidth(200); navList->addItems({"概览", "文件列表", "曲线监控"}); pageStack = new QStackedWidget(central); pageStack->addWidget(createOverviewPage()); pageStack->addWidget(createFilePage()); pageStack->addWidget(createChartPage()); hLayout->addWidget(navList); hLayout->addWidget(pageStack, 1); setCentralWidget(central); connect(navList, &QListWidget::currentRowChanged, pageStack, &QStackedWidget::setCurrentIndex); buildActions(); buildMenus(); buildToolBar(); statusBar()->showMessage("就绪"); }

这段代码里有几个点值得展开。hLayout->addWidget(pageStack, 1)里那个 1 是 stretch 参数，表示右侧区域吃掉所有多余宽度，左侧导航因为设了setFixedWidth所以保持 200 像素。setContentsMargins(0,0,0,0)是为了让中央区完全贴边，否则默认会有 9 像素的边距，看起来像是界面没铺满。

导航和页面栈的连接用的是currentRowChanged信号直接连到setCurrentIndex槽，这两个函数的参数类型刚好匹配（都是 int），所以可以直连，不用写中间槽函数。这种直连在 Qt 里非常常见，能让代码干净不少。

菜单和工具栏的构建：

void MainWindow::buildActions() { actOpen = new QAction(QIcon(":/icons/open.png"), "打开配置", this); actOpen->setShortcut(QKeySequence::Open); connect(actOpen, &QAction::triggered, this, &MainWindow::onOpenConfig); actRefresh = new QAction(QIcon(":/icons/refresh.png"), "刷新", this); actRefresh->setShortcut(QKeySequence::Refresh); connect(actRefresh, &QAction::triggered, this, &MainWindow::onRefresh); actQuit = new QAction("退出", this); actQuit->setShortcut(QKeySequence::Quit); connect(actQuit, &QAction::triggered, this, &QWidget::close); }

用QKeySequence::Open这种标准快捷键常量而不是硬写"Ctrl+O"，好处是跨平台时 Qt 会自动适配，在 macOS 上就变成 Command+O 了。

3.3 读配置和列文件：数据层的实操

JSON 读取是桌面工具的高频需求，Qt 提供了 QJsonDocument 这一套。读配置的典型写法是这样：

bool ConfigLoader::load(const QString &path, AppConfig &out) { QFile f(path); if (!f.open(QIODevice::ReadOnly)) { qWarning() << "open failed:" << f.errorString(); return false; } const QByteArray raw = f.readAll(); QJsonParseError err; const QJsonDocument doc = QJsonDocument::fromJson(raw, &err); if (err.error != QJsonParseError::NoError) { qWarning() << "json parse error at" << err.offset << err.errorString(); return false; } if (!doc.isObject()) { qWarning() << "root is not an object"; return false; } const QJsonObject obj = doc.object(); out.interval = obj.value("interval").toInt(1000); out.outputDir = obj.value("output_dir").toString("./out"); const QJsonArray dirs = obj.value("watch_dirs").toArray(); for (const QJsonValue &v : dirs) { if (v.isString()) out.watchDirs.append(v.toString()); } return true; }

这段代码里有三个防御性设计值得学。第一，fromJson带了QJsonParseError参数，出错时能拿到具体的偏移位置，排查配置文件格式问题时这个信息非常有用。第二，对根节点类型做了检查，因为 JSON 顶层可以是对象也可以是数组，不检查就跟后面的toObject()逻辑对不上。第三，取值时用value()加默认值而不是operator[]，前者在键不存在时返回 undefined，toInt()会给默认值，后者虽然也能用但可读性差一点。

文件信息获取用 QFileInfo 和 QDir 就够了：

QFileInfoList list = QDir(dirPath).entryInfoList( {"*.log", "*.csv"}, QDir::Files | QDir::NoDotAndDotDot, QDir::Time | QDir::Reversed); for (const QFileInfo &fi : list) { qDebug() << fi.fileName() << fi.size() << fi.lastModified().toString("yyyy-MM-dd hh:mm:ss") << fi.suffix(); }

QDir::Time | QDir::Reversed这个组合是按修改时间倒序，做日志查看类工具时经常用。entryInfoList比自己在循环里逐个QFileInfo要高效，因为它一次性拿到所有元数据。

3.4 曲线绘制：QChart 的用法和刷新线程

图表这块 Qt 提供了 QtCharts 模块，虽然性能上不如一些专门的绘图库，但对于几千个点的实时曲线完全够用。基本用法是先建 series 和 chart，再建坐标轴，最后关联起来：

QChart *chart = new QChart(); QLineSeries *series = new QLineSeries(); QValueAxis *axisX = new QValueAxis(); axisX->setRange(0, 100); axisX->setTitleText("时间(s)"); QValueAxis *axisY = new QValueAxis(); axisY->setRange(-1, 1); axisY->setTitleText("幅值"); chart->addSeries(series); chart->addAxis(axisX, Qt::AlignBottom); chart->addAxis(axisY, Qt::AlignLeft); series->attachAxis(axisX); series->attachAxis(axisY); QChartView *view = new QChartView(chart); view->setRenderHint(QPainter::Antialiasing);

注意addSeries的顺序要在addAxis之前，而且每个 series 必须显式attachAxis才会显示，这个在 Qt 5 的某些小版本上如果顺序反了会出现曲线不显示的问题。

数据刷新如果点多了，直接series->append()会越来越卡，因为内部没有容量限制。控制方法是维护一个固定长度的队列，超出就移除最前面的点：

series->append(x, y); if (series->count() > kMaxPoints) { series->remove(0); } axisX->setRange(x - kWindowSeconds, x);

至于"曲线刷新能不能放在另一个线程"这个问题，我自己的结论是：数据采集可以在线程里做，曲线插值也可以在线程里算，但最终往 series 里 append 的操作必须回到主线程。原因是 QLineSeries 属于 QGraphicsItem 体系，它不是线程安全的，跨线程操作会随机崩溃，而且这种崩溃的堆栈往往指向完全无关的地方，排查起来极其痛苦。正确做法是在工作线程里算好一批点，通过信号传出去，队列连接保证接收端在主线程执行：

// 工作线程中 emit dataReady(QVector<QPointF> points); // 主线程中接收 connect(worker, &Sampler::dataReady, this, &MainWindow::onDataReady, Qt::QueuedConnection);

信号参数用QVector<QPointF>是可以的，因为 Qt 的元对象系统内置支持这个类型的序列化。如果换成自定义结构体，需要先qRegisterMetaType注册，否则跨线程传参会失败并打印一句"QObject::connect: Cannot queue arguments of type..."。

缩放和拖动方面，QChartView 支持setRubberBand()，设成QChartView::RectangleRubberBand之后鼠标拖拽就能框选放大，RectangleRubberBand配合右键可以缩小。如果要实现鼠标滚轮平滑缩放，需要自己重写wheelEvent，在事件里调整坐标轴范围然后chart->zoom()或者直接改setRange。

3.5 编译、调试和打包发布

开发阶段没什么好说的，Qt Creator 的调试器能直接断点、看变量，注意学会用条件断点，在循环里定位特定情况很有用。

真正麻烦的是发布。Windows 上最容易犯的错是直接把 exe 拷给用户，结果对方一运行就报缺 DLL。原因是 Qt 程序依赖 Qt5Core.dll、Qt5Gui.dll、Qt5Widgets.dll 以及一堆平台插件，这些都不会自动打进 exe。官方的解决方案是用windeployqt工具：

mkdir dist copy release\DataViewer.exe dist\ windeployqt --release --no-translations dist\DataViewer.exe

windeployqt会扫描 exe 的依赖，把需要的 DLL、插件目录（platforms、imageformats、styles）都拷过去。有个细节特别容易踩：platforms/qwindows.dll这个文件必须存在，缺了的话程序启动时会弹一个"could not find or load the Qt platform plugin windows"的错误然后直接退出。很多人以为 DLL 拷全了就行，忽略了插件目录。

Linux 上对应的是linuxdeployqt或者手写脚本收集依赖，思路是一样的，用ldd列出依赖再逐个拷，同时要把 Qt 的插件目录也带过去。另外 Linux 下打包还得注意系统库不能带，比如 glibc、libstdc++ 这些要依赖目标机器自己的，带了反而容易出问题。

如果想让安装体验好一点，可以用 NSIS 或者 Inno Setup 做一个安装包，把 windeployqt 输出的整个目录打进去，顺便创建开始菜单快捷方式。这一步不算难，但能让交付显得专业很多。

4. 常见问题排查：那些让人抓头发的现场

写了这么多年，遇到问题的类型其实很集中，无非是编译不过、运行崩溃、界面不刷新这几类。我按这个分类整理一下，配合排查思路和解决方案，遇到的时候可以对着查。

4.1 编译和链接期的典型报错

编译期的报错相对好办，因为编译器会告诉你具体位置。麻烦的是那些"看起来像编译器问题其实是你自己问题"的类型，下面这张表是我整理的高频清单。

undefined reference to vtable这个错误特别容易误导人，因为它看起来像是虚表的问题，实际上绝大多数情况是你在头文件里声明了一个虚函数但忘了在 cpp 里实现，或者是类里用了 Q_OBJECT 宏但对应文件没有被 moc 处理。清理构建目录重新来一遍能解决相当一部分玄学报错，因为 Qt 的构建系统对增量编译的处理偶尔会出岔子。

还有一个跟 VS Code 相关的问题也经常有人问：在 VS Code 里配置 Qt 开发环境，最麻烦的是 IntelliSense 找不到头文件，需要手动在 c_cpp_properties.json 里加 includePath，指向 Qt 的 include 目录，同时定义好编译器的路径。构建部分可以配一个 tasks.json 调 qmake 和 make，或者直接用 CMake Tools 插件。这个配置一次就好，但第一次弄确实要花点时间。

4.2 运行期崩溃的排查顺序

崩溃是最耗时间的，因为很多时候不给你堆栈。我总结的排查顺序是这样的：先看崩溃是否稳定复现，稳定复现的问题用调试器直接跑，崩了就有堆栈；不稳定复现的先怀疑多线程和内存问题，这时候可以打开 Qt 的调试输出，或者用 AddressSanitizer 这类工具。

几类高频崩溃原因值得单独说。空指针访问最常见，尤其是从容器里取指针之后没判空就用了，或者某个初始化函数的返回值没检查。跨线程访问界面对象排第二，症状是崩溃位置飘忽不定，堆栈偶尔指向 QWidget 的绘制代码，偶尔指向别的地方。父子关系重复排第三，比如一个控件被 addWidget 到两个布局里，或者手动 delete 了有 parent 的对象导致 Qt 后续再析构一次。

QObject的析构顺序也有讲究。父对象析构时会先删子对象，如果你的槽函数在父对象析构过程中还被触发，就会访问到已经部分析构的成员。避免方式是在析构函数里先断开所有连接，或者确保发送方比接收方先销毁。

4.3 界面不刷新和卡顿的处理

界面刷新类问题虽然不崩，但特别影响体验。常见的几种表现和对策可以这样对照：

进度条走到一半不动了，通常是在主线程里跑长循环，解决方案是把循环拆开用 QTimer 分片，或者整体挪到工作线程。控件内容改了但界面没变，先确认改的是不是主线程的副本，跨线程改数据必须通过信号传回主线程再更新。动画卡顿掉帧，检查是不是在 paintEvent 里做了耗时计算，绘制函数里只应该做纯粹的绘制，复杂计算提前算好缓存起来。

绘图效率这块有个经验值可以分享：用 QPainter 画几千条线段的静态图，开启抗锯齿和不开启差别大概在两三倍，如果是高频刷新场景，建议关掉抗锯齿或者只在必要时开。QChart 的曲线数量超过十条、每条点数上万的时候会明显吃力，这时候考虑降采样，或者换用 QCustomPlot 这类更轻量的库。

再补一个容易忽略的点：update()调用太频繁本身也会拖慢程序，因为它会产生大量重绘事件。如果数据每秒来几百次，不要每次都调 update，用一个 30 到 60 毫秒的定时器统一触发重绘就够了，人眼的感知上限也差不多在这个范围。

5. 做了几个项目之后，我自己的几条经验

最后聊几条没法写进文档但确实有用的东西。第一条是关于界面设计流程的，我现在做新窗口都是从纸上画草图开始，把每个区域的功能和大致比例标出来，然后再打开 Qt Creator。直接上手拖控件的话，很容易陷入"这个按钮再左移两像素"的反复调整里，效率极低。草图阶段改一版只要两分钟，代码阶段改一版可能要半小时。

第二条是关于第三方库引入的。用 Qt 调别的库是常见需求，比如调用某个图像处理库、某个数学计算库，这时候要注意它们的线程模型和内存管理方式跟 Qt 不一定一致。我的做法是在 Qt 和外部库之间加一层薄的封装类，所有外部调用都经过这一层，一来隔离了头文件依赖，二来如果将来换库只改一处。

第三条是关于代码风格统一。Qt 项目大了之后最怕两个人写出来的代码互相看不懂，命名规范、信号槽命名习惯、错误处理方式最好在项目开始时定下来。我一般会要求槽函数统一用 on 加控件名加动作的形式，错误处理统一用 qWarning 输出加返回值，别有的地方弹对话框有的地方写日志。

第四条是关于版本管理的。Qt 版本之间细微的 API 差异比想象中多，5.12、5.15、6.x 在一些绘图和线程接口上都有变化。团队协作时把 Qt 版本写进 README，构建脚本里也做一下版本检查，能省掉很多"在我机器上好好的"的扯皮。如果项目要长期维护，我建议锁定一个 LTS 版本，不要追新，等生态稳定了再考虑升级。升级这件事本身也是个独立课题，因为从 Qt5 到 Qt6 有不少 API 被废弃或者改了签名，得留出专门的改造时间，别指望顺手就迁完了。