Python 日志记录完全指南：从基础到最佳实践

2026-02-12 03:00:45 0条评论 4次阅读 0人点赞

作为一名开发者，我们深知代码的调试和维护是开发周期中至关重要的一环。你是否曾遇到过这样的情况：程序在测试环境中运行完美，但在生产环境却莫名崩溃？或者，当用户报告一个错误时，你却因为缺乏运行时信息而束手无策？

这正是日志记录 发挥作用的地方。在这篇文章中，我们将深入探讨 Python 内置的强大日志模块。我们将不再仅仅依赖 print() 语句，而是学习如何构建一个专业、可配置且高效的日志系统。无论你是编写小型脚本还是大型企业级应用，掌握日志记录都将极大地提升你的调试效率和系统可维护性。

为什么我们需要日志？

在初学阶段，我们习惯使用 print() 函数来输出变量的值或检查程序的流程。这在简单的脚本中虽然有效，但在复杂系统中显得力不从心。日志记录提供了以下几个核心优势：

分级控制：我们可以区分信息的轻重缓急（如调试信息、错误警报），而不仅仅是输出所有内容。
持久化存储：日志可以被写入磁盘文件或发送到远程服务器，以便事后分析。
运行时灵活性：可以在不修改代码的情况下，通过配置文件调整日志的详细程度。

1 基础用法：快速上手
2 理解日志的五个级别
3 记录变量数据：追踪状态
4 深入探索：Handler（处理器）与 Logger（记录器）
5 综合实战：记录所有级别
6 常见陷阱与最佳实践
7 总结与后续步骤

基础用法：快速上手

让我们从最基础的例子开始。Python 的 logging 模块是标准库的一部分，因此无需安装任何额外的东西。

示例 1：最简单的日志记录

import logging

# 配置日志的最基本设置：设置级别为 INFO
logging.basicConfig(level=logging.INFO)

project_name = "MyProject"
# 输出一条错误信息
logging.error(‘%s raised an error‘, project_name)

输出：

> ERROR:root:MyProject raised an error

代码解析：

import logging：导入 Python 内置的日志模块。
project_name = ‘MyProject‘：定义我们要在日志中使用的变量。
INLINECODE6d4f1113：记录一条严重级别为 ERROR 的消息。注意，我们使用了字符串格式化（INLINECODE3156c608），这是一种推荐的做法，因为它只在日志实际需要输出时才会进行字符串拼接，从而节省性能。

理解日志的五个级别

在 Python 的 logging 模块中，消息的严重程度分为五个标准级别。理解这些级别对于写出有条理的日志至关重要。

级别

数值

使用场景

描述

:—

DEBUG

诊断问题

最详细的信息，通常仅在开发时关注。

INFO

确认正常

表明事情按预期工作。

WARNING

意外情况

指示发生了意想不到的事情（如“磁盘空间不足”），但软件仍在运行。

ERROR

严重问题

由于更严重的问题，软件无法执行某些功能。

CRITICAL

严重错误

表明程序本身可能无法继续运行的严重错误。示例 2：演示不同的日志级别

我们可以通过设置日志级别来过滤输出。例如，如果我们将级别设置为 INLINECODEde25ccee，那么 INLINECODE752db921 和 INFO 级别的消息将被忽略。

import logging

# 这里我们将级别设置为 WARNING，因此只有 WARNING 及以上级别的消息会被打印
logging.basicConfig(level=logging.WARNING)

logging.debug("这是调试信息 - 你看不到我")
logging.info("这是普通信息 - 你也看不到我")
logging.warning("这是一个警告！你应该能看到我。")
logging.error("这是一个错误！")

记录变量数据：追踪状态

日志不仅仅是输出固定的文本，更重要的是记录程序运行时的数据状态。让我们看看如何在日志中优雅地记录变量。

示例 3：记录变量与格式化输出

import logging

# 配置日志格式，只显示级别和消息
logging.basicConfig(format=‘%(levelname)s: %(message)s‘, level=logging.INFO)

age = 25
user_id = 1012

# 使用 %d 格式化整数
logging.info("用户 ID: %d 的年龄是 %d 岁", user_id, age)

# 如果数据量很大，可以使用字典方式
user_data = {"name": "Alice", "status": "Active"}
logging.info("当前用户状态: %s", user_data)

输出：

> INFO: 用户 ID: 1012 的年龄是 25 岁

> INFO: 当前用户状态: {‘name‘: ‘Alice‘, ‘status‘: ‘Active‘}

核心技巧：

请注意我们在 INLINECODE76ed0c59 中使用了占位符（INLINECODE40bb880b, INLINECODEef079953）而不是直接使用 f-string（如 INLINECODEb329d542）。这是 Python 日志的一个最佳实践。INLINECODE8e193ed1 模块会延迟字符串的格式化操作。如果当前日志级别不需要输出该条消息（例如 INLINECODEb51af70e 级别被关闭了），那么字符串拼接的计算成本就不会产生，这在高频循环中能显著提升性能。

深入探索：Handler（处理器）与 Logger（记录器）

当我们需要更复杂的控制时（例如将日志同时输出到控制台和文件），仅仅使用 INLINECODE5f5f8bb7 就不够了。我们需要理解 INLINECODE75efaa81、INLINECODE008fff69 和 INLINECODEec1cb9a2 的关系。

常用处理器

处理器决定了日志消息的“去向”。以下是几种最常用的处理器：

StreamHandler：将日志发送到类流对象（通常是 INLINECODE37e9c4b4 或 INLINECODE5510c40a，即控制台）。
FileHandler：将日志发送到磁盘文件。这是最常见的持久化方式。
RotatingFileHandler：当你担心日志文件过大时，这个处理器可以帮你。当文件达到一定大小时，它会自动创建新文件，并限制保留的文件数量。

示例 4：将日志写入文件

让我们看一个实际场景：我们将所有 INFO 级别以上的日志保存到 application.log 文件中。

import logging

# 1. 创建一个 logger 对象（通常以模块名命名）
logger = logging.getLogger("MyAppLogger")
logger.setLevel(logging.DEBUG) # 设置 logger 的最低级别

# 2. 创建一个 FileHandler，指定日志文件名
file_handler = logging.FileHandler("app.log")

# 3. (可选) 设置日志格式
formatter = logging.Formatter(‘%(asctime)s - %(name)s - %(levelname)s - %(message)s‘)
file_handler.setFormatter(formatter)

# 4. 将 handler 添加到 logger
logger.addHandler(file_handler)

# 5. 现在我们可以使用 logger 对象来记录日志了
logger.debug("这条消息用于调试，会被写入文件")
logger.info("程序已成功启动")
logger.error("检测到配置文件缺失")

代码解析：

INLINECODE39ac8c66：获取一个特定的记录器实例。建议使用模块名或应用名，而不是使用 INLINECODE21fe1c34 记录器，这样可以避免与其他库的日志冲突。
logger.setLevel(logging.DEBUG)：即使文件只接受 ERROR，logger 本身也必须允许 DEBUG 消息通过。
logger.addHandler(file_handler)：这是连接管道的关键步骤，将处理器“挂载”到记录器上。

运行此代码后，你会在当前目录下找到一个 app.log 文件，里面包含了上述三条日志记录。

综合实战：记录所有级别

在大型项目中，我们通常需要记录从 Debug 到 Critical 的所有信息，并包含时间戳，以便排查故障发生的精确时间。

示例 5：完整的日志配置实战

下面的代码演示了如何配置一个包含时间戳、级别和消息的完整日志系统，并尝试写入文件。

import logging

# 配置 basicConfig
# filename: 指定日志文件
# filemode=‘w‘: ‘w‘ 模式会覆盖旧文件，‘a‘ (默认) 则是追加
# format: 自定义每条日志的格式
logging.basicConfig(
    filename="complete_log.log",
    filemode="w", # 为了演示效果，这里使用 ‘w‘ 覆盖模式
    format=‘%(asctime)s - %(levelname)s: %(message)s‘,
    level=logging.DEBUG
)

logger = logging.getLogger()

# 演示不同级别的日志
logger.debug("这是无害的调试信息，通常用于开发阶段")
logger.info("程序正常启动，加载配置文件中...")
logger.warning("发现警告：连接响应时间过长 (>500ms)")
logger.error("发生错误：尝试除以零")
logger.critical("严重错误：数据库连接丢失，服务停止")

输出内容 (在 complete_log.log 中):

> 2023-10-27 10:00:00,123 – DEBUG: 这是无害的调试信息，通常用于开发阶段

> 2023-10-27 10:00:00,124 – INFO: 程序正常启动，加载配置文件中…

> 2023-10-27 10:00:00,125 – WARNING: 发现警告：连接响应时间过长 (>500ms)

> 2023-10-27 10:00:00,126 – ERROR: 发生错误：尝试除以零

> 2023-10-27 10:00:00,127 – CRITICAL: 严重错误：数据库连接丢失，服务停止

关键点解释：

%(asctime)s：自动插入人类可读的时间戳。
INLINECODE58333937：在演示中这很有用，但在实际生产环境中，通常省略此参数（默认为追加模式 ‘a‘）或使用 INLINECODEa1ab3dd8，以免每次重启程序都丢失之前的日志。

常见陷阱与最佳实践

在与无数开发者交流的经验中，我们总结了一些在 Python 日志记录中常见的错误及其解决方案：

1. 避免在库代码中配置 basicConfig

如果你正在编写一个库（供其他人使用的包），千万不要在代码中调用 logging.basicConfig。这会强制使用你库的用户采用你的日志配置。最佳实践是仅仅创建一个 logger 并使用它，让应用程序的使用者去决定如何配置日志。

2. 捕获异常信息

仅仅记录 INLINECODE69075fd4 往往是不够的。我们需要知道具体的堆栈跟踪。使用 INLINECODE914dc4fb 参数或 .exception() 方法。

import logging

try:
    result = 1 / 0
except ZeroDivisionError:
    # 方法 A：使用 exc_info=True 自动附带异常信息
    logging.error("计算失败", exc_info=True)
    
    # 方法 B：专门用于异常的方法，等同于 logging.error(..., exc_info=True)
    logging.exception("检测到除以零错误")

3. 处理中文编码问题

在 Windows 系统下，如果不正确配置，将包含中文的日志写入文件可能会遇到 INLINECODEf9d1bf20。确保在 INLINECODE75bb5cc5 中指定编码格式。

# Python 3 推荐做法
file_handler = logging.FileHandler("chinese_log.log", encoding="utf-8")

总结与后续步骤

在这篇文章中，我们一起探索了 Python 日志记录的各个方面，从基础的五个级别到复杂的 Logger 和 Handler 配置。掌握这些技能后，你将能够：

快速定位 Bug：通过分级日志和文件记录，迅速缩小问题范围。
监控系统健康：通过 WARNING 和 ERROR 日志监控生产环境的稳定性。
编写专业代码：告别漫天飞的 print 语句，拥抱工业级的日志标准。

给你的建议：

在你下一个项目中，尝试从一开始就规划好日志策略。为你的应用配置一个独立的 Logger，规定好文件存放位置，并养成记录关键操作（如数据库连接、外部 API 调用、关键计算步骤）的习惯。

如果你对日志的配置文件（如 dictConfig）或者如何将日志发送到远程服务器（如 ELK Stack）感兴趣，我们建议你进一步深入研究官方文档或参考更高级的架构模式。祝你编码愉快，日志常青！

投稿给我们	如何建站？
vps是什么？	如何安装宝塔？
如何通过博客赚钱？	便宜wordpress托管方案
免费wordpress主题	这些都是免费方案

豆丁博客