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

- **ID:** `flutter/platform-view-assertion-error`
- **领域:** flutter
- **类别:** runtime_error
- **验证级别:** ai_generated
- **修复率:** 80%

## 根因

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

## 版本兼容性

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

## 解决方案

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
   ```

## 无效尝试

- **Disable hybrid composition by setting AndroidViewSurface.mode = AndroidViewSurfaceMode.graphics** — 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. (60% 失败率)
- **Set enableImplicitScrolling to false on all platform view widgets** — Implicit scrolling is unrelated to vertical sync; this change breaks scrolling behavior without fixing the assertion. (80% 失败率)
- **Upgrade to Flutter 3.16+ without any other changes** — The assertion persists in newer versions if the platform view is still used in a background isolate context. (50% 失败率)