环境变量 | Flet中文文档

设置布尔值

要设置为布尔 True，请使用以下字符串值之一："true"、"1" 或 "yes"。任何其他值都会被解释为 False。

`APPLE_API_ISSUER`

App Store Connect API 密钥的签发者 ID。它与 APPLE_API_KEY 和 APPLE_API_KEY_ID 一起，把 Apple 公证服务的凭据以内联方式传递给 flet build—— 适合 CI 环境；已配置的公证 profile 优先。

`APPLE_API_KEY`

App Store Connect API 私钥（.p8）文件的路径。参见 APPLE_API_ISSUER。

`APPLE_API_KEY_ID`

App Store Connect API 密钥的密钥 ID。参见 APPLE_API_ISSUER。

`FLET_ANDROID_SIGNING_KEY_ALIAS`

flet build 用于 Android 应用签名的签名密钥别名。

仅在配置了密钥库时才会使用。

`FLET_ANDROID_SIGNING_KEY_PASSWORD`

flet build 用于 Android 应用签名的签名密钥密码。

如果设置了 FLET_ANDROID_SIGNING_KEY_STORE_PASSWORD 而没有设置本变量，则会复用密钥库密码作为密钥密码。

`FLET_ANDROID_SIGNING_KEY_STORE`

flet build 用于 Android 应用签名的 Android 上传密钥库（.jks）路径。

`FLET_ANDROID_SIGNING_KEY_STORE_PASSWORD`

flet build 用于 Android 应用签名的 Android 签名密钥库密码。

如果设置了 FLET_ANDROID_SIGNING_KEY_PASSWORD 而没有设置本变量，则会复用密钥密码作为密钥库密码。

`FLET_APP_CONSOLE`

应用控制台日志文件（console.log）在缓存存储目录（FLET_APP_STORAGE_CACHE）中的路径。

其值在生产模式下才会设置。

INFO

在一个运行中的 Flet 应用里，与此环境变量等价的是 [StoragePaths.get_console_log_filename()][flet.StoragePaths.get_console_log_filename]。

`FLET_APP_ID`

Linux 桌面用来对应用窗口进行分组和命名时所使用的身份标识：即 X11 的 WM_CLASS 和 Wayland 的 app_id。如果没有它，每个打包应用都会继承共享客户端二进制的名称，显示为 flet。

请将其设置为与应用桌面入口的 StartupWMClass 键相同的字符串，这样桌面就能把窗口与入口匹配起来，并从中获取应用的名称和图标——参见 Linux 任务栏身份。

仅适用于 Linux 桌面应用；当给定 --bundle-id 时， flet pack 会自动将其设置为该值，否则设置为可执行文件的名称。

`FLET_APP_RELAUNCH_COMMAND`

Windows 用于从固定到任务栏的图标重新启动应用的命令（System.AppUserModel.RelaunchCommand），盖章在桌面客户端窗口上。当 FLET_APP_USER_MODEL_ID 为某个已存在文件的路径时，默认取该路径的带引号形式。

仅适用于 Windows 桌面应用；由 flet pack 自动设置—— 参见 FLET_APP_USER_MODEL_ID。

`FLET_APP_RELAUNCH_DISPLAY_NAME`

Windows 在任务栏右键菜单和固定项中为应用显示的名称（System.AppUserModel.RelaunchDisplayNameResource）。默认取自 FLET_APP_USER_MODEL_ID 中的可执行文件名。

仅适用于 Windows 桌面应用；由 flet pack 自动设置—— 参见 FLET_APP_USER_MODEL_ID。

`FLET_APP_RELAUNCH_ICON`

Windows 用于任务栏按钮和固定项的图标资源（System.AppUserModel.RelaunchIconResource），例如 C:\path\to\app.exe,0。默认取自 FLET_APP_USER_MODEL_ID 中可执行文件的第一个图标。

仅适用于 Windows 桌面应用；由 flet pack 自动设置—— 参见 FLET_APP_USER_MODEL_ID。

`FLET_APP_STORAGE_CACHE`

用于存放可重新生成的缓存数据的目录。操作系统可能会在存储空间紧张时将其清除（平台自带的「清除缓存」操作也会清空它），因此只应存放那些可以重建的内容。该目录会预先创建且为应用私有；它映射到平台的 caches 目录（Windows 上为 %LOCALAPPDATA%\<company>\<product>，macOS 上为 ~/Library/Caches/<bundle-id>，Linux 上为 ~/.cache/<app-id>，iOS/Android 上为应用缓存目录）。在 flet run 下则为 <project>/.flet/storage/cache。

INFO

在一个运行中的 Flet 应用里，与此环境变量等价的是 [StoragePaths.get_application_cache_directory()][flet.StoragePaths.get_application_cache_directory]。

`FLET_APP_STORAGE_DATA`

用于存放持久应用数据的目录——数据库、状态、配置——在应用更新之间保留、由操作系统备份、且不会被自动删除。它会预先创建且为应用私有，其位置取决于平台（映射到平台的 application support 目录：Windows 上为 %APPDATA%\<company>\<product>\data，macOS 上为 ~/Library/Application Support/<bundle-id>/data，Linux 上为 ~/.local/share/<app-id>/data， iOS/Android 上为应用沙盒中的支持目录）。

在生产环境中，该目录同时也是 Python 程序的当前工作目录，因此相对路径的文件写入（例如 open("app.db", "w")、sqlite3.connect("app.db")）都会落在这里。在 flet run （开发模式）下则为 <project>/.flet/storage/data。

INFO

在一个运行中的 Flet 应用里，它映射到 [StoragePaths.get_application_support_directory()][flet.StoragePaths.get_application_support_directory] 的 data 子目录。

`FLET_APP_STORAGE_TEMP`

用于存放一次性临时文件的目录——即操作系统的临时目录（getTemporaryDirectory()）。它是三者中最易失的，可能会在两次启动之间被清空，因此不要依赖其内容的持久性。（在 Android 上，它解析为与 FLET_APP_STORAGE_CACHE 相同的目录。）在 flet run 下则为 <project>/.flet/storage/temp，Python 的 tempfile 也被指向这里（通过 TMPDIR）。等价于 Python 的 tempfile.gettempdir()。

INFO

在一个运行中的 Flet 应用里，与此环境变量等价的是 [StoragePaths.get_temporary_directory()][flet.StoragePaths.get_temporary_directory]。

`FLET_APP_USER_MODEL_ID`

Windows 的 AppUserModelID，由桌面客户端进程用于任务栏分组和固定。

仅适用于 Windows 桌面应用——由桌面客户端启动器（flet-desktop）读取；它对 Web 或移动应用无效。

对于用 flet pack 打包的应用，该值会被自动设置为打包后的可执行文件路径，这样任务栏就会把客户端窗口与打包应用关联起来，而不是与缓存的 Flet 客户端可执行文件关联。它还会与 FLET_APP_RELAUNCH_* 属性一起被盖章到客户端窗口上，这些属性会让任务栏的名称、图标和固定项都解析到打包应用。

当使用其他方式打包时（例如 Nuitka），请自行设置此变量——在应用启动前或 main.py 的最顶部设置——以获得相同的行为。

`FLET_ASSETS_DIR`

应用静态资源目录的绝对路径。

在由 flet build 构建的生产应用中，此环境变量在运行时指向打包后静态资源的绝对位置。当你的代码需要访问打包文件的文件系统路径时（例如 JSON 配置、数据库或模型文件），可以使用它。

对于本地运行，它可能会因应用的启动方式而未设置，因此请使用一个回退方案：

python

import os
from pathlib import Path
import flet as ft

default_assets_dir = Path(__file__).parent / "assets"
assets_dir = Path(os.environ.get("FLET_ASSETS_DIR", str(default_assets_dir))).resolve()

def main(page: ft.Page):
	...

ft.run(main, assets_dir="assets")

对于像 Image.src 这样的控件属性，请继续使用相对于 ft.run(assets_dir=...) 的路径，如静态资源常用食谱中所述。

`FLET_CLI_NO_RICH_OUTPUT`

是否禁用控制台中的富文本输出。

默认为 "false"。

`FLET_CLI_SKIP_FLUTTER_DOCTOR`

是否在构建失败时跳过运行 flutter doctor。

默认为 False。

`FLET_FORCE_WEB_SERVER`

设置为 true 可强制以 Web 应用方式运行。在无界面（headless）的 Linux 主机上会自动设置。

`FLET_HIDE_WINDOW_ON_START`

设置为 true 可在启动时隐藏主窗口。

默认为 False。

`FLET_LOG_LEVEL`

应用启动时应用的日志级别，例如 "info" 或 "debug"。参见日志记录。

flet run 会为它启动的应用设置该级别：-v 对应 "info"，-vv 对应 "debug"。若应用自行配置了日志，则保留其选择的设置，因此该变量仅在应用未自行配置日志时才会生效。

`FLET_MACOS_INSTALLER_IDENTITY`

安装器证书（"3rd Party Mac Developer Installer" / "Mac Installer Distribution" 的名称或 SHA-1 指纹），由 flet build 用于为 Mac App Store 构建签名安装器 .pkg。未配置时，会自动发现钥匙串中唯一的安装器证书。

`FLET_MACOS_NOTARY_PROFILE`

notarytool 钥匙串 profile 的名称（通过 xcrun notarytool store-credentials 创建），由 flet build 用于在对 macOS 应用进行公证时向 Apple 公证服务进行身份验证。

或者，设置 APPLE_API_KEY（.p8 文件路径）、APPLE_API_KEY_ID 和 APPLE_API_ISSUER 环境变量，以以内联方式传递一个 App Store Connect API 密钥；已配置的 profile 优先于它们（precedence）。

`FLET_MACOS_PROVISIONING_PROFILE`

Mac App Store 配置文件（.provisionprofile）的路径，由 flet build 嵌入到 App Store 构建的 Contents/embedded.provisionprofile 中。

`FLET_MACOS_SIGNING_IDENTITY`

代码签名身份，由 flet build 用于对 macOS 应用 bundle 进行签名：可以是 "Developer ID Application"（直接分发）或 "Apple Distribution" （App Store）证书名称、其 SHA-1 指纹，或者 - 表示临时（ad-hoc）签名。

当未配置时（此处、通过 CLI 或在 pyproject.toml 中均未配置），普通构建会保留其默认的临时（ad-hoc）签名，而需要公证和 App Store 的构建会在钥匙串中恰好只有一张所需类型证书时自动发现它。

`FLET_MAX_UPLOAD_SIZE`

允许上传的文件最大大小（以字节为单位）。

默认不限制。

`FLET_OAUTH_CALLBACK_HANDLER_ENDPOINT`

OAuth 处理器的自定义路径。

默认为 "/oauth_callback"。

`FLET_OAUTH_STATE_TIMEOUT`

完成 OAuth Web 流程所允许的最大时间（以秒为单位）。

默认为 600。

`FLET_PLATFORM`

应用运行所在的平台。

其值可以是以下几种之一："android"、"ios"、"linux"、"macos"、"windows" 或 "fuchsia"。

`FLET_SECRET_KEY`

用于对临时上传 URL 进行签名的密钥。

`FLET_SERVER_IP`

Web 应用监听的 IP 地址，例如 "127.0.0.1"。

默认为 0.0.0.0——绑定到所有服务器 IP。

`FLET_SERVER_PORT`

运行应用所使用的 TCP 端口。

如果程序运行在 Linux 服务器上，或者设置了 FLET_FORCE_WEB_SERVER，则为 8000；否则为随机端口。

`FLET_SERVER_UDS_PATH`

Flet 服务器的 Unix 域套接字（UDS）路径。它支持基于 Unix 的系统上的进程间通信，其值为格式为 flet_<pid>.sock 的套接字文件路径。

`FLET_SESSION_TIMEOUT`

会话生命周期（以秒为单位）。

默认为 3600。

`FLET_UPLOAD_DIR`

应用「上传」目录的绝对路径。

`FLET_UPLOAD_HANDLER_ENDPOINT`

上传处理器的自定义路径。

默认为 "/upload"。

`FLET_VIEW_PATH`

一个目录的路径，其中包含要使用的 Flet 桌面客户端，以替代 Flet 自动下载的客户端：macOS 上为 Flet.app，Windows 上为 flet.exe，Linux 上为 flet。

flet run 会优先在 build/<platform> 中查找上一次 flet build 生成的客户端，若找不到则回退到该变量指定的目录，最后才使用缓存的客户端。 flet pack 会读取该变量以选择其打包时使用的客户端。

`FLET_WEB_APP_PATH`

承载 Web 应用的域名之后的 URL 路径，例如 "/apps/myapp"。

默认为 "/"——将应用托管在根路径。

`FLET_WEB_NO_CDN`

设置为 true 可避免从 CDN 加载 CanvasKit、Pyodide 和字体。

`FLET_WEB_PATH`

一个目录的路径，其中包含要提供服务的 Flet Web 客户端，以替代随 flet-web 包一同发布的客户端。由 flet run --web、flet publish，以及以 ft.run(export_asgi_app=True) 启动的应用读取。

将其指向 flet build web 的输出，即可提供包含你应用扩展的客户端。扩展的 Dart 代码在构建时会被编译进客户端，因此不论应用如何构建，随版本发布的打包客户端都会将第三方控件渲染为 Unknown control: <Type>。

`FLET_WEB_RENDERER`

Web 渲染模式："canvaskit"（默认）、"skwasm" 或 "auto"。

`FLET_WEB_ROUTE_URL_STRATEGY`

Web 应用的 URL 策略。其值可以是 "path"（默认）或 "hash"。

`FLET_WEB_USE_COLOR_EMOJI`

设置为 True、true 或 1 可加载带有彩色 emoji 的 Web 字体。

`FLET_WEBSOCKET_HANDLER_ENDPOINT`

WebSocket 处理器的自定义路径。

默认为 "/ws"。

托管

托管

APPLE_API_ISSUER ​

APPLE_API_KEY ​

APPLE_API_KEY_ID ​

FLET_ANDROID_SIGNING_KEY_ALIAS ​

FLET_ANDROID_SIGNING_KEY_PASSWORD ​

FLET_ANDROID_SIGNING_KEY_STORE ​

FLET_ANDROID_SIGNING_KEY_STORE_PASSWORD ​

FLET_APP_CONSOLE ​

FLET_APP_ID ​

FLET_APP_RELAUNCH_COMMAND ​

FLET_APP_RELAUNCH_DISPLAY_NAME ​

FLET_APP_RELAUNCH_ICON ​

FLET_APP_STORAGE_CACHE ​

FLET_APP_STORAGE_DATA ​

FLET_APP_STORAGE_TEMP ​

FLET_APP_USER_MODEL_ID ​

FLET_ASSETS_DIR ​

FLET_CLI_NO_RICH_OUTPUT ​

FLET_CLI_SKIP_FLUTTER_DOCTOR ​

FLET_FORCE_WEB_SERVER ​

FLET_HIDE_WINDOW_ON_START ​

FLET_LOG_LEVEL ​

FLET_MACOS_INSTALLER_IDENTITY ​

FLET_MACOS_NOTARY_PROFILE ​

FLET_MACOS_PROVISIONING_PROFILE ​

FLET_MACOS_SIGNING_IDENTITY ​

FLET_MAX_UPLOAD_SIZE ​

FLET_OAUTH_CALLBACK_HANDLER_ENDPOINT ​

FLET_OAUTH_STATE_TIMEOUT ​

FLET_PLATFORM ​

FLET_SECRET_KEY ​

FLET_SERVER_IP ​

FLET_SERVER_PORT ​

FLET_SERVER_UDS_PATH ​

FLET_SESSION_TIMEOUT ​

FLET_UPLOAD_DIR ​

FLET_UPLOAD_HANDLER_ENDPOINT ​

FLET_VIEW_PATH ​

FLET_WEB_APP_PATH ​

FLET_WEB_NO_CDN ​

FLET_WEB_PATH ​

FLET_WEB_RENDERER ​

FLET_WEB_ROUTE_URL_STRATEGY ​

FLET_WEB_USE_COLOR_EMOJI ​

FLET_WEBSOCKET_HANDLER_ENDPOINT ​

关注我，学习大模型、大数据、Python等热门技术。

`APPLE_API_ISSUER`

`APPLE_API_KEY`

`APPLE_API_KEY_ID`

`FLET_ANDROID_SIGNING_KEY_ALIAS`

`FLET_ANDROID_SIGNING_KEY_PASSWORD`

`FLET_ANDROID_SIGNING_KEY_STORE`

`FLET_ANDROID_SIGNING_KEY_STORE_PASSWORD`

`FLET_APP_CONSOLE`

`FLET_APP_ID`

`FLET_APP_RELAUNCH_COMMAND`

`FLET_APP_RELAUNCH_DISPLAY_NAME`

`FLET_APP_RELAUNCH_ICON`

`FLET_APP_STORAGE_CACHE`

`FLET_APP_STORAGE_DATA`

`FLET_APP_STORAGE_TEMP`

`FLET_APP_USER_MODEL_ID`

`FLET_ASSETS_DIR`

`FLET_CLI_NO_RICH_OUTPUT`

`FLET_CLI_SKIP_FLUTTER_DOCTOR`

`FLET_FORCE_WEB_SERVER`

`FLET_HIDE_WINDOW_ON_START`

`FLET_LOG_LEVEL`

`FLET_MACOS_INSTALLER_IDENTITY`

`FLET_MACOS_NOTARY_PROFILE`

`FLET_MACOS_PROVISIONING_PROFILE`

`FLET_MACOS_SIGNING_IDENTITY`

`FLET_MAX_UPLOAD_SIZE`

`FLET_OAUTH_CALLBACK_HANDLER_ENDPOINT`

`FLET_OAUTH_STATE_TIMEOUT`

`FLET_PLATFORM`

`FLET_SECRET_KEY`

`FLET_SERVER_IP`

`FLET_SERVER_PORT`

`FLET_SERVER_UDS_PATH`

`FLET_SESSION_TIMEOUT`

`FLET_UPLOAD_DIR`

`FLET_UPLOAD_HANDLER_ENDPOINT`

`FLET_VIEW_PATH`

`FLET_WEB_APP_PATH`

`FLET_WEB_NO_CDN`

`FLET_WEB_PATH`

`FLET_WEB_RENDERER`

`FLET_WEB_ROUTE_URL_STRATEGY`

`FLET_WEB_USE_COLOR_EMOJI`

`FLET_WEBSOCKET_HANDLER_ENDPOINT`