flutter-webview

Flutter WebView

应将 WebView 视为嵌入特权应用进程中的不可信 Web 运行时。除非请求迁移，否则应保留项目当前的 WebView 包、Web 契约、路由器、会话所有者和支持的平台。

不要仅仅因为选择了此技能，就添加 WebView 包、原生清单更改或域名／重定向注册。

预检

阅读 pubspec.yaml、SDK 约束、所选 WebView 包及其版本、平台目标、平台清单和权限声明、加载的来源和重定向、JavaScript 设置和通道、Cookie 和网站数据、身份验证所有权、文件和权限流程、应用导航、生命周期处理及测试。在承诺跨平台行为之前，先确认该包当前支持的平台；Flutter Web 上的嵌入式 Web 内容所用的机制和限制，可能不同于 Android、iOS 或 macOS 上的系统 WebView。

如果原生 Flutter UI 能提供所需的保真度和无障碍支持，则优先用于应用自有的交互。只有在有具体内容或集成需求时才使用嵌入式浏览器。默认情况下，不要将现有包替换为 webview_flutter 或其他依赖项。

按需加载参考资料

• 若需了解来源允许列表、方案、弹出窗口、下载、错误、外部链接、TLS 和浏览器历史记录，请阅读导航和内容策略。
• 若需了解消息架构、来源信任、特权操作、对话框、媒体、摄像头或麦克风请求，以及最小化 JavaScript 启用范围，请阅读JavaScript 桥接和权限。
• 若需了解 Cookie、账号切换、登出清理、文件选择器和下载行为、控制器所有权、进程重建及平台验证，请阅读会话、文件和生命周期。

核心规则

• 将每次导航解析为 URI，并根据明确的方案、规范化主机、端口和路径规则进行判断。字符串前缀不是来源检查。
• 除非内容契约要求，否则应禁用 JavaScript。仅公开范围最小的类型化消息接口，并在更改应用状态或调用原生能力前，在 Dart 中再次验证每个载荷。
• 绝不要将页面标题、URL 片段、JavaScript 消息或匹配的自定义方案视为身份、付款、授权或可信完成状态的证明。应通过其所属的后端或平台协议确认敏感结果。
• 明确哪些 Cookie 和网站数据会被共享、持久化、隔离或清除。登出和账号切换应与应用会话所有者协调。
• 如果所选包提供相应处理机制，应明确处理主框架加载、HTTP、TLS、渲染器、权限、弹出窗口、文件、下载和外部应用的结果。不得绕过证书错误。
• 确保控制器和回调的所有权符合生命周期要求。应防止已销毁屏幕、过期导航或先前账号的回调修改当前状态。

边界

• flutter-authentication 负责 OAuth 或 OIDC、PKCE、已验证的重定向、令牌生命周期、登出语义和账户切换。原生应用授权使用外部用户代理，而不是嵌入式 WebView。
• flutter-navigation 负责 Flutter 路由、深层链接目标、浏览器 URL 同步，以及嵌入页面之外的返回栈正确性。
• flutter-security 负责威胁建模和整个仓库的 WebView 加固审计；此技能实现限定范围内的内容、桥接和生命周期契约。
• flutter-networking 负责常规 API 传输。不要仅仅因为存在 WebView，就通过 JavaScript 转发应用 API 行为。
• flutter-platform-integration 负责自定义原生 WebView 功能或平台视图桥接，以满足现有插件无法支持的必需 API。
• flutter-device-testing 负责在实际设备和模拟器上执行测试；此技能定义必须观察的 WebView 行为。

验证

使用由测试控制的确定性本地或暂存内容，并使用实际支持的平台运行时验证系统 WebView 行为。视情况覆盖允许和阻止的顶层导航、重定向、可观察到的子框架、外部方案、返回行为、JavaScript 禁用和启用状态、格式错误和重放的消息、账户切换和登出、离线和 HTTP 故障、进程重建、回调期间的释放、文件取消和无效选择、权限拒绝，以及下载归属。

记录软件包和版本、平台和 OS、WebView 引擎、测试的源站、JavaScript 和数据存储策略，以及实际观察到的提供方或后端边界。Widget 测试可以验证策略函数和状态归属，但无法证明设备上的系统 WebView 渲染、Cookie 持久性、选择器行为、权限、下载或导航回调。

来源

• Flutter webview_flutter
• 将网页内容嵌入 Flutter Web 应用
• Android WebView 原生桥接风险
• Apple WKWebsiteDataStore
• 适用于原生应用的 OAuth 2.0