Web 渲染器

命令行参数
Command line options
配置运行时
Runtime configuration
选择合适的渲染器
Choosing which option to use
示例
Examples

你可以选择两种不同的渲染器来运行和构建 Web 应用。下文介绍两种渲染器以及它们的适用场景:

你可以选择两种不同的渲染器来运行和构建 Web 应用。下文介绍两种渲染器以及它们的适用场景。

When running and building apps for the web, you can choose between two different renderers. This page describes both renderers and how to choose the best one for your needs. The two renderers are:

使用 HTML 渲染
使用 HTML，CSS，Canvas 和 SVG 元素来渲染，应用的大小相对较小。

HTML renderer
Uses a combination of HTML elements, CSS, Canvas elements, and SVG elements. This renderer has a smaller download size.

使用 CanvasKit 渲染
应用在移动和桌面端保持一致，有更好的性能，以及降低不同浏览器渲染效果不一致的风险。但是应用的大小会增加大约 2MB。

CanvasKit renderer
This renderer is fully consistent with Flutter mobile and desktop, has faster performance with higher widget density, but adds about 2MB in download size.

命令行参数

Command line options

--web-renderer 可选参数值为 auto、html 或 canvaskit。

The --web-renderer command line option takes one of three values, auto, html, or canvaskit.

auto（默认）- 自动选择渲染器。移动端浏览器选择 HTML，桌面端浏览器选择 CanvasKit。
auto (default) - automatically chooses which renderer to use. This option chooses the HTML renderer when the app is running in a mobile browser, and CanvasKit renderer when the app is running in a desktop browser.
html - 强制使用 HTML 渲染器。
html - always use the HTML renderer
canvaskit - 强制使用 CanvasKit 渲染器。
canvaskit - always use the CanvasKit renderer

此选项适用于 run 和 build 命令。例如：

This flag can be used with the run or build subcommands. For example:

flutter run -d chrome --web-renderer html
flutter build web --web-renderer canvaskit

如果运行/构建目标是非浏览器设备（即移动设备或桌面设备），这个选项会被忽略。

This flag is ignored when a non-browser (mobile or desktop) device target is selected.

配置运行时

Runtime configuration

要覆写 web 实时渲染器请执行以下操作：

To override the web renderer at runtime:

使用 auto 选项构建应用。
Build the app with the auto option.
在 web/index.html 文件的 main.dart.js 前插入 <script> 标签。
Insert a <script> tag in web/index.html file before the main.dart.js script.
配置 window.flutterWebRenderer 为 "canvaskit" 或者 "html"：
Set window.flutterWebRenderer to "canvaskit" or "html":

  <script type="text/javascript">
    let useHtml = // ...
    if(useHtml) {
      window.flutterWebRenderer = "html";
    } else {
      window.flutterWebRenderer = "canvaskit";
    }
  </script>
  <script src="main.dart.js" type="application/javascript"></script>

Flutter engine 启动之后无法再在 main.dart.js 更换 web 渲染器。

The web renderer can’t be changed after the Flutter engine startup process begins in main.dart.js.

选择合适的渲染器

Choosing which option to use

如果您在移动端浏览器平台上更关心应用大小，而桌面端浏览器更关心性能，请选择 auto 选项（默认）。

Choose the auto option (default) if you are optimizing for download size on mobile browsers and optimizing for performance on desktop browsers.

如果您在移动端和桌面端都更关心应用大小，请选择 html 选项。

Choose the html option if you are optimizing download size over performance on both desktop and mobile browsers.

canvaskit：移动端和桌面端都更关心性能，和跨浏览器的像素级一致性。

Choose the canvaskit option if you are prioritizing performance and pixel-perfect consistency on both desktop and mobile browsers.

示例

Examples

在 Chrome 浏览器上使用默认 (auto) 渲染器运行：

Run in Chrome using the default renderer option (auto):

flutter run -d chrome

使用默认 (auto) 渲染器构建应用（发布模式）：

Build your app in release mode, using the default (auto) option:

flutter build web --release

使用 CanvasKit 渲染器构建应用（发布模式）：

Build your app in release mode, using just the CanvasKit renderer:

flutter build web --web-renderer canvaskit --release

使用 HTML 渲染器构建应用（发布模式）：

Run your app in profile mode using the HTML renderer:

flutter run -d chrome --web-renderer html --profile