QSystemTrayIcon 创建失败或图标不显示最常见原因是未设置有效 QIcon；需检查 isSystemTrayAvailable()、使用 qrc 资源路径、调用 show()，Linux 需确认桌面环境支持，右键菜单须通过 setContextMenu() 设置，左键响应需连接 activated() 信号并判断 ActivationReason。
QSystemTrayIcon 创建失败或图标不显示
最常见原因是没设置图标，或者图标路径错误。Qt 要求 QSystemTrayIcon 必须绑定一个有效的 QIcon，否则 isSupported() 可能返回 true，但图标就是不出现。
- 先用
QSystemTrayIcon::isSystemTrayAvailable()和QSystemTrayIcon::supportsMessages()检查平台支持（Linux 某些桌面环境如 Wayland + GNOME 默认禁用托盘） - 图标必须是实际存在的资源，推荐用
:/{path}方式加载 qrc 资源，避免相对路径失效：QIcon(":/icons/tray.png") - Windows 和 macOS 一般没问题；Linux 下若用 KDE Plasma，需确认系统设置中启用了“传统系统托盘”（Plasma 6 默认隐藏）
- 创建后必须调用
show()，否则静默无反应
右键菜单点击无响应或菜单不弹出
根本原因通常是菜单没有被正确关联到托盘对象，或事件被拦截。Qt 的托盘右键行为不走标准 mousePressEvent，而是依赖 QSystemTrayIcon::contextMenu() 属性和 activated() 信号。
- 不要重写
QSystemTrayIcon子类去捕获鼠标事件——它不转发右键 - 正确做法：构造一个
QMenu*，设置为trayIcon->setContextMenu(menu)，然后调用menu->addAction(...) - 菜单项触发逻辑应连接到普通槽函数，例如：
connect(action, &QAction::triggered, this, &MyApp::onExitClicked) - 确保菜单对象生命周期长于托盘对象（通常设为父对象，如传入
new QMenu(this)）
点击托盘图标（非右键）没反应
QSystemTrayIcon 默认对左键点击不做任何处理，需要手动监听 activated() 信号并判断触发类型。
- 该信号参数是
QSystemTrayIcon::ActivationReason枚举值，常用：Trigger（单击）、DoubleClick（双击）、Context（右键，此时会优先走 contextMenu） - 连接方式示例：
connect(trayIcon, &QSystemTrayIcon::activated, this, &MyApp::onTrayActivated) - 在槽函数里用
switch(reason)分支处理，注意Context类型下一般不额外弹菜单——因为setContextMenu()已接管 - macOS 上单击可能无效，建议默认响应
DoubleClick更稳妥
图标闪烁、消息弹窗不显示或中文乱码
通知消息（QSystemTrayIcon::showMessage()）在不同平台表现差异大，且容易因编码或权限失败。
- Linux 下需 D-Bus 服务（如
org.freedesktop.Notifications）可用，Arch/Manjaro 用户常缺notification-daemon或xdg-desktop-portal - 消息标题和内容长度受限（尤其 Windows），超长会被截断，建议控制在 64 字符内
- 中文乱码多因构建时未指定 UTF-8 编码，确保
.pro文件含QMAKE_CXXFLAGS += -finput-charset=UTF-8，或在 main() 开头加QTextCodec::setCodecForLocale(QTextCodec::codecForName("UTF-8")) - 图标频繁调用
setIcon()可能导致闪烁，如需动画效果，改用定时器 + 小间隔切换图标，避免连续 setIcon
托盘功能看似简单，但跨平台细节极多——特别是 Linux 桌面环境碎片化严重，同一段代码在 X11 和 Wayland 下行为可能完全不同。调试时优先检查 isSystemTrayAvailable() 返回值和图标加载是否成功，比盲目改菜单逻辑更有效。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
