Python日志配置详解与实战

本文深入讲解了Python日志格式配置的核心方法与最佳实践，涵盖从快速上手的`basicConfig`到灵活可控的`Formatter+Handler`组合方案，强调时间戳、日志级别、模块名、行号及函数名等关键字段的结构化输出，兼顾开发调试的可读性与生产环境的机器可解析性；同时提醒读者注意调用时机、第三方库适配、多目标输出差异、中文编码、颜色处理等易踩坑细节，为个人脚本和团队项目提供了一套清晰、健壮且可落地的日志规范化指南。

Python中配置日志格式，核心是通过logging.basicConfig()或Formatter对象定义输出样式，让所有日志具备时间、级别、模块名、行号和消息等统一字段，便于排查问题和集中采集。

用basicConfig快速统一基础格式

适合脚本或简单项目，一行代码即可生效（注意：仅首次调用有效）：

import logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s [%(levelname)-5s] %(name)s:%(lineno)d - %(message)s',
    datefmt='%Y-%m-%d %H:%M:%S'
)

说明：

• %(asctime)s：自动注入格式化后的时间，依赖datefmt
• [%(levelname)-5s]：左对齐、占5字符宽的级别名（如 INFO、ERROR）
• %(name)s：记录器名（默认为root，可自定义）
• %(lineno)d：日志所在源码行号，调试时非常关键
• 该配置会影响所有未单独设置handler的logger

用Formatter+Handler精细控制多输出目标

当需同时输出到控制台和文件，并且格式/级别不同，推荐显式创建Handler：

import logging
<p>logger = logging.getLogger('myapp')
logger.setLevel(logging.DEBUG)</p><h1>控制台输出（简洁格式）</h1><p>console_handler = logging.StreamHandler()
console_formatter = logging.Formatter(
'%(levelname)s - %(message)s'
)
console_handler.setFormatter(console_formatter)
logger.addHandler(console_handler)</p><h1>文件输出（完整格式，含时间与位置）</h1><p>file_handler = logging.FileHandler('app.log', encoding='utf-8')
file_formatter = logging.Formatter(
'%(asctime)s | %(levelname)-8s | %(name)s:%(funcName)s:%(lineno)d | %(message)s',
datefmt='%Y-%m-%d %H:%M:%S'
)
file_handler.setFormatter(file_formatter)
logger.addHandler(file_handler)</p>

关键点：

• 每个Handler可绑定独立Formatter，实现“同日志、不同展现”
• %(funcName)s能显示函数名，比%(name)s更准确定位逻辑位置
• 文件Handler建议加encoding='utf-8'避免中文乱码
• 务必调用logger.addHandler()，否则日志不会输出到该目标

统一规范建议（团队协作推荐）

为保障日志可读性与机器可解析性，建议固定以下字段顺序和格式：

• 时间戳：%(asctime)s + datefmt='%Y-%m-%dT%H:%M:%S'（ISO 8601，利于ELK解析）
• 日志级别：[%(levelname)-5s]，大写、左对齐、固定宽度
• 模块标识：%(name)s（按模块命名logger，如logging.getLogger(__name__)）
• 代码位置：%(filename)s:%(lineno)d 或 %(module)s.%(funcName)s:%(lineno)d
• 业务消息：%(message)s，避免换行，关键参数用logger.info("user_id=%s, action=%s", uid, action)结构化传入

避免常见坑

实际配置中容易忽略的细节：

• basicConfig()必须在任何logger.xxx()之前调用，否则无效
• 若使用第三方库（如requests、sqlalchemy），它们自带logger，需单独设置其level（如logging.getLogger("requests").setLevel(logging.WARNING)）
• 生产环境禁用StreamHandler，优先写文件或对接Syslog/Fluentd
• 不要在format字符串里硬编码颜色或ANSI序列——终端渲染应由Handler（如colorlog）负责，而非Formatter

今天关于《Python日志配置详解与实战》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！