运行 Flet 应用 (热重载)

Flet 应用可以使用 flet run 命令以桌面应用或 Web 应用的形式执行。运行该命令将分别在原生操作系统窗口或 Web 浏览器中启动应用，并启用**热重载 (hot reload)**以实时查看代码更改。

桌面应用 (Desktop app)

要将 Flet 应用作为桌面应用运行，请使用以下命令：

uv

uv run flet run

pip

flet run

默认情况下，当您运行不带任何参数的命令时，将执行当前目录中的 main.py 脚本。

如果您需要提供不同的路径，请使用以下命令：

uv

uv run flet run [脚本]

pip

flet run [脚本]

其中 [脚本] 可以是您想要运行的 Python 脚本的相对路径（例如：counter.py）或绝对路径（例如：/Users/john/projects/flet-app/main.py）。

该应用程序将在原生操作系统窗口中启动：

macOS

Windows

---

桌面客户端是如何被选中的

一个桌面 Flet 应用由两部分组成：你的 Python 代码，以及负责显示 UI 的 Flutter 客户端。当你运行 flet run，或用 python main.py 启动一个调用 ft.run(main) 的脚本时，Flet 会按以下顺序查找桌面客户端：

1. 在当前工作目录下的 build/<平台> 中，来自上一次 flet build 的客户端，例如 build/windows、build/macos 或 build/linux。
2. 由 FLET_VIEW_PATH 指定的目录中的客户端。
3. 缓存在 ~/.flet/client/ 中的标准预构建 Flet 客户端（如需要则自动下载）。

复用本地构建的客户端，可以运行带有自定义 Flutter 扩展的应用。你当前的 Python 源码依旧会运行：Flet 启动客户端，并将其连接到该 Python 进程。例如，在执行 flet build windows 之后，你可以编辑 main.py 并运行 flet run main.py 而无需重新构建。build/windows 中的可执行文件提供 UI 客户端；构建时打包进去的 Python 代码在此模式下不会被使用。

当你新增或修改 Flutter 扩展时需要重新构建。仅修改 Python 则无需重建客户端。示例参见 创建扩展。

当 Flet 使用来自 build/<平台> 的客户端时，会打印一条包含该客户端路径的警告。要重新使用标准客户端，请移动、重命名或删除对应的 build/<平台> 目录，并清除（如已设置）FLET_VIEW_PATH。仅设置 FLET_VIEW_PATH 不会覆盖在 build/<平台> 中找到的客户端。

INFO

直接打开构建出的可执行文件，会运行打包后的应用，包括构建时的 Python 代码。要让 Python 改动包含进该打包应用，需要重新构建。

Web 应用 (Web app)

要将 Flet 应用作为 Web 应用运行，请使用 --web（或 -w）选项：

uv

uv run flet run --web [脚本]

pip

flet run --web [脚本]

系统将打开一个新的浏览器窗口/标签页，且应用将使用一个随机的 TCP 端口：

---

监听更改 (Watching for changes)

默认情况下，Flet 会监视正在运行的脚本文件，并在修改并保存该文件内容时重新加载应用，但不会监视其他文件的更改。

若要修改此行为，您可以使用以下一个或多个 flet run 选项：

• -d 或 --directory：仅监视 [脚本] 所在目录中的更改。
• -r 或 --recursive：递归监视 [脚本] 所在目录及其所有子目录中的更改。

示例

uv

uv run flet run --recursive [脚本]

pip

flet run --recursive [脚本]

故障排查

Linux 上热重载不可用 {#linux-inotify-limits}

在 Linux 上，flet run 使用 inotify 监视文件变化，inotify 限制了每个用户一次可监视的目录与文件数量。该限制由用户运行的所有程序共享，因此编辑器和 IDE 往往会占用其中大部分；而 --recursive 需要为每一个子目录（包括 .venv、node_modules 和 build）各建立一个监视。当达到该限制时，flet run 会打印如下警告：

Warning: file watching is unavailable (inotify watch limit reached), so the app won't reload on changes.

应用仍可运行，但保存文件后不会重新加载。

查看当前限制：

grep . /proc/sys/fs/inotify/max_user_watches /proc/sys/fs/inotify/max_user_instances

如果其中任一值低于下方给出的值，请在下次重启前调高它。对于已经更高的设置，此步及下一步都无需重复设置：

sudo sysctl fs.inotify.max_user_watches=524288 fs.inotify.max_user_instances=512

若要在重启后保留新值，可将其保存到 sysctl 配置文件并加载：

printf 'fs.inotify.max_user_watches=524288\nfs.inotify.max_user_instances=512\n' | sudo tee /etc/sysctl.d/90-inotify.conf
sudo sysctl --system

然后重新运行 flet run。

使用 --recursive 时，请将 .venv 等大型目录排除在被监视目录之外，例如可像 flet create 那样将应用代码放在 src/ 目录下。--ignore-dirs 并不会减少监视数量：它只是阻止这些目录中的变更触发应用重新加载。