Python 中实现单实例应用并等待前一个实例完成的完整方案

本文详解如何在 windows 平台使用互斥量（mutex）实现 python 应用的“单实例 + 排队等待”机制，解决第二个进程无限卡在等待状态的问题，关键在于正确获取并释放互斥量所有权。

在开发桌面工具或后台服务类 Python 应用时，常需确保同一时刻仅有一个实例运行；但与简单“检测后退出”的单实例模式不同，某些场景（如批处理任务、GUI 工具链）要求后续启动的实例主动等待前一个实例结束后再执行——这需要互斥量（Mutex）的所有权语义与同步等待能力，而非仅靠创建失败判断。

原始代码的核心缺陷在于：调用 CreateMutex(None, False, ...) 时传入了 bInitialOwner=False（即不获取所有权），导致即使本进程成功创建了互斥量，也无法通过 WaitForSingleObject 等待其被释放（因为未持有句柄所有权，系统不会将其视为“可等待对象”）。而当另一进程已持有该 Mutex 时，本进程虽能检测到 ERROR_ALREADY_EXISTS，却因未正确调用 WaitForSingleObject 进入阻塞等待，而是陷入轮询 time.sleep(5) 的低效循环，且未处理句柄清理逻辑，极易引发资源泄漏或状态不一致。

以下是经过验证、生产可用的解决方案（基于 pywin32）：

import win32event as evt
import win32api as api

ERROR_ALREADY_EXISTS = 183  # pywin32 未导出此常量，需手动定义

class SingleInstance:
    def __init__(self):
        # 关键：bInitialOwner=True → 创建即获取所有权
        self.Mutex = evt.CreateMutex(None, True, 'Global\\MyMutex')
        last_error = api.GetLastError()

        if last_error == ERROR_ALRE
ADY_EXISTS:
            print('另一个实例正在运行，当前实例将等待其结束...')
            # 阻塞等待互斥量被释放（INFINITE 表示永久等待）
            wait_result = evt.WaitForSingleObject(self.Mutex, evt.INFINITE)

            # 注意：需同时处理正常释放（WAIT_OBJECT_0）和异常终止（WAIT_ABANDONED）
            if wait_result in (evt.WAIT_OBJECT_0, evt.WAIT_ABANDONED):
                print('前一实例已退出，当前实例开始执行。')
            else:
                raise RuntimeError(f'等待互斥量失败，错误码：{wait_result}')
        else:
            # 本进程是首个实例，已自动持有 Mutex，无需额外操作
            print('首次启动，获得执行权限。')

    def release(self):
        """安全释放互斥量资源"""
        if self.Mutex is not None:
            try:
                evt.ReleaseMutex(self.Mutex)  # 释放所有权
            except Exception:
                pass  # 若已被释放，忽略错误
            finally:
                api.CloseHandle(self.Mutex)
                self.Mutex = None

    def __del__(self):
        self.release()

    def __enter__(self):
        return self

    def __exit__(self, exc_type, exc_value, traceback):
        self.release()

# 使用示例：确保资源自动释放
if __name__ == '__main__':
    with SingleInstance():
        print('✅ 应用程序主体逻辑开始执行...')
        # 此处放置你的主业务代码（如 GUI 启动、文件处理等）
        input('应用正在运行，请按 ENTER 键退出：')
        print('? 应用已退出，互斥量自动释放。')

✅ 关键要点说明：

• bInitialOwner=True 是核心：它确保创建 Mutex 的进程立即成为其所有者，使 WaitForSingleObject 能真正进入等待队列；若为 False，则仅做存在性检查，无法同步。
• 命名空间建议加 'Global\\' 前缀：避免会话隔离问题（尤其在远程桌面或服务环境下），确保跨会话唯一性。
• 必须调用 ReleaseMutex()：否则当进程异常退出时，Mutex 可能处于 ABANDONED 状态，后续等待者需能识别并继续执行（本例已处理）。
• 推荐使用 with 语句：利用上下文管理器保障 __exit__ 中的 release() 必然执行，杜绝资源泄露风险。
• Linux/macOS 用户注意：本方案为 Windows 专属；跨平台需求应改用文件锁（如 portalocker）或进程名检查 + 信号通信，但无法实现真正的“等待完成”语义。

通过以上实现，多个 python app.py 进程将严格串行执行：第二个实例启动后立即阻塞，直至第一个实例完全退出并释放 Mutex，随后自动唤醒并执行自身逻辑——真正满足“应用必须等待另一个完成”的设计目标。