把 Flet 应用发布为独立静态网站（SPA）的说明，该网站使用 Pyodide 在浏览器中完全运行。服务器上不运行任何 Python 代码。

Pyodide 是 CPython 到 WebAssembly（WASM）的移植版本，有一些限制。

::: infoNative Python packages 原生 Python 包（相对于仅用 Python 编写的「纯」Python 包）是指部分用 C、Rust 或其他语言编写并生成原生代码的包。例如 numpy、cryptography、lxml、pydantic-core 这些包。

Pyodide 自带一份 built-in packages 列表。要从 PyPI 使用一个包，它必须是纯 Python 包，或提供为 Emscripten 构建的 wheel。 :::

::: infoAsync and threading 静态网站在浏览器单个线程中运行。你可以使用同步和异步事件处理器，但长时间运行的 CPU 任务或阻塞调用会冻结 UI。优先使用异步 I/O，或把繁重的工作移到服务器上并通过 Web API 调用。 :::

::: tipMicropip Pyodide 通过 micropip 安装包。你可以直接在 Flet 应用中使用 Micropip API：

import sys

if sys.platform == "emscripten":
    import micropip
    await micropip.install("regex")

:::

::: infoPyodide and Python version 你为 flet build web / flet publish 选择的 Python 版本会绑定到特定的 Pyodide 版本——完整的矩阵与解析规则参见选择 Python 版本。简而言之：

Python	Pyodide
3.14	314.0.6
3.13	0.29.4
3.12	0.27.7

匹配的 Pyodide 运行时会下载到构建输出中，并在首次使用时缓存到 ~/.flet/pyodide/<version>/。过去随构建模板一起发布的旧版 0.27.5 包已被移除，改为这种按版本每次构建时下载的方式。 :::

两种方式区别

发布静态网站有两种方式：flet build web 和 flet publish。两者都生成一个通过 Pyodide 在浏览器中运行的静态站点。它们主要区别在于 Python 依赖的安装方式和时机：

	flet publish	flet build web
是否需要 Flutter	否	是
依赖安装	运行时，在浏览器中（micropip）	构建时，在你的机器上（pip）
构建时间	更快 —— 无需 Flutter 编译，无需本地 pip 安装	更慢 —— Flutter 构建 + 本地依赖安装
初始加载时间	更慢 —— 页面加载时从 PyPI 拉取 wheel	更快 —— 依赖已经打包好
纯 Python wheel	✅	✅
Pyodide 构建的二进制 wheel	✅（来自 Pyodide CDN）	✅（从 Pyodide 注册表自动检测）
源码分发包（sdists）	❌ micropip 无法在浏览器中构建 sdist	✅ 纯 Python sdist，可通过 source_packages 开启

仅含 sdist 的依赖

flet publish 一个常见的失败模式是某个（传递）依赖只提供源码分发包（.tar.gz，没有 wheel）——例如 docopt。micropip 无法构建 sdist，因此加载会失败并报错：

ValueError: Can't find a pure Python 3 wheel for '<package>'

这种情况下，我们建议改用 flet build web，并把该包加入 source_packages。注意 source_packages 仅适用于纯 Python sdist。带有 C/Rust 扩展的 sdist（例如 numpy、cryptography）无法为 Pyodide 构建——请改用 Pyodide 的 built-in packages。

flet publish

不需要 Flutter。它会打包你的应用，并在运行时通过 micropip 在浏览器中安装依赖。

要发布应用，运行：

flet publish <path-to-app.py>

网站会被发布到 --distpath（默认：./dist）。

测试站点

你可以用 flet serve 命令来试跑已发布的 Flet 应用：

flet serve dist

然后在浏览器中打开 http://localhost:8000 来检查已发布的应用。

静态资源

如果存在 assets 目录（默认：./assets），其内容会被复制到已发布站点的根目录。使用 --assets 指向另一个文件夹。静态资源不会被打包进 app.tar.gz。

flet build web

使用 Flutter 和 Pyodide。依赖在构建时于本地解析并安装（通过 pip），然后打包进输出归档。

::: tipNote 更通用、更全面的补充信息可在此查看。 :::

测试站点

flet serve 会提供默认的输出目录（./build/web）：

flet serve

配置选项

以下设置适用于 flet build web 和 flet publish，除非另有说明。

Base URL

当在子目录中托管应用时，使用一个 base URL。Flet 会把它规范化为 /<value>/，未设置时使用 /。

解析顺序

其值按以下优先级依次确定：

1. --base-url
2. [tool.flet.web].base_url
3. "/"

示例

flet build

flet build web --base-url /myapp/

pyproject.toml

[tool.flet.web]
base_url = "/myapp/"

Route URL 策略

控制路由在 URL 中的表示方式：

• path —— 简洁路径；需要支持 SPA 的托管。
• hash —— 使用 URL 的 hash；可在不支持 SPA 的静态主机上工作。

解析顺序

其值按以下优先级依次确定：

1. --route-url-strategy
2. [tool.flet.web].route_url_strategy
3. FLET_WEB_ROUTE_URL_STRATEGY
4. "path"

示例

flet build

flet build web --route-url-strategy hash

pyproject.toml

[tool.flet.web]
route_url_strategy = "hash"

env var

FLET_WEB_ROUTE_URL_STRATEGY="hash"

Web renderer

选择 Flutter web 渲染器：

• canvaskit（默认）—— CanvasKit 渲染器，应用编译为 JavaScript
• skwasm —— Skia WebAssembly 渲染器，应用编译为 WebAssembly
• auto —— 由 Flutter 根据浏览器选择渲染器

INFO

默认是 canvaskit，而不是 auto。使用 auto 时，基于 Chromium 的浏览器会选择 skwasm，此时 JavaScript 与 Dart 之间传递的每一个字节缓冲区都要付出高昂的 WebAssembly 边界转换代价。Flet Web 应用每次 UI 更新都会与 Python 运行时交换字节，因此对它们来说 canvaskit 明显更快。

解析顺序

其值按以下优先级依次确定：

1. --web-renderer
2. [tool.flet.web].renderer
3. FLET_WEB_RENDERER
4. "canvaskit"

示例

flet build

flet build web --web-renderer skwasm

pyproject.toml

[tool.flet.web]
renderer = "skwasm"

env var

FLET_WEB_RENDERER="skwasm"

CDN 静态资源

默认情况下，Pyodide、CanvasKit 和字体从 CDN 加载，以保持输出体积较小。在离线或无外部网络的环境中部署时，可禁用 CDN 加载。

解析顺序

CDN 加载按以下优先级依次禁用：

1. --no-cdn
2. [tool.flet.web].cdn = false
3. FLET_WEB_NO_CDN
4. 默认：启用 CDN

示例

flet build

flet build web --no-cdn

pyproject.toml

[tool.flet.web]
cdn = false

env var

FLET_WEB_NO_CDN="true"

PWA 颜色

配置 manifest.json 和浏览器 UI 中使用的 PWA 颜色。

解析顺序

对于每个设置：

1. --pwa-background-color / --pwa-theme-color
2. [tool.flet.web].pwa_background_color / [tool.flet.web].pwa_theme_color
3. #FFFFFF / #FF005F

示例

flet build

flet build web --pwa-background-color "#000000" --pwa-theme-color "#FF0000"

pyproject.toml

[tool.flet.web]
pwa_background_color = "#000000"
pwa_theme_color = "#FF0000"

PWA 短名称

manifest.json 中的 short_name 是 PWA 安装后显示在应用图标下方的标签，例如在 iOS 主屏幕上。

解析顺序

1. --pwa-short-name
2. [tool.flet.web].pwa_short_name
3. 产品名称（--product / `[tool.flet].product）

示例

flet build

flet build web --pwa-short-name "Studio"

pyproject.toml

[tool.flet.web]
pwa_short_name = "Studio"

WASM 输出

默认情况下，flet build web 会启用 Flutter 的 WASM 输出。

::: infoNote 仅适用于 flet build web。 :::

解析顺序

WASM 输出按以下优先级依次禁用：

1. --no-wasm
2. [tool.flet.web].wasm = false
3. 默认：启用 WASM

示例

flet build

flet build web --no-wasm

pyproject.toml

[tool.flet.web]
wasm = false