日志记录 (Logging)

---

本文将介绍如何控制由 Flet 库及其底层组件生成的日志消息的日志级别（log level）。在对 Flet 库本身进行排查故障或准备提交新的 Flet issue 问题时，你可能需要启用详细的日志记录。

---

Python 日志记录器 (Python)

Flet Python 内部使用了以下命名的日志记录器（loggers）：

• flet —— 框架常规行为和数据传输日志。
• flet_object_patch —— 详细的底层控件树 diff/patch 差异日志。
• flet_components —— 声明式自定义组件（@component）的生命周期日志。

在开发过程中，flet run 可以自动为你开启日志：-v 对应 INFO， -vv 对应 DEBUG。它会通过 FLET_LOG_LEVEL 将级别传递给你的应用， 这样无需修改应用代码即可在反馈问题时上报日志。

在应用中自行配置日志的优先级高于该变量，因此本文其余部分内容保持不变。

对于常规开发使用，在调用 ft.run() 启动应用之前，进行如下日志基本配置即可：

import logging

logging.basicConfig(level=logging.INFO)

这可以向你输出普通的 Flet 运行日志，而不会夹杂太多噪音。

查看详细日志

如果你想要查看 flet 主日志记录器的更多详细底层诊断信息，可以直接提升根日志（root logger）的级别：

import logging

logging.basicConfig(level=logging.DEBUG)

或者也可以单独显式设置 flet 记录器的级别，而保持根级别为 INFO 以免引入其他库的过多调试日志：

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("flet").setLevel(logging.DEBUG)

请注意，flet_object_patch 和 flet_components 会在初始化时将其自身的级别显式覆盖设置为 INFO，因此除非你显式对它们进行开启，否则它们不会直接继承根日志的 DEBUG 级别。

开启极尽详细诊断

如果要启用最完整详细的诊断日志，请将上述对应的各个日志记录器显式设置为 DEBUG 级别：

import logging

logging.basicConfig(level=logging.DEBUG)
logging.getLogger("flet_object_patch").setLevel(logging.DEBUG)
logging.getLogger("flet_components").setLevel(logging.DEBUG)

请只在需要调试非常棘手的问题或者准备给 Flet 官方提交 issue 报告时，才启用该日志级别。

---

内置 Web 服务器 (Built-in Web Server)

在运行网页（Web）应用时，Flet 会在 FastAPI 和 Uvicorn 的基础上启动其内置的网页传输通道。

Flet Python 日志记录器的生效级别会自动传递并应用于该内置网页服务器，因此请在启动应用之前配置好 Flet 的日志级别：

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("flet").setLevel(logging.DEBUG)

如果你是在自己的 ASGI 服务器进程（例如手动的命令行 uvicorn 或 gunicorn）上托管运行 Flet ASGI 应用，请根据该服务器程序各自本身的配置选项来单独进行服务器日志级别的配置。