不知道对面的朋友是不是也经历过这种绝望：FastAPI 服务跑得好好的，一查日志文件却是空的，或者更惨——日志全串成一锅粥，根本看不出哪个请求在哪儿挂了？

之前用 Python 自带的 logging 模块写了一大坨配置，又是 handlers 又是 formatters，结果放进异步协程里直接“精神分裂”。
直到看见那句“Loguru is a library which aims to bring enjoyable logging in Python.”心想：“还能这么玩？赶紧试试...”
好家伙，那种感觉就像手动档开惯了，突然换了一辆自动档性能车——又快又丝滑。

今天咱就来聊聊，在 FastAPI 里怎么把 loguru 用得明明白白，不只要“能跑”，还得“在生产环境稳如泰山”。我会把从踩坑到解脱的全过程讲给你听。🎯

⚡️ 为什么我暂时抛弃了 logging

先说我踩过最大的坑：logging 的默认输出是同步阻塞的，FastAPI 的异步特性一来，日志不但会打乱顺序，还可能悄无声息地丢失。
而且你要拿到一个像样的日志，得先写几十行配置，每次开新项目都要先把以前的代码复制过来，烦得要死。

而 loguru 一上来就告诉我：别折腾了，直接打就行。
它只有一个全局的 logger 对象，装上就能用，彩色控制台输出，自带日期、级别和超好看的格式。一句话：清爽，真的清爽。

这里为什么我说是“暂时”呢？是因为Loguru的魅力在于它直击痛点的简洁。用 logger.add() 一行代码就能搞定输出目标、格式、轮转策略等所有事情。
不过它也存在短板。如果直接代替标准库，可能出现业务代码用Loguru日志，uvicorn服务器依然打官方日志的混乱局面，或是要对标准库日志做好“拦截”，避免重复刷屏。
能用和用好，是完全不同的两个维度。在大型项目里，选择标准 logging，本质上不是因为它更好用，而是因为它能让整个复杂的系统更好地在一起工作，更具确定性和可控性。

所以，对于新项目，建议从 Loguru 起步，享受它的便利。当项目成长为大型/微服务架构时，再将日志系统核心回迁到标准库 logging + dictConfig 上。
或 组合使用，各司其职： Loguru 作用于你的业务代码 + 标准库 logging 作为“基础设施”，兼顾开发体验和生产系统的兼容性。

📦 安装与第一个日志

好，咱们先来安装。就一行：

uv add loguru

然后在 FastAPI 里直接开怼：

from loguru import logger
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def hello():
    logger.info("有人访问了首页，美滋滋")
    return {"msg": "Hello"}

跑起来后，你的终端会立马出现一条带有时间戳、级别和高亮颜色的日志，再也不用对着黑白海量的输出发呆了。

这里有个问题，在正式环境一定不要只往控制台打印，接下来重点来了：怎么把日志稳稳地写到文件里。

🔧 常用配置，一次搞懂

你可能会问：“loguru 写文件是不是又要配一堆东西？”完全不用，一行搞定：

logger.add("app.log", rotation="10 MB", retention="7 days", level="INFO")

你看，rotation 按文件大小自动轮转，retention 自动清理老日志，而且压缩、自定义格式都能在同一个方法里搞定。
这比 logging 的 RotatingFileHandler + TimedRotatingFileHandler 那种套娃组合直观太多了。

但说个容易翻车的点：在 FastAPI 这种异步框架里，千万别漏了 enqueue=True 参数。
官方示例可能没写，但根据我线上血的教训，不加这个参数，多并发下日志写入会阻塞事件循环，轻则响应变慢，重则日志串行甚至丢数据。正确姿势：

logger.add("app.log", rotation="10 MB", retention="7 days",
           level="INFO", enqueue=True)

loguru 会把日志消息扔进一个线程安全的队列，专门有后台线程负责写入，你的主流程该干嘛干嘛，完全不用分心。
这就像点一杯奶茶，小程序下单后不用在店里干等，做好了自然叫你。😊

🧩 和 Uvicorn 的日志整合

是不是以为这样就完了？还有个折磨过我的地方：FastAPI 底层用的 Uvicorn 自己也哗哗地打印日志，两边各玩各的，管理起来特难受。

我的做法是，在应用启动的地方，把 Uvicorn 的日志也“绑架”到 loguru 里来：

import logging
from loguru import logger

class InterceptHandler(logging.Handler):
    def emit(self, record):
        logger_opt = logger.opt(depth=6, exception=record.exc_info)
        logger_opt.log(record.levelname, record.getMessage())

# 在 FastAPI 的 lifespan 或 startup 事件里执行
logging.basicConfig(handlers=[InterceptHandler()], level=0)

这样，所有日志都汇聚到一个口子输出，规则统一，查找问题就像过红绿灯，一次看清。🚦

但在实际开发时，还有个问题就是如果启用了 --reload 模式，或者使用命令 fastapi dev main.py 启动的项目，那有些日志拦截还是会漏掉，
想办法把自定义的 InterceptHandler 拦截的更彻底些：

import logging
from loguru import logger

class InterceptHandler(logging.Handler):
    def emit(self, record):
        # 拿到对应的 loguru 级别
        try:
            level = logger.level(record.levelname).name
        except ValueError:
            level = record.levelno
        
        # 找到调用栈里真正发出日志的地方
        frame, depth = logging.currentframe(), 2
        while frame.f_code.co_filename == logging.__file__:
            frame = frame.f_back
            depth += 1
        
        logger.opt(depth=depth, exception=record.exc_info).log(level, record.getMessage())

# 这里是关键：启动的时候，把 root logger 的所有旧 handler 都干掉，
# 只留我们自己的 InterceptHandler
def setup_logging():
    logging.root.handlers = [InterceptHandler()]
    logging.root.setLevel(logging.INFO)
    
    # 把 uvicorn 那几个 logger 也顺手接管
    for name in ("uvicorn", "uvicorn.access", "uvicorn.error"):
        logging.getLogger(name).handlers = []
        logging.getLogger(name).propagate = True

# 在 FastAPI 应用实例化之前就调用
setup_logging()

⚠️ 这些不足和注意点，请刻在脑子里

loguru 虽香，但也别盲目吹。我总结了几个生产环境必须注意的：

最后啰嗦一句：
有优点，也有不足，这也是为什么前面我说“暂时”替代标准库logging的原因，享受它带来的便利，避开它会引起的坑！
日志是项目上线后你的“眼睛”，花半小时好好配一下，未来无数个深夜调试都会感谢现在的自己。

好啦，今天掏心窝子的分享就到这儿。如果你也被日志折腾过、踩过同样的坑，点个「赞」加个「关注」吧，别让这篇溜走，说不定下次就能帮你省掉一大把掉头发的时间。收藏起来，需要的时候心里不慌。我们下个坑里见～ 🛠️