使用flutter_inappwebview加载下载解压的HTML文件遇空白屏求助

问题背景 #

使用flutter_inappwebview: ^6.0.0-beta.14开发应用，流程如下：

• 从网络下载HTML压缩包
• 解压到getApplicationDocumentsDirectory()获取的本地存储路径
• 启动InAppLocalhostServer并设置documentRoot为该路径

访问http://localhost:8080/index.html时页面空白，已确认路径下存在对应文件及文件夹；但将HTML放在assets文件夹中，通过同一服务器可正常加载，需实现下载HTML的功能。

解压代码 #

final dir = (await getApplicationDocumentsDirectory()).path;
final zippedFile = File('$dir/html.zip');// 已从网络下载
await zippedFile.writeAsBytes(zip.data);

final bytes = await zippedFile.readAsBytes();
final archive = ZipDecoder().decodeBytes(bytes);
for (final file in archive) {
  final fileName = '$dir/${file.name}';
  if (file.isFile && !fileName.contains("__MACOSX")) {
    debugPrint(fileName);
    final outFile = File(fileName);
    await outFile.create(recursive: true);
    await outFile.writeAsBytes(file.content);
  }
}

本地服务器启动代码 #

final dir = (await getApplicationDocumentsDirectory()).path;
final localhostServer = InAppLocalhostServer(
      port: 8080,
      documentRoot: $dir
    );

if (!localhostServer.isRunning()) {
      await localhostServer.start();
      debugPrint('LOCALHOSTSERVER STARTED');
}

排查与解决办法 #

1. 修复服务器配置的语法错误 #

服务器启动代码中documentRoot: $dir存在语法错误，Dart中引用变量不需要加$符号，正确写法应为：

final dir = (await getApplicationDocumentsDirectory()).path;
final localhostServer = InAppLocalhostServer(
  port: 8080,
  documentRoot: dir // 去掉$符号，直接使用变量
);

这个错误会导致documentRoot设置无效，服务器无法找到指定目录下的文件，是页面空白的核心原因之一。

2. 检查压缩包文件结构 #

确认压缩包内的index.html是否直接位于根目录：

• 如果压缩包内的HTML文件在子文件夹（如web/index.html），则访问路径应为http://localhost:8080/web/index.html
• 解压后打印index.html的实际路径，验证是否与服务器根目录对应：

// 解压完成后添加校验
final indexFilePath = '$dir/index.html';
debugPrint('index.html实际路径: $indexFilePath');
debugPrint('文件是否存在: ${await File(indexFilePath).exists()}');

3. 确保文件完全写入 #

在解压完成后添加文件存在性校验，避免因异步写入未完成导致服务器读取不到文件：

// 解压循环结束后执行
bool hasIndexFile = await File('$dir/index.html').exists();
if (!hasIndexFile) {
  debugPrint('错误：index.html未解压到指定路径，请检查压缩包内容');
}

4. 调整服务器启动时机 #

确保服务器启动在解压完成之后，避免服务器先启动时文件尚未解压完成：

// 先执行完整的解压逻辑
await performUnzip(); // 封装你的解压代码为函数
// 再启动服务器
final dir = (await getApplicationDocumentsDirectory()).path;
final localhostServer = InAppLocalhostServer(
  port: 8080,
  documentRoot: dir
);
if (!localhostServer.isRunning()) {
  await localhostServer.start();
  debugPrint('LOCALHOSTSERVER STARTED');
}

5. 查看WebView加载日志 #

通过InAppWebView的错误回调和控制台日志排查具体加载问题：

InAppWebView(
  initialUrlRequest: URLRequest(url: Uri.parse('http://localhost:8080/index.html')),
  onLoadError: (controller, url, code, message) {
    debugPrint('加载错误：$message，错误码：$code');
  },
  onConsoleMessage: (controller, consoleMessage) {
    debugPrint('WebView控制台：${consoleMessage.message}');
  },
  initialSettings: InAppWebViewSettings(
    cacheEnabled: false, // 禁用缓存避免旧资源干扰
  ),
)

如果出现404错误，说明文件路径与访问URL不匹配，需调整documentRoot或访问路径。

内容的提问来源于stack exchange，提问作者Advin Thepphakan