Qt 跨线程信号槽：connect 返回 true 但槽函数不执行的坑

一句话总结：connect 返回 true 只代表连接注册成功，跨线程队列连接还要求参数类型已注册到 Qt 元类型系统，否则参数无法入队，槽函数永远不会被调用。

现象

最近调试一个 Qt 跨线程信号槽时，遇到了一个很隐蔽的问题：

QObject::connect(...) 返回 true，看起来连接成功；
信号在 sender 端 emit 正常触发；
但 receiver 的槽函数从不被调用，断点打不进去；
运行时控制台偶尔闪过一行 WARN，很容易被忽略：

text

复制代码

[WARN] QObject::connect: Cannot queue arguments of type 'QVector<quint16>'
(Make sure 'QVector<quint16>' is registered using qRegisterMetaType().)

根本原因

关键点在于：

connect 只验证信号和槽的签名是否匹配，不会检查参数类型是否支持跨线程传递。

当 sender 和 receiver 在不同线程时，Qt 的 AutoConnection 会自动降级为 QueuedConnection。这时参数需要通过事件队列进行序列化/反序列化，而 Qt 只能处理已经注册到元对象系统的类型。

QVector<quint16>、std::vector<T>、自定义 struct 等类型，默认不在 Qt 内置的元类型名单里。所以：

connect 注册时看似成功；
实际执行时 Qt 发现无法序列化参数；
参数无法入队，槽函数永远不会被调用。

这就是为什么断点命不中------函数根本没被调用。

修复方法

在 connect 之前，用 qRegisterMetaType 注册参数类型即可：

cpp

复制代码

// 必须先注册，再 connect
qRegisterMetaType<QVector<quint16>>("QVector<quint16>");

connect(m_panelServer, &PanelModbusServer::controlChanged,
        m_panelRouter, &PanelCommandRouter::sltControlChanged);

注意：第二个参数 "QVector<quint16>" 是注册名，必须与信号参数在 moc 生成签名中使用的类型名保持一致。

qRegisterMetaType 只需要在程序启动时调用一次，放在初始化代码里即可。比如放在 m_panelRouter 创建之后、connect 之前。

加上后重新编译运行，WARN 消失，断点就能命中了。

哪些类型需要手动注册？

类型	是否需要注册
`QVector<T>` / `std::vector<T>`	✅ 需要
自定义 `struct` / `class`	✅ 需要（`Q_DECLARE_METATYPE` + `qRegisterMetaType`，必要时配合 `Q_GADGET`）
`QString` / `int` / `QPoint` / `QSize` 等	❌ 不需要，Qt 内置
裸指针 `MyClass*`（跨线程）	✅ 需要

排查步骤

遇到"槽函数不执行"的问题时，可以按这个顺序排查：

看运行期 WARN

搜索控制台里有没有 Cannot queue arguments of type 这类提示。
有 WARN

加 qRegisterMetaType<T>() 后重新编译。
没 WARN 但槽不执行

在 connect 后打印返回值确认：

cpp
复制代码
```
bool connected = connect(...);
qDebug() << "connect result:" << connected;
```
connected == false

检查信号/槽签名是否完全匹配，包括参数类型、const、引用修饰等。
确认线程关系

如果 sender 和 receiver 跨线程，优先怀疑队列连接和元类型注册问题。

经验总结

connect 返回 true 只代表"连接已注册"，不代表"连接能正常工作"。
跨线程传递自定义类型、容器类型时，养成习惯先 qRegisterMetaType。
qRegisterMetaType 只需要调用一次，放在程序启动阶段、相关 connect 之前即可。
那个一闪而过的 WARN，往往就是问题的根源。
如果断点不命中，除了检查连接方式、线程归属，也要看看运行日志里有没有元类型未注册的警告。