Flutter Web本地加载CanvasKit遇问题：请求远程或本地文件语法报错

问题背景 #

我正在开发Flutter Web应用，需要基于CanvasKit构建版本在本地网络运行。当前应用初始化时，客户端会向gstatic发送请求获取canvaskit.js，断网时该请求会失败。我希望让应用从本地服务器获取该文件以实现离线运行。

已尝试的index.html配置 #

我已在index.html中添加以下配置，但应用仍会请求远程canvaskit.js：

<script>
  window.flutterConfiguration = {
    canvasKitBaseUrl: "/canvaskit/"
  };
</script>
<script>
  window.addEventListener('load', function (ev) {
    // Download main.dart.js
    _flutter.loader.loadEntrypoint({
      serviceWorker: {
        serviceWorkerVersion: serviceWorkerVersion,
      },
      onEntrypointLoaded: function (engineInitializer) {
        let config = {
        canvasKitVariant: "full",
      };
        engineInitializer.initializeEngine(config).then(function (appRunner) {
          appRunner.runApp();
        });
      }
    });
  });
</script>

已尝试的构建命令 #

flutter build web --web-renderer canvaskit
flutter build web  --dart-define=FLUTTER_WEB_USE_SKIA=true --web-renderer canvaskit 
flutter build web --dart-define=FLUTTER_WEB_CANVASKIT_URL=./canvaskit.js --dart-define=FLUTTER_WEB_USE_SKIA=true --web-renderer canvaskit
flutter build web --base-href "/" --no-web-resources-cdn --dart-define=FLUTTER_WEB_USE_SKIA=true --web-renderer canvaskit

Flutter环境信息 #

flutter doctor
Doctor summary (to see all details, run flutter doctor -v):
[√] Flutter (Channel stable, 3.19.6, on Microsoft Windows [Version 10.0.19044.4046], locale en-US)
[√] Windows Version (Installed version of Windows is version 10 or higher)
[!] Android toolchain - develop for Android devices (Android SDK version 34.0.0)
    X cmdline-tools component is missing
      Run `path/to/sdkmanager --install "cmdline-tools;latest"`
      See https://developer.android.com/studio/command-line for more details.
    X Android license status unknown.
      Run `flutter doctor --android-licenses` to accept the SDK licenses.
      See https://flutter.dev/docs/get-started/install/windows#android-setup for more details.
[√] Chrome - develop for the web
[!] Visual Studio - develop Windows apps (Visual Studio Build Tools 2019 16.11.34)
    X The current Visual Studio installation is incomplete.
      Please use Visual Studio Installer to complete the installation or reinstall Visual Studio.
[√] Android Studio (version 2023.1)
[√] VS Code (version 1.88.1)
[√] Connected device (4 available)
[!] Network resources
    X A network error occurred while checking "https://maven.google.com/": The semaphore timeout period has expired.


! Doctor found issues in 3 categories.

后续遇到的问题 #

后来我成功加载本地CanvasKit文件，但canvaskit.js的97:504行出现语法错误，错误代码行如下：

var gb=0,ib=0,jb="undefined"!=typeof TextDecoder?new TextDecoder("utf8"):void 0,kb=(a,b,c)=>{var d=b+c;for(c=b;a[c]&&!(c>=d);)++c;if(16<c-b&&a.buffer&&jb)return jb.decode(a.subarray(b,c));for(d="";b<c;){var f=a[b++];if(f&128){var k=a[b++]&63;if(192==(f&224))d+=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXf)}return d},

解决方案 #

1. 修复本地CanvasKit文件损坏问题 #

你看到的语法错误中出现大量XXXXXXXX，说明本地的canvaskit.js文件已损坏或下载不完整。正确操作：

• 从Flutter SDK对应版本目录复制完整CanvasKit文件，Flutter 3.19.6的路径通常是flutter/bin/cache/flutter_web_sdk/canvaskit/，里面包含canvaskit.js、canvaskit.wasm等核心文件。
• 将整个canvaskit文件夹复制到项目的web/目录下，确保目录结构为web/canvaskit/。

2. 正确配置加载路径 #

方式一：通过index.html全局配置

确保window.flutterConfiguration脚本放在main.dart.js加载脚本之前，修改后关键代码如下：

<script>
  window.flutterConfiguration = {
    canvasKitBaseUrl: "/canvaskit/",
    canvasKitVariant: "full"
  };
</script>
<script>
  window.addEventListener('load', function (ev) {
    _flutter.loader.loadEntrypoint({
      serviceWorker: {
        serviceWorkerVersion: serviceWorkerVersion,
      },
      onEntrypointLoaded: function (engineInitializer) {
        engineInitializer.initializeEngine().then(function (appRunner) {
          appRunner.runApp();
        });
      }
    });
  });
</script>

使用以下命令构建：

flutter build web --web-renderer canvaskit --no-web-resources-cdn

方式二：通过构建命令指定路径

无需修改index.html，直接用参数指定本地路径：

flutter build web --web-renderer canvaskit --no-web-resources-cdn --dart-define=FLUTTER_WEB_CANVASKIT_URL=/canvaskit/canvaskit.js

注意路径需与web/目录下的文件位置对应，确保本地服务器能正常访问/canvaskit/canvaskit.js。

3. 验证资源完整性 #

构建完成后，检查build/web/canvaskit/目录是否包含完整文件；启动本地服务器后，直接访问http://localhost:<端口>/canvaskit/canvaskit.js，确认文件无乱码、无缺失内容。

4. 语法错误排查补充 #

若仍出现语法错误，检查：

• 是否复制了与当前Flutter版本匹配的CanvasKit文件，不同版本的CanvasKit存在兼容性差异。
• 本地服务器是否对JS文件做了错误的压缩或转码处理，需确保服务器原样返回文件内容。

内容的提问来源于stack exchange，提问作者NIMA Shahahmadian