前言

在 Python 项目开发中，print() 只适合临时调试，正式项目必须使用标准库 logging。 logging 支持日志分级、格式化输出、同时打印控制台 + 写入本地文件、灵活过滤日志，是工程开发必备工具。 本文结合代码实例，拆解自定义 logger 完整配置流程，理清日志器、处理器、格式器、日志级别四大核心概念。

目录

前言

一、logging 基础核心概念

1. 五大日志级别（等级从小到大）

2. 四大组件

3. 常用格式占位符

二、完整可运行代码（文中示例源码）

三、运行结果分析（重点！层级过滤规则）

本次代码实际输出

四、两种配置方式对比

方式 1：basicConfig（简易写法，适合小型脚本）

方式 2：自定义 Logger（本文方案，企业项目标准写法）

五、开发常见踩坑点

六、拓展优化方向（可自行扩展）

结语

---

一、logging 基础核心概念

1. 五大日志级别（等级从小到大）

表格

级别	常量	用途
DEBUG	logging.DEBUG	调试信息，开发阶段使用
INFO	logging.INFO	常规运行信息，记录正常流程
WARNING	logging.WARNING	警告，程序可继续运行
ERROR	logging.ERROR	错误，部分功能执行失败
CRITICAL	logging.CRITICAL	致命错误，程序可能终止

规则：设置某个级别后，只输出大于等于该级别的日志。

2. 四大组件

1. Logger（日志器）：日志入口，使用getLogger()创建，推荐命名__name__，避免 root 日志冲突
2. Handler（处理器）：决定日志输出到哪里
   • StreamHandler：输出到控制台
   • FileHandler：输出保存到本地文件
3. Formatter（格式器）：定义日志文本格式
4. Filter（过滤器）：可选，自定义规则过滤日志

3. 常用格式占位符

plaintext

%(name)s     logger实例名称
%(levelname)s 日志级别英文名称
%(message)s   日志主体内容
%(asctime)s   时间戳
%(filename)s  文件名
%(lineno)d    行号

二、完整可运行代码（文中示例源码）

python

运行

import logging

# 1. 创建日志器实例
logger = logging.getLogger(__name__)
# 设置日志器全局最低级别（只是门槛，处理器可以再次限制）
logger.setLevel(logging.DEBUG)

# 2. 控制台处理器：输出到终端
stream_handler = logging.StreamHandler()
# 单独设置控制台输出级别
stream_handler.setLevel(logging.INFO)
# 定义日志格式
stream_formatter = logging.Formatter('%(name)s %(levelname)s %(message)s')
stream_handler.setFormatter(stream_formatter)
# 将处理器绑定到logger
logger.addHandler(stream_handler)

# 3. 文件处理器：日志写入 log.txt
file_handler = logging.FileHandler('log.txt', encoding="utf-8")
# 文件日志单独设置级别
file_handler.setLevel(logging.WARNING)
file_formatter = logging.Formatter('%(name)s %(levelname)s %(message)s')
file_handler.setFormatter(file_formatter)
logger.addHandler(file_handler)

# 测试输出日志
logger.debug("debug")
logger.warning("warning")
logger.error("error")

三、运行结果分析（重点！层级过滤规则）

1. logger.setLevel(logging.DEBUG) 日志器接收所有 ≥ DEBUG 的日志，但不代表一定会打印，最终输出受处理器控制。
2. 控制台处理器：INFO级别 只会输出：INFO、WARNING、ERROR、CRITICAL 👉 debug 日志不会打印在控制台
3. 文件处理器：WARNING级别 只会输出：WARNING、ERROR、CRITICAL 👉 debug、info 不会写入 log.txt

本次代码实际输出

控制台输出：

plaintext

__main__ WARNING warning
__main__ ERROR error

log.txt 文件内容：

plaintext

__main__ WARNING warning
__main__ ERROR error

💡关键知识点： Logger 级别 → 第一道过滤；Handler 级别 → 第二道过滤。两道关卡都要满足，日志才会最终输出。

四、两种配置方式对比

方式 1：basicConfig（简易写法，适合小型脚本）

优点：代码简短 缺点：只能创建一个默认 root 日志器，不支持多处理器差异化级别，大型项目不推荐

python

运行

import logging
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s %(filename)s[line:%(lineno)d] %(levelname)s %(message)s',
    handlers=[
        logging.StreamHandler(),
        logging.FileHandler("log.txt",encoding="utf-8")
    ]
)

方式 2：自定义 Logger（本文方案，企业项目标准写法）

✅ 支持控制台、文件设置不同日志级别 ✅ 可以创建多个独立日志器，互不干扰 ✅ 格式灵活配置，扩展性强 生产环境优先使用这种写法。

五、开发常见踩坑点

1. 重复打印日志：多次 addHandler，避免函数反复执行添加处理器
2. 中文乱码：FileHandler 务必指定 encoding="utf-8"
3. 级别混淆：很多新手误以为设置 logger 级别就万事大吉，忘记 handler 也有独立级别
4. 不要直接使用 logging.debug()，会使用 root 日志器，项目模块化推荐 getLogger(__name__)

六、拓展优化方向（可自行扩展）

1. 使用 RotatingFileHandler / TimedRotatingFileHandler，实现日志分割，防止单个日志文件过大
2. 封装日志工具类，统一项目日志配置
3. 增加日志颜色，美化控制台输出
4. 增加 Filter，根据内容过滤日志

结语

logging 是 Python 开发必备基础能力，区分日志器、处理器两级过滤逻辑是理解难点。 当你需要同时控制台看简洁日志、文件保存更重要的告警错误日志时，本文这种多 Handler 方案就是最优选择。