跳转到内容
WebView AllWebView All

错误与限制

API失败情况
loadRequestURI 没有 scheme 时抛 ArgumentError。
loadFlutterAssetkey 为空或 asset 不存在时失败。
loadFile文件不存在时失败;Web 不支持。
runJavaScriptReturningResult返回 null、undefined 或不可序列化值时失败。
callAsyncJavaScriptfunction body 为空、参数名非法或为保留字、参数不能转换为 JSON、数值非有限值、timeout 非正数时抛 ArgumentError;Promise reject 和运行时错误产生 JavaScriptExecutionException,超时产生 TimeoutException。
addUserScriptsource 为空时抛 ArgumentError;注入阶段不可用时抛 UnsupportedError,应先检查 isUserScriptInjectionSupported。
addJavaScriptChannel重名 channel 会失败;部分平台还要求合法 JS identifier。
setCookiecookie name/domain/path 非法时失败。
平台API行为
AndroidPOST + 自定义 headersAndroid postUrl 不支持。
OHOSPOST + 自定义 headersArkWeb postUrl 不支持,抛 UnsupportedError。
WebloadFile抛 UnsupportedError。
WebsetUserAgent(nonNull)打印一次说明并忽略,不抛异常。
WebSSL auth 决策浏览器不暴露。
Web跨域 JS/scroll浏览器同源策略阻止。
Web查询其他 origin 的 Cookie返回空列表并打印一次说明;浏览器 JavaScript 无法检查对应 cookie jar。
Webdocument-start 用户脚本iframe 无法保证早于页面脚本执行,能力检查返回 false。
WebWebViewDataManager.clearAllWebsiteData所有类型均返回不支持,宿主页无权清理任意 iframe storage 或 HttpOnly Cookie。
OHOS网站数据清理session storage、IndexedDB、Cache Storage 和 service worker 注册返回不支持。
Android较旧系统 WebView 的 document-start 用户脚本能力检查返回 false,应用可跳过注册并继续运行。
Windows网站数据清理WebView2 profile API 不支持 session storage 和 service worker 注册;旧 Runtime 没有该接口时,所有类型均返回不支持。
macOS滚动位置、滚动回调、滚动条和 overscrollfork 会打印缺少公开 WKWebView API 的说明并安全忽略;位置读取返回 Offset.zero。
macOS受系统版本限制的 WebKit 属性背景色需要 macOS 12,inspect 需要 macOS 13.3;更早系统打印说明并安全忽略。

最大兼容建议:

  • Android/OHOS 上需要自定义 headers 时优先使用 GET。
  • 同时要求 Android/OHOS 时避免 POST 自定义 headers。
  • Web 非简单请求必须由服务器正确配置 CORS。
  • 手动 HTTP 请求再 loadHtmlString 只适合可控 HTML,不等同于浏览器导航。

生产环境应取消证书错误:

onSslAuthError: (SslAuthError error) async {
await error.cancel();
}

proceed() 只能用于内部测试、实验环境或完全受控网络。

Web 可直接控制同源内容,并通过来源校验消息桥控制插件管理的隔离 HTML。 直接跨域 iframe URL 仍无法检查或脚本控制。隔离 HTML 的 confirm 和 prompt 保留浏览器原生对话框,因为同步 API 无法等待异步跨 frame 回调。

Web 的 fetch-backed 导航最多保留 100 条类型化历史记录。前进、后退直接恢复 已保存的响应快照,不会重放修改型请求;只有显式调用 reload() 才重新请求。 导航代理拒绝跳转时不会改变当前历史位置。

clearAllWebsiteData 使用结果对象区分完整清理、引擎不支持和原生执行失败。生产环境的注销流程应检查 result.isComplete,否则继续检查 unsupportedDataTypes 和 failures。该接口不会退而清理浏览记录、密码、自动填充或 profile 设置。

Linux 的导航、HTTP 认证、TLS、权限和 JavaScript 对话框回调抛错时会采用安全的 拒绝或取消结果;native 待决请求也会在 30 秒后超时。错误以单行日志记录,既能 定位应用回调问题,又不会永久阻塞 WebKitGTK。

Windows 初始化或渲染失败会显示在组件内,可用 Refresh 重试。渲染失败后 会暂停自动重试,避免布局变化反复启动失败的捕获会话。Install Webview2 仅在错误为 webview2_runtime_unavailable 时显示,用于打开 WebView2 Runtime 官方下载页。重试前会释放未完成初始化留下的资源。

错误码阶段含义
webview2_runtime_unavailablewebview2_runtime指定浏览器路径下没有兼容的 Runtime。
environment_creation_failedwebview2_environmentWebView2 无法创建指定 profile 环境。
winrt_runtime_unavailable / winrt_initialization_failedwinrt_runtime / winrt_initialization渲染器所需 Windows Runtime 无法加载或初始化。
graphics_capture_unavailable / graphics_capture_initialization_failedgraphics_capture当前系统、设备、策略或会话不支持图形捕获。
dispatcher_queue_initialization_faileddispatcher_queue无法复用或创建 UI 线程的 Composition 队列。
d3d_device_creation_failedd3d_deviceDirect3D 硬件设备和 WARP 软件回退均创建失败。
dxgi_device_initialization_faileddxgi_deviceDirect3D 设备没有提供所需的 DXGI 接口。
d3d_interop_initialization_failedd3d_interopWindows Runtime Direct3D 互操作初始化失败。
composition_initialization_failedcompositionWindows Composition compositor 创建失败。
webview_creation_failedwebview2_controller环境创建后 controller 创建失败。
graphics_capture_item_creation_failedgraphics_capture_item无法将 Composition 画面连接到 Windows 图形捕获。
graphics_capture_size_unavailablegraphics_capture_size捕获对象未能提供有效的画面尺寸。
graphics_capture_frame_pool_creation_failedgraphics_capture_frame_pool无法创建 UI 线程帧池。
graphics_capture_frame_handler_registration_failedgraphics_capture_frame_handler无法注册帧回调。
graphics_capture_session_creation_failed / graphics_capture_start_failedgraphics_capture_session / graphics_capture_start无法创建或启动捕获会话。
graphics_capture_resize_failedgraphics_capture_resize无法调整捕获帧池尺寸。
flutter_texture_registration_failedflutter_texture_registrationFlutter 未能注册原生纹理。
invalid_surface_size / webview_surface_update_failedwebview_surface_size / webview_surface画面尺寸无效,或 WebView2 未能应用该尺寸。
webview_visibility_update_failedwebview_visibilityWebView2 未能应用显示状态。
website_data_clearing_failedwebview2_data_window / webview2_data_controller / webview2_data_webview / webview2_profile / webview2_website_data隔离窗口、临时 controller、WebView 访问、profile 查询或清理操作失败。

Windows 原生异常详情包含 stage、十六进制 hresult、有符号 hresultValue、remoteSession,并在检测成功时包含 webView2RuntimeVersion。配置相同的并发 ensureEnvironment 调用只执行一次 原生创建;配置冲突时不会替换正在创建或已生效的环境。

Windows 和 Linux 的无参 ensureEnvironment() 复用已选环境,尚无环境时才初始化 默认配置。显式参数必须与已选完整配置一致,否则返回 environment_configuration_conflict;重复调用严格的 initializeEnvironment 返回 environment_already_initialized。目录无效或不可用时返回 environment_creation_failed,修正路径后可重试。网站数据 manager 会将这些失败 记录在清理结果中,不会转而清理其他环境。

平台限制
Windows必须安装 WebView2 Runtime。
Linux必须安装 WebKitGTK 4.1;标准 Flutter runner 的 GtkOverlay 由插件自动安装。
OHOS需要 OHOS Flutter SDK 和 API 22 或更新版本,ArkWeb 行为会随系统版本和设备变化。
Android能力取决于系统 WebView/Chrome 版本。
iOS/macOS能力取决于 OS 版本和应用 entitlement。