Qt程序检测已有实例并退出新进程的核心方法是使用QLocalSocket+QLocalServer：首次启动创建命名服务端，后续启动尝试连接该名，若成功则唤醒旧实例并立即退出；此法跨平台、资源自动清理、避免QSharedMemory等方案的残留与权限问题。
Qt程序如何检测已有实例并退出新启动进程
Qt本身不提供跨平台的单实例锁机制，必须借助系统级手段实现。核心思路是：新进程启动时尝试获取一个全局唯一标识（如共享内存、本地socket、文件锁或系统互斥量），若获取失败，说明已有实例在运行，当前进程应立即退出。
最可靠且跨平台的方式是使用 QLocalSocket + QLocalServer，它在 Windows/macOS/Linux 上行为一致，不依赖外部文件或注册表，崩溃后资源也能自动清理。
- 不要用
QSharedMemory单独实现——Windows 下可能残留锁，Linux/macOS 上权限问题多，且无法主动通知旧实例前置窗口 - 避免基于临时文件的 PID 检查——竞态条件严重（文件存在但进程已死）、无权限写入临时目录时直接失效
- Windows 平台慎用
CreateMutex原生 API——Qt 程序若异常退出，互斥量可能未释放，导致后续启动被误拒
用 QLocalServer 建立命名服务端并拦截后续启动
主程序首次启动时创建 QLocalServer，绑定一个固定名称（如 "myapp-unique-server"）；后续启动时尝试连接该名字的 QLocalSocket，连得上就说明已有实例，此时发送唤醒信号并退出。
关键点在于：服务端需在 QApplication 构造之后、exec() 之前启动，且监听到新连接时要能触发已有窗口的激活逻辑（比如调用 raise() + activateWindow()）：
// 在 main() 中
QApplication app(argc, argv);
MyMainWindow w;
<p>QLocalServer server;
if (!server.listen("myapp-unique-server")) {
// 已有实例：尝试连接并唤醒
QLocalSocket socket;
socket.connectToServer("myapp-unique-server");
if (socket.waitForConnected(500)) {
socket.write("show\n"); // 自定义唤醒协议
socket.waitForBytesWritten(500);
}
return 0; // 退出新进程
}</p><p>// 启动服务端并关联连接处理
QObject::connect(&server, &QLocalServer::newConnection, [&]() {
auto client = server.nextPendingConnection();
QObject::connect(client, &QLocalSocket::readyRead, [=]() {
if (client->canReadLine()) {
QByteArray line = client->readLine().trimmed();
if (line == "show") {
w.raise();
w.activateWindow();
}
}
});
});</p><p>w.show();
return app.exec();</p>
macOS 上还需额外处理 Dock 点击和 Finder 双击
仅靠 QLocalServer 不足以拦截 macOS 的「从 Dock 启动」或「Finder 双击.app」行为——系统会绕过主函数，直接调用 NSApplication 的 applicationShouldHandleReopen 回调。
必须在 main() 之前插入 Objective-C++ 兼容代码，或使用 Qt 提供的 QApplication::setQuitOnLastWindowClosed(false) 配合重写 event() 捕获 QEvent::ApplicationActivate。更稳妥的做法是启用 QtMacExtras 并监听 QMacApplicationEventHandler：
- 确保
.pro文件包含QT += macextras - 在
main()中调用QApplication::setAttribute(Qt::AA_EnableHighDpiScaling)前，先注册事件处理器 - 对
QEvent::ApplicationActivate做响应：即使窗口被最小化，也要raise()+show()
Windows 上防止命令行重复启动时黑窗残留
如果用户在 CMD 中反复执行 myapp.exe，每次失败的新进程会闪出控制台窗口再退出，体验极差。解决方法是在 .pro 文件中添加：
win32 {
CONFIG += console
# 或者彻底隐藏控制台：CONFIG -= console
# 若需日志，改用 OutputDebugString 或写入文件
}
更重要的是，在检测到已有实例后，立即调用 FreeConsole()（Windows API），再 return 0，可避免黑窗出现：
#ifdef Q_OS_WIN #include <windows.h> // ... 检测到已有实例后 FreeConsole(); return 0; #endif </windows.h>
实际部署时，QLocalServer 名称建议加入版本哈希（如 "myapp-v1.2.3-8a2b"），否则升级后新旧版本会互相干扰——用户本意是允许新版覆盖旧版，但当前逻辑会让新版启动失败。
