跳到主内容

本页详细介绍 Flutter Web 应用的初始化过程以及如何对其进行自定义。

启动

#

flutter build web 命令会在构建输出目录（build/web）中生成一个名为 flutter_bootstrap.js 的脚本。该文件包含初始化和运行 Flutter 应用所需的 JavaScript 代码。您可以通过在 Flutter 应用的 web 子目录中的 index.html 文件中为其添加一个异步脚本标签来使用此脚本。

html
<html>
  <body>
    <script src="flutter_bootstrap.js" async></script>
  </body>
</html>

或者，您可以通过在 index.html 文件中插入模板标记 {{flutter_bootstrap.js}} 来内联 flutter_bootstrap.js 文件的全部内容。

html
<html>
  <body>
    <script>
      {{flutter_bootstrap_js}}
    </script>
  </body>
</html>

在构建步骤中，当 index.html 文件被复制到输出目录（build/web）时，{{flutter_bootstrap_js}} 标记会被替换为 flutter_bootstrap.js 文件的内容。

自定义初始化

#

默认情况下，flutter build web 会生成一个 flutter_bootstrap.js 文件，该文件会简单地初始化您的 Flutter 应用。但是，在某些情况下，您可能需要自定义此初始化过程，例如：

  • 为您的应用设置自定义 Flutter 配置。
  • 更改 Flutter 服务工作者的设置。
  • 编写自定义 JavaScript 代码，在启动过程的不同阶段运行。

要编写自己的自定义启动逻辑，而不是使用构建步骤生成的默认脚本，您可以将 flutter_bootstrap.js 文件放在项目根目录的 web 子目录中。该文件会被复制并用于替换构建生成的默认脚本。此文件也是一个模板，您可以在其中插入一些特殊的标记，这些标记会在构建时复制 flutter_bootstrap.js 文件到输出目录时被构建步骤替换。下表列出了构建步骤将在 flutter_bootstrap.js 或 index.html 文件中替换的标记。

标记替换为
{{flutter_js}}使 FlutterLoader 对象可在全局变量 _flutter.loader 中使用的 JavaScript 代码。（有关更多详细信息，请参阅下面的 _flutter.loader.load() API 部分。）
{{flutter_build_config}}一个 JavaScript 语句，用于设置构建过程生成的元数据，这些元数据为 FlutterLoader 提供了正确引导应用程序所需的信息。
{{flutter_service_worker_version}}一个唯一的数字，表示服务工作者的构建版本，可以作为服务工作者配置的一部分传递（请参阅下面的“常见警告”信息）。
{{flutter_bootstrap_js}}如上所述，这将 flutter_bootstrap.js 文件的内容直接内联到 index.html 文件中。请注意，此标记只能在 index.html 中使用，而不能在 flutter_bootstrap.js 文件本身中使用。

编写自定义启动脚本

#

任何自定义的 flutter_bootstrap.js 脚本都需要三个组件才能成功启动您的 Flutter 应用：

  • {{flutter_js}} 标记，用于使 _flutter.loader 可用。
  • {{flutter_build_config}} 标记，它向 FlutterLoader 提供启动应用程序所需的有关构建的信息。
  • 调用 _flutter.loader.load()，该调用实际启动应用程序。

最基本的 flutter_bootstrap.js 文件看起来会像这样：

js
{{flutter_js}}
{{flutter_build_config}}

_flutter.loader.load();

自定义 Flutter 加载器

#

_flutter.loader.load() JavaScript API 可以使用可选参数调用，以自定义初始化行为。

名称描述JS 类型
config您应用的 Flutter 配置。Object
onEntrypointLoaded引擎准备好初始化时调用的函数。接收一个 engineInitializer 对象作为其唯一参数。Function

config 参数是一个对象，可以包含以下可选字段：

名称描述Dart 类型
assetBase应用 assets 目录的基础 URL。当 Flutter 从与实际 Web 应用不同的域或子目录加载时，请添加此项。当您将 Flutter Web 嵌入到另一个应用中，或将其资源部署到 CDN 时，可能需要此项。String
canvasKitBaseUrl下载 canvaskit.wasm 的基础 URL。String
canvasKitVariant要下载的 CanvasKit 变体。您的选项包括：

1. auto：下载最适合浏览器的变体。此选项默认为此值。
2. full：下载适用于所有浏览器的完整版 CanvasKit。
3. chromium：下载一个较小的 CanvasKit 变体，该变体使用 Chromium 兼容的 API。警告：除非您计划仅使用基于 Chromium 的浏览器，否则请勿使用 chromium 选项。		String
canvasKitForceCpuOnly当设置为 true 时，强制 CanvasKit 进行仅 CPU 渲染（引擎不会使用 WebGL）。bool
canvasKitMaximumSurfacesCanvasKit 渲染器可以使用的最大叠加层表面数量。double
debugShowSemanticNodes如果设置为 true，Flutter 会在屏幕上可见地渲染语义树（用于调试）。bool
entrypointBaseUrl您的 Flutter 应用入口点的基础 URL。默认为“/”。String
hostElementFlutter 渲染应用的 HTML 元素。未设置时，Flutter Web 会接管整个页面。HtmlElement
renderer指定当前 Flutter 应用的 Web 渲染器，可以是 "canvaskit" 或 "skwasm"。String

示例：根据 URL 查询参数自定义 Flutter 配置

#

以下示例展示了一个自定义的 flutter_bootstrap.js，它允许用户通过在其网站 URL 中提供 renderer 查询参数（例如 ?renderer=skwasm）来选择渲染器。

js
{{flutter_js}}
{{flutter_build_config}}

const searchParams = new URLSearchParams(window.location.search);
const renderer = searchParams.get('renderer');
const userConfig = renderer ? {'renderer': renderer} : {};
_flutter.loader.load({
  config: userConfig,
});

此脚本会评估页面的 URLSearchParams，以确定用户是否传递了 renderer 查询参数，然后更改 Flutter 应用的用户配置。

onEntrypointLoaded 回调

#

您还可以将 onEntrypointLoaded 回调传递给 load API，以便在初始化过程的不同阶段执行自定义逻辑。初始化过程分为以下几个阶段：

加载入口点脚本
当服务工作者初始化完成，并且 main.dart.js 入口点已被浏览器下载并执行后，load 函数会调用 onEntrypointLoaded 回调。在开发过程中，Flutter 也会在每次热重启时调用 onEntrypointLoaded。
初始化 Flutter 引擎
onEntrypointLoaded 回调接收一个 引擎初始化器 对象作为其唯一参数。使用引擎初始化器的 initializeEngine() 函数来设置运行时配置（例如 multiViewEnabled: true）并启动 Flutter Web 引擎。
运行应用
initializeEngine() 函数返回一个 Promise，该 Promise 会解析为一个 应用运行器 对象。应用运行器有一个名为 runApp() 的单一方法，用于运行 Flutter 应用。
向应用添加（或从中删除）视图
runApp() 方法返回一个 flutter 应用 对象。在多视图模式下，可以使用 addView 和 removeView 方法从宿主应用管理应用视图。要了解更多信息，请查看 嵌入模式。

示例：显示进度指示器

#

为了在初始化过程中为您的应用程序用户提供反馈，请使用每个阶段提供的钩子来更新 DOM。

js
{{flutter_js}}
{{flutter_build_config}}

const loading = document.createElement('div');
document.body.appendChild(loading);
loading.textContent = "Loading Entrypoint...";
_flutter.loader.load({
  onEntrypointLoaded: async function(engineInitializer) {
    loading.textContent = "Initializing engine...";
    const appRunner = await engineInitializer.initializeEngine();

    loading.textContent = "Running app...";
    await appRunner.runApp();
  }
});

常见警告

#

如果您遇到类似以下的警告：

text
Warning: In index.html:37: Local variable for "serviceWorkerVersion" is deprecated.
Use "" template token instead.

您可以通过删除 web/index.html 文件中的以下行来解决此问题：

web/index.html
html
var serviceWorkerVersion = null;

除非另有说明，否则本网站上的文档反映了 Flutter 的最新稳定版本。页面最后更新于 2025-08-13。 查看源代码 或 报告问题。