信号槽是 Qt 核心机制，连接失败表现：槽函数不执行、崩溃、编译报错。下面按出现频率排序，逐一说明原因、现象、解决方案。
1. 类未继承 QObject 且缺少 Q_OBJECT 宏
现象：编译报错undefined reference to vtable，运行完全不触发。
原因：只有继承QObject并声明Q_OBJECT的类，才会被 MOC 解析信号槽。
修复
cpp
运行
class MyClass : public QObject { Q_OBJECT // 必须添加 public: explicit MyClass(QObject *parent = nullptr); signals: void testSig(); public slots: void testSlot(); };额外操作：清理项目 → 重新 qmake/CMake → 编译。
2. 信号 / 槽函数签名不一致
现象：编译无错，运行槽函数从不执行。
规则：参数数量、参数类型、顺序必须严格一致；槽参数可以比信号少（多余参数舍弃）。
错误示例：
cpp
运行
// 信号：带 int 参数 void sig(int a); // 槽：参数类型不匹配 void slot(QString a);修复：统一参数类型与顺序。
3. 槽函数未声明为 slots / Q_INVOKABLE
现象：运行无报错，槽不执行；QML 调用 C++ 函数尤为常见。
原因
- C++ 普通成员函数，不能直接作为槽；
- 被 QML 调用的函数需要
Q_INVOKABLE。
修复
cpp
运行
// 方式1：标准槽函数 public slots: void mySlot(); // 方式2：允许 QML / 动态调用 Q_INVOKABLE void myFunc();4. 连接时对象指针为空（野指针 / 未初始化）
现象：程序直接崩溃，或连接日志提示Invalid object。
定位：连接前打印指针qDebug() << obj;，地址为 0 即为空。
修复：保证sender和receiver都已正常实例化。
5. 信号槽名称拼写错误（大小写敏感）
现象：编译正常，运行无响应。
原因：Qt 信号槽名称大小写敏感，clicked≠Clicked。
修复：严格核对信号、槽函数名。
6. 跨线程连接未注意生命周期，对象提前销毁
现象：偶尔生效、偶尔失效，后台莫名崩溃。
原因：发送者 / 接收者所在线程结束，对象被析构，信号无法投递。
修复
- 保证对象生命周期长于信号触发时机；
- 跨线程优先使用
Qt::QueuedConnection； - 非模态窗口 / 临时对象慎用信号槽。
7. 重载信号 / 槽，编译器无法自动推导
现象：编译报错no matching function for call to connect。
原因：函数重载，connect不知道选用哪个版本。
修复：使用函数指针显式指定版本
cpp
运行
// 假设有重载：void clicked(bool checked = false) connect(btn, QOverload<bool>::of(&QPushButton::clicked), this, &MainWindow::onClicked);8. 命名空间、类作用域问题
现象：找不到信号 / 槽，编译失败。原因：自定义类在命名空间内，connect无法识别。修复：补全命名空间，或使用前置声明。
9. 控件在 UI 设计师中提升为类失败
现象：UI 拖拽的控件，信号槽不触发。原因：控件未提升为自定义类，还是原生控件，自定义信号自然不存在。修复：Qt Designer → 右键控件 → 提升为 → 填写类名与头文件。
10. connect 第五个参数连接方式使用错误
现象：同线程正常，跨线程完全不执行。五种连接方式核心
Qt::DirectConnection：同步调用，跨线程危险（直接在发送线程执行槽）；Qt::QueuedConnection：队列异步，跨线程标准用法；Qt::AutoConnection（默认）：自动判断同 / 跨线程。
问题场景：手动强制DirectConnection用于跨线程，UI 操作崩溃 / 不执行。
修复：跨线程显式指定队列连接：
cpp
运行
connect(sender, &Sender::sig, receiver, &Receiver::slot, Qt::QueuedConnection);附加：快速排错技巧
- 开启连接日志：
qInstallMessageHandler捕获警告，Qt 会打印连接失败原因； - 连接前校验指针、打印类名；
- 最简测试：新建空槽，只打印日志，逐步定位问题。
小结
信号槽排错优先级：
指针非空 → 名称大小写 → 函数签名 → Q_OBJECT/MOC → 槽声明(slots/Q_INVOKABLE) → 跨线程连接方式。
