WebToApp 中文文档 下载 App

预览正常导出功能丢失：宿主路径 vs Shell 路径的配置漂移

问题现象

在 WebToApp 预览时一切正常：广告拦截生效、JS 脚本被注入、指纹伪装成功、资源加密生效。但导出 APK 后安装到真机上测试，发现这些功能都消失了——广告回来了、脚本没执行、UA 仍然是 WebView 默认的。

根本原因

WebToApp 有两条不同的执行路径：

宿主路径（预览）

预览 → 构建器自身的 classpath → 直接读 Room 数据库里的应用配置 → WebView 加载

预览时一切代码都在构建器进程的 classpath 上运行，配置直接从内存里的 Room 对象读取，没有任何序列化/反序列化环节。

Shell 路径（导出）

导出 APK → ShellModeManager 读取嵌入在 APK 内部的 app_config.json → 反序列化 → WebView 加载

导出的 APK 是一个最小化壳。启动时 ShellModeManager 从 JSON 文件里读配置，反序列化后驱动运行时。如果某个配置字段在序列化或反序列化环节有问题，或者字段本身在 JSON schema 里有定义但在 Shell 路径的代码里没有正确消费，导出 APK 里就丢失了这个功能。

常见的漂移点

根据开发者文档，以下配置最容易出现预览正常但导出丢失：

配置项原因
资源加密加密密钥需要在 Shell 路径里重新读取，偶尔会读不到
JS/CSS 注入注入的脚本路径在 JSON 里的存储格式和 Shell 路径的期望格式不一致
MV3 扩展扩展的 CRX 文件在 APK 里的位置需要在 Shell 路径里正确解析
hosts 去广告规则列表在 JSON 里是数组，但 Shell 路径里可能只读取前 N 个
TLS 指纹伪装GCM 加密配置需要 Shell 路径完整支持

解决方法

方法 1：全量重建（最常用）

构建对话框里有一个「全量重建」选项。默认情况下构建器会做增量构建——只重新打包 APK 里有变化的部分。全量重建会跳过增量逻辑，从模板 APK 开始，重新走完整的打包流程。

遇到预览/导出差异时，先勾选全量重建，重新构建一次。很多漂移问题只是增量构建的缓存没有刷新，全量重建就能解决。

方法 2：检查配置是否正确保存

在「编辑核心配置」和「编辑通用配置」之间来回切换一次，确保所有字段都被正确序列化到 Room 数据库。然后再构建。

方法 3：用 Agent 工具检查配置 JSON

打开 Agent，让它「导出当前应用的配置 JSON」——WebToApp Agent 有这个工具。查看导出的 JSON 是否完整、字段值是否正确。如果 JSON 本身就是错的，问题在保存环节；如果 JSON 是对的但导出 APK 里功能丢失，问题在 Shell 路径的消费环节。

方法 4：重启构建器

偶尔 Room 数据库的缓存会导致配置读取不一致。彻底关闭 WebToApp（在应用管理里强制停止），重新打开，进入应用编辑界面，保存一次，然后重新构建。

如何减少漂移