flutter runtime_error ai_generated true

平台视图断言失败：垂直同步已禁用

Platform view assertion failure: vertical sync disabled

ID: flutter/platform-view-assertion-error

其他格式: JSON · Markdown 中文 · English
80%修复率
82%置信度
1证据数
2023-06-15首次发现

版本兼容性

版本状态引入弃用备注
Flutter 3.10.0 active — — —
Flutter 3.13.9 active — — —
Android 12+ active — — —
iOS 16+ active — — —

根因分析

混合组合平台视图在框架尝试在垂直同步禁用时渲染时引发断言失败，通常是由于后台隔离渲染或无头模式。

English

Hybrid composition platform views cause assertion failure when the framework attempts to render with vertical sync disabled, often due to background isolate rendering or headless mode.

generic

官方文档

https://docs.flutter.dev/platform-integration/platform-views

解决方案

  1. Ensure platform views are only created on the main isolate. Wrap platform view creation in a check: if (Isolate.current == Isolate.main) { /* create view */ } else { /* fallback or send to main isolate */ }
  2. Use virtual display mode instead of hybrid composition by setting AndroidViewSurface.mode = AndroidViewSurfaceMode.graphics in the AndroidManifest.xml metadata
  3. Disable headless mode in Flutter engine by setting --enable-headless-rendering=false in run arguments

无效尝试

常见但无效的做法:

  1. Disable hybrid composition by setting AndroidViewSurface.mode = AndroidViewSurfaceMode.graphics 60% 失败

    This reverts to virtual display mode which has its own rendering bugs and memory leaks, and does not address the root cause of the vertical sync issue.

  2. Set enableImplicitScrolling to false on all platform view widgets 80% 失败

    Implicit scrolling is unrelated to vertical sync; this change breaks scrolling behavior without fixing the assertion.

  3. Upgrade to Flutter 3.16+ without any other changes 50% 失败

    The assertion persists in newer versions if the platform view is still used in a background isolate context.