跳到主要内容

将 Flet 应用程序发布到多个平台

博客

flet打包更新

简介

Flet CLI 提供了 flet build 命令,该命令允许将 Flet 应用程序打包成独立的可执行文件或安装包,以便分发。

平台矩阵

以下矩阵显示了在哪个操作系统上运行 flet build 命令,以便为特定平台生成包:

运行于 / flet buildapk/aabipamacoslinuxwindowsweb
macOS
Windows✅ (WSL)
Linux

前提条件

Flutter SDK

必须安装 Flutter SDK 3.16 或更高版本,并将 flutterdart 命令的路径添加到 PATH 环境变量中。

在 macOS 上,我们建议使用 "下载并安装" 方法 安装 Flutter SDK。

在 Linux 上,我们建议使用 Method 2: 手动安装 安装 Flutter SDK(不要使用 snap 安装 Flutter)。

请注意,Flutter 对每个平台的要求,例如 macOS 上的 XCode 和 Cocopods,Windows 上的 Visual Studio 2022,以及 Linux 上的其他工具和库。

项目结构

flet build 命令假设以下 Flet 项目结构:

/assets/
icon.png
main.py
requirements.txt
pyproject.toml

main.py 是 Flet 应用程序的入口点,最后有一行 ft.app(main)。可以使用 --module-name 参数指定不同的入口点。

assets 是一个可选的目录,包含应用程序资产(图像、声音、文本和其他文件)以及用于生成所有平台图标和闪屏的图像。

如果只提供了 icon.png(或其他支持的格式,例如 .bmp.jpg.webp),它将被用作所有平台的图标和闪屏的源图像。

requirements.txt 是一个标准的 pip 文件,包含 Flet 应用程序的 Python 依赖项列表。如果该文件不存在,只会安装 flet 依赖项。

不要使用 pip freeze

不要使用 pip freeze > requirements.txt 命令创建 requirements.txt 文件,以便在移动设备上运行应用程序。在桌面上运行 pip freeze 命令时,requirements.txt 将包含不适合移动设备的依赖项,例如 watchdog

手动选择 requirements.txt,以便包含应用程序所需的直接依赖项,包括 flet

pyproject.toml 也可以被 flet build 命令用来获取项目依赖项列表。然而,如果同时存在 requirements.txtpyproject.toml,则 pyproject.toml 将被忽略。

使用 flet create 命令可以轻松创建该结构:

flet create myapp

其中 myapp 是目标目录。

pyproject.toml

pyproject.toml 读取依赖项尚不支持 (issue),请使用 requirements.txt 代替。

如何工作

flet build <target_platform> 命令可以从 Flet 应用程序目录的根目录运行:

<flet_app_directory> % flet build <target_platform>

其中 <target_platform> 可以是以下之一:apkaabipawebmacoswindowslinux

如果从不同的目录运行,可以提供 Flet 应用程序目录的路径:

flet build <target_platform> <path_to_python_app>

构建结果将被复制到 <python_app_directory>/build/<target_platform> 目录中。可以使用 --output 选项指定自定义的输出目录:

flet build <target_platform> --output <path-to-output-dir>

flet build 使用 Flutter SDK 和多个 Flutter 包来从 Flet 应用程序生成分发包。

当您运行 flet build <target_platform> 命令时,它:

  • 在临时目录中创建一个新的 Flutter 项目,从 https://github.com/flet-dev/flet-build-template 模板中获取。
  • 将自定义图标和闪屏图像从 assets 目录复制到 Flutter 项目中。
  • 使用 flutter_launcher_icons 包生成所有平台的图标。
  • 使用 flutter_native_splash 包生成 web、iOS 和 Android 目标的闪屏。
  • 使用 package 命令将 Python 应用程序打包到资产中。所有 Python 文件将被编译到 .pyc 文件中,并将所有文件(除了 build 目录)添加到资产中。
  • 运行 flutter build <target_platform> 命令生成可执行文件或安装包。
  • 将构建结果复制到 build/<target_platform> 目录中。

包含可选控件

如果您的应用程序使用以下控件,必须将其包添加到构建命令中:

  • Audio 控件,实现在 flet_audio 包中。
  • AudioRecorder 控件,实现在 flet_audio_recorder 包中。
  • Lottie 控件,实现在 flet_lottie 包中。
  • Rive 控件,实现在 flet_rive 包中。
  • Video 控件,实现在 flet_video 包中。
  • WebView 控件,实现在 flet_webview 包中。

使用 --include-packages <package_1> <package_2>... 选项将 Flutter 包添加到构建命令中。

例如,要构建包含 VideoAudio 控件的 Flet 应用程序,添加 --include-packages flet_video flet_audio 到您的 flet build 命令中:

flet build apk --include-packages flet_video flet_audio

图标

您可以使用 assets 目录中的图像自定义所有平台的图标(除 Linux 外)。

如果只提供了 icon.png(或其他支持的格式,例如 .bmp.jpg.webp),它将被用作所有平台的图标的源图像。

  • iOS - icon_ios.png(或其他支持的格式)。推荐的最小图像大小为 1024 px。图像不应是透明的(具有 alpha 通道)。默认为 icon.png,并自动删除 alpha 通道。
  • Android - icon_android.png(或其他支持的格式)。推荐的最小图像大小为 192 px。默认为 icon.png
  • Web - icon_web.png(或其他支持的格式)。推荐的最小图像大小为 512 px。默认为 icon.png
  • Windows - icon_windows.png(或其他支持的格式)。ICO 将被生成为 256 px 大小。默认为 icon.png。如果提供了 icon_windows.ico 文件,它将被复制到 windows/runner/resources/app_icon.ico 目录中,不进行修改。
  • macOS - icon_macos.png(或其他支持的格式)。推荐的最小图像大小为 1024 px。默认为 icon.png

启动画面

您可以使用 Flet 应用程序的 assets 目录中的图像自定义 iOS、Android 和 Web 应用程序的启动画面。

如果只提供了 splash.pngicon.png(或其他支持的格式如 .bmp.jpg.webp),它将被用作生成所有启动画面的源图像。

  • iOS(浅色) - splash_ios.png(或任何支持的图像格式)。默认为 splash.png,然后是 icon.png
  • iOS(深色) - splash_dark_ios.png(或任何支持的图像格式)。默认为浅色 iOS 启动画面,然后是 splash_dark.png,然后是 splash.png,再然后是 icon.png
  • Android(浅色) - splash_android.png(或任何支持的图像格式)。默认为 splash.png,然后是 icon.png
  • Android(深色) - splash_dark_android.png(或任何支持的图像格式)。默认为浅色 Android 启动画面,然后是 splash_dark.png,然后是 splash.png,再然后是 icon.png
  • Web(浅色) - splash_web.png(或任何支持的图像格式)。默认为 splash.png,然后是 icon.png
  • Web(深色) - splash_dark_web.png(或任何支持的图像格式)。默认为浅色 Web 启动画面,然后是 splash_dark.png,然后是 splash.png,再然后是 icon.png

--splash-color 选项指定浅色模式下启动画面的背景颜色。默认为 #ffffff

--splash-dark-color 选项指定深色模式下启动画面的背景颜色。默认为 #333333

Flet 应用程序入口点

默认情况下,flet build 命令将 main.py 作为 Flet 应用程序的入口点,即文件末尾带有 ft.app(main) 的文件。可以使用 --module-name 参数指定不同的入口点。

版本控制

您可以使用 --build-number--build-version 参数为构建的可执行文件或软件包提供版本信息。这些信息用于区分 App Store 和 Google Play 中的不同构建/发布版本,并在关于对话框中显示给用户。

--build-number - 一个整数(默认是 1),用作内部版本号。每个构建必须有一个唯一的标识符,以便与之前的构建区分开来。它用于确定一个构建是否比另一个构建更新,数字越大表示构建越新。

--build-version - 一个 "x.y.z" 格式的字符串(默认是 1.0.0),用作显示给用户的版本号。对于应用程序的每个新版本,您需要提供一个版本号,以区分它与之前的版本。

自定义打包模板

为了创建一个临时的 Flutter 项目,flet build 使用存储在 https://github.com/flet-dev/flet-build-template 仓库中的 cookiecutter 模板。

您可以自定义该模板以满足您的特定需求,然后使用 flet build

--template 选项可以用于提供模板的 URL 或目录路径。对于 GitHub 仓库,使用 gh: 前缀,例如 gh:{my-org}/{my-repo} 或提供 Git 仓库的完整路径,例如 https://github.com/{my-org}/{my-repo}.git

对于 Git 仓库,您可以使用 --template-ref 选项检查特定的分支/标签/提交。

--template-dir 选项指定仓库中 cookiecutter 模板的相对路径。

flutter build 命令传递额外参数

--flutter-build-args 选项允许在构建过程中向 flutter build 命令传递额外参数。该选项可以多次使用。

例如,如果您想添加 --no-tree-shake-icons 选项:

flet build macos --flutter-build-args=--no-tree-shake-icons

要传递带有值的选项:

flet build ipa --flutter-build-args=--export-method --flutter-build-args=development

日志记录

所有 Flet 应用程序的输出(例如所有 print() 语句或 sys.stdout.write() 调用,Python logging 库)现在重定向到 out.log 文件。写入该文件是无缓冲的,因此您可以在 Python 程序中的任何时候通过简单的代码检索日志:

with open("out.log", "r") as f:
log = f.read()

可以使用 AlertDialog 或其他控件显示 log 变量的值。

当通过调用 sys.exit() 并使用退出代码 100(特殊代码)终止程序时,整个日志将显示在可滚动窗口中。

import sys
sys.exit(100)

使用其他退出代码调用 sys.exit() 将终止(关闭)应用程序而不显示日志。