本文详解如何在 windows 平台使用互斥量（mutex）实现 python 应用的单实例控制，并确保后续启动的应用自动阻塞等待前一实例退出后再继续执行，避免死锁和 `getlasterror()` 误判问题。
在开发桌面级或服务型 Python 应用时，常需保证同一时刻仅有一个进程运行。但与简单“检测并退出”的单实例模式不同，某些场景（如批处理任务续跑、UI 应用排队响应）要求：新启动的实例不立即退出，而是挂起等待，直到前一个实例完全释放资源后才开始执行。这需要正确使用 Windows 互斥量（Mutex）的“所有权”与“等待”机制。
核心问题在于：原始代码中调用 CreateMutex(None, False, ...) 创建了互斥量，但未尝试获取其所有权（即未“进入”该互斥量），导致 WaitForSingleObject 无法生效；同时，GetLastError() 在多线程/多进程竞争下易受干扰，不应作为主逻辑判断依据。
✅ 正确做法是：
- 首次创建时即以 bInitialOwner=True 获取所有权（关键！）；
- 若互斥量已存在，则调用 WaitForSingleObject 阻塞等待其被释放；
- 显式调用 ReleaseMutex 确保资源干净释放；
- 妥善处理 WAIT_ABANDONED（前实例异常崩溃未释放）等边界情况。
以下是经过生产验证的完整实现（依赖 pywin32）：
bee餐饮点餐外卖小程序是针对餐饮行业推出的一套完整的餐饮解决方案，实现了用户在线点餐下单、外卖、叫号排队、支付、配送等功能，完美的使餐饮行业更高效便捷！功能演示：1、桌号管理登录后台，左侧菜单 “桌号管理”，添加并管理你的桌号信息，添加以后在列表你将可以看到 ID 和 密钥，这两个数据用来生成桌子的二维码2、生成桌子二维码例如上面的ID为 308，密钥为 d3PiIY，那么现在去左侧菜单微信设置
立即学习“Python免费学习笔记（深入）”；
import win32event as evt
import win32api as api
ERROR_ALREADY_EXISTS = 183 # pywin32 未导出，需手动定义
class SingleInstance:
def __init__(self, mutex_name: str = "Global\\MyApp_SingleInstance"):
self.Mutex = None
self.mutex_name = mutex_name
try:
# 关键：bInitialOwner=True → 创建即持有，否则无法等待
self.Mutex = evt.CreateMutex(None, True, self.mutex_name)
last_error = api.GetLastError()
if last_error == ERROR_ALREADY_EXISTS:
print("⚠️ 检测到另一实例正在运行，等待其结束...")
# 无限期等待互斥量释放（正常退出）或被遗弃（崩溃）
wait_result = evt.WaitForSingleObject(self.Mutex, evt.INFINITE)
if wait_result == evt.WAIT_OBJECT_0:
print("✅ 前一实例已正常退出，当前实例开始执行")
elif wait_result == evt.WAIT_ABANDONED:
print("❗ 前一实例异常终止，互斥量已被系统回收，继续执行")
else:
raise RuntimeError(f"WaitForSingleObject 返回异常状态: {wait_result}")
elif last_error != 0:
raise RuntimeError(f"CreateMutex 失败，错误码: {last_error}")
except Exception as e:
if self.Mutex:
api.CloseHandle(self.Mutex)
raise e
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_val, exc_tb):
self.release()
# ✅ 使用示例：with 语句确保自动清理
if __name__ == "__main__":
try:
with SingleInstance("Global\\MySecureApp_v1"):
print("? 应用主逻辑开始执行...")
input("应用运行中，请按 ENTER 键退出：")
print("? 应用已安全退出。")
except Exception as e:
print(f"❌ 应用启动失败: {e}")? 关键注意事项：
- 命名空间选择：使用 "Global\\" 前缀确保互斥量跨会话可见（适用于多用户环境）；若仅限当前会话，可用 "Local\\"；
- 异常健壮性：WAIT_ABANDONED 表示前一实例崩溃未释放互斥量，此时系统已自动授予当前进程所有权，可安全继续；
- 资源泄漏防护：__del__ 和 __exit__ 双重保障句柄关闭，但推荐始终使用 with 语句以获得确定性清理；
- 跨平台替代方案：Linux/macOS 可用文件锁（fcntl.flock）或 socket.bind() 占用端口模拟互斥，但无原生“等待释放”语义，需轮询+超时。
该方案已在 Windows 10/11 + Python 3.8–3.12 环境中稳定运行，支持 VS Code 调试及命令行直接双击/重复执行，彻底解决“永远卡在 Waiting...”问题。
