本文介绍如何在 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 键退出应用...')✅ 注意事项与最佳实践：
立即学习“Python免费学习笔记（深入）”；
- 命名空间选择：使用 'Global\MyMutex'（而非默认会话命名空间）可确保不同用户会话下的进程也能互斥（适用于服务场景）；若仅限当前用户，可用 'MyMutex'。
- 异常退出保护：即使主逻辑崩溃，__exit__ 和 __del__ 仍会尝试释放 Mutex；但极端情况下（如强制 kill 进程），系统会自动回收句柄并触发 WAIT_ABANDONED，本方案已妥善处理该情况。
- 跨平台兼容性：此方案仅适用于 Windows。Linux/macOS 可改用文件锁（fcntl.flock）或 socket.bind() 占用端口的方式实现类似逻辑，但无原生 Mutex 等价物。
- 调试建议：避免在 IDE 中逐行调试互斥量逻辑（如 VS Code 的断点可能干扰句柄生命周期），应通过终端直接运行 python app.py 测试多实例行为。
总结来说，实现“等待式单实例”的核心是：创建即占有 + 显式等待 + 安全释放。只要确保 Mutex 所有权链清晰可控，就能稳定支撑生产环境中的串行化任务调度需求。
