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

本文介绍如何在 windows 平台上使用互斥量（mutex）确保 python 应用仅运行一个实例，并让后续启动的进程主动等待前一实例退出后再继续执行，解决因未正确获取/释放所有权导致的无限等待问题。

在开发桌面级或后台服务类 Python 应用时，常需保证同一时刻仅有一个进程在运行（例如防止重复写入日志、冲突访问共享资源等）。单纯“检测是否存在”（如 ActiveState 示例）只能让第二个实例立即退出；而实际业务中，我们往往需要阻塞等待——即新启动的进程暂停执行，直到前一个实例正常结束、释放资源后才继续运行。这要求对 Windows 互斥量（Mutex）进行更精确的控制。

关键在于：创建互斥量时必须“立即获取其所有权”，否则 WaitForSingleObject 将无法感知其状态变化。原代码中调用 CreateMutex(None, False, ...) 以 bInitialOwner=False 创建，意味着即使当前进程成功创建了 Mutex，也并未持有它，导致后续 WaitForSingleObject 始终处于无效等待（因为对象未被任何线程拥有，也就谈不上“被释放”）。

以下是经过验证的完整实现（依赖 pywin32）：

import win32event as evt
import win32api as api

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

class SingleInstance:
    def __init__(self):
        # 关键：bInitialOwner=True → 创建即占有，确保 WaitForSingleObject 可响应
        self.Mutex = evt.CreateMutex(None, True, 'Global\\MyMutex')
        last_error = api.GetLastError()

        if last_error == ERROR_ALREADY_EXISTS:
            print('另一个实例正在运行，等待其退出...')
   
         # 无限期等待互斥量被释放（前一实例调用 ReleaseMutex 或进程终止）
            wait_result = evt.WaitForSingleObject(self.Mutex, evt.INFINITE)

            # 注意：WAIT_ABANDONED 表示前一实例异常终止但未释放 Mutex，
            # 系统已自动授予当前进程所有权，仍可安全继续
            if wait_result in (evt.WAIT_OBJECT_0, evt.WAIT_ABANDONED):
                print('前一实例已退出，继续执行...')
            else:
                raise RuntimeError(f'等待互斥量失败: {wait_result}')
        # 若创建成功（无冲突），则当前进程已持有 Mutex，无需额外操作

    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()

# 使用示例：配合 with 语句确保资源安全释放
if __name__ == '__main__':
    with SingleInstance():
        print('✅ 应用已启动，当前为唯一运行实例')
        input('按 ENTER 键退出应用...')

✅ 注意事项与最佳实践：

• 命名空间选择：使用 'Global\\MyMutex'（而非默认会话命名空间）可确保不同用户会话下的进程也能互斥（适用于服务场景）；若仅限当前用户，可用 'MyMutex'。
• 异常退出保护：即使主逻辑崩溃，__exit__ 和 __del__ 仍会尝试释放 Mutex；但极端情况下（如强制 kill 进程），系统会自动回收句柄并触发 WAIT_ABANDONED，本方案已妥善处理该情况。
• 跨平台兼容性：此方案仅适用于 Windows。Linux/macOS 可改用文件锁（fcntl.flock）或 socket.bind() 占用端口的方式实现类似逻辑，但无原生 Mutex 等价物。
• 调试建议：避免在 IDE 中逐行调试互斥量逻辑（如 VS Code 的断点可能干扰句柄生命周期），应通过终端直接运行 python app.py 测试多实例行为。

总结来说，实现“等待式单实例”的核心是：创建即占有 + 显式等待 + 安全释放。只要确保 Mutex 所有权链清晰可控，就能稳定支撑生产环境中的串行化任务调度需求。