sys.excepthook是Python中捕获未处理异常的唯一全局入口,需在启动早期重设以确保主线程及后台线程异常均写入日志;须配合threading.excepthook(3.8+)和RotatingFileHandler等机制保障日志完整性与可靠性。

sys.excepthook 是接管未捕获异常的唯一入口
Python 进程中,任何未被 try/except 捕获的异常最终都会流向 sys.excepthook。它不是装饰器或上下文管理器,而是一个可替换的函数对象——默认行为是把 traceback 打印到 sys.stderr。要写入日志文件,必须重置它,且需在程序启动早期(如 main() 开头或模块顶层)完成,否则主线程外的异常(如线程中抛出的)可能仍走默认路径。
常见错误:只改了 logging.basicConfig() 或加了 try/except 包裹主逻辑,但没动 sys.excepthook,结果后台线程崩溃时日志文件里空空如也。
- 重设前先保存原钩子,便于调试时临时恢复:
original_hook = sys.excepthook - 新钩子函数必须接收三个参数:
exc_type、exc_value、exc_traceback - 不要在钩子里调用
logging.exception()(它依赖当前异常上下文,而此处已退出),应手动构造日志消息 - 务必用
logging.getLogger()获取 logger,而非logging.getLogger(__name__)——后者在钩子中可能返回意外命名空间的实例
用 logging.getLogger().critical() 写入结构化日志
直接 print 或写文件缺乏日志级别、时间戳、模块名等关键元信息。正确做法是用 root logger 或显式配置的 logger 调用 critical(),并传入完整 traceback 字符串。注意:不能靠 exc_value 的 str() 表示,它不含堆栈;必须用 traceback.format_exception() 生成完整文本。
import sys import logging import traceback <p>logging.basicConfig( level=logging.CRITICAL, filename="error.log", format="%(asctime)s - %(name)s - %(levelname)s - %(message)s", datefmt="%Y-%m-%d %H:%M:%S" )</p><p>def log_uncaught_exceptions(exc_type, exc_value, exc_traceback): logger = logging.getLogger() logger.critical( "Uncaught exception", exc_info=(exc_type, exc_value, exc_traceback) )</p><p>sys.excepthook = log_uncaught_exceptions </p>
关键点:exc_info= 参数必须是三元组,不能只传 exc_value;否则日志里只有异常类型和消息,没有堆栈行号。
threading.excepthook 需单独处理(Python 3.8+)
从 Python 3.8 开始,threading.excepthook 独立于 sys.excepthook,用于捕获非主线程中未处理的异常。如果不设,这些异常只会打印到 sys.stderr,完全不会进你的日志文件。
- 设置方式与
sys.excepthook类似,但函数签名不同:args是一个命名元组,含exc_type、exc_value、exc_traceback、thread - 推荐复用同一日志逻辑,避免两套实现:
threading.excepthook = lambda args: log_uncaught_exceptions(args.exc_type, args.exc_value, args.exc_traceback) - 低于 3.8 的版本需手动为每个线程设置
threading.Thread(excepthook=...),或改用concurrent.futures并捕获as_completed()中的异常
日志文件权限与轮转容易被忽略
生产环境常因权限问题导致日志写入失败——比如用 systemd 启动服务时,进程用户无权写入 /var/log/ 下的文件;或日志持续增长撑爆磁盘。别依赖 basicConfig(filename=...) 的简单写法。
- 用
RotatingFileHandler替代filename参数,控制单文件大小和备份数:handler = RotatingFileHandler("error.log", maxBytes=10*1024*1024, backupCount=5) - 确认目标目录存在且进程有写权限,否则
basicConfig会静默失败(不报错,也不写日志) - 若用非 root 用户运行,避免硬编码绝对路径,改用相对路径或
os.path.join(os.path.dirname(__file__), "logs", "error.log") - 多进程场景下,多个 Python 进程同时写同一文件会冲突,此时应改用
WatchedFileHandler或集中式日志系统(如 syslog)
最隐蔽的问题是:你测试时一切正常,但上线后发现 error.log 始终为空——八成是权限或路径问题,而不是钩子没生效。
Python免费学习笔记(深入):立即使用
在学习笔记中,你将探索 Python 的核心概念和高级技巧!











