外观
hear 预置资源与离线打包
资源来源
预置图片、训练音频、音乐与视频统一保存在 apps/hear/public/。STATIC_ASSET_BASE 使用本地路由基址 /hear,开发时读取 Vite public,Android 中读取完整 H5 包。
家庭上传资料仍使用服务端返回的 URL,不属于预置离线资源。离线预置不代表账号、家庭同步与更新检查可以离线执行。
构建与更新
Vite 保持 copyPublicDir: true,将 public 全部文件复制到 public/hear/。scripts/pack-h5.mts 从完整产物生成 client/android/h5-packages/hear/hear-{version}.zip,包含 index、version.json(应用与版本)及 package-files.json(文件大小清单)。H5 zip 与 APK 分离,APK 不含业务散文件或 zip。
首次启动由原生页面下载最新完整包,校验 SHA-256、清单与包内版本,解压和校验完成后激活。下载期间显示进度,离线或失败时可重试/退出;已有有效完整包时可立即离线启动,后续联网检查更新。
WebView 通过 appassets.androidplatform.net/hear/ 读取当前本地目录,原生播放器读取同一激活版本的文件。旧 prefs 版本不能证明本地文件可用,启动会检查入口、版本与新包文件清单;缺失时恢复上一完整版本或重新下载,APK 无内置兜底。
public 内容参与现有 H5 构建指纹。新增媒体需重新构建并发布完整 H5;H5 更新包限制 300 MiB,下载、解压及保留上一版需要额外空间。APK 变小不代表完整资源存储量减少。
全部 Android flavor 均使用这一分发方式;局域网 dev 模式仍直连开发服务器。上传先完成 H5 与必要 APK,最后发布 manifest,避免首启获取不存在的资源包。
Web 上传边界
deployAppsVue 仅对 hear 遍历 public 源文件清单,映射到构建输出后从服务器 HTML 上传与七牛静态文件上传中排除。新目录、嵌套资源与根级文件均按源文件清单处理;其他应用不受影响。
上传过滤不删除本地 public/hear 文件,因此 Web 发布后的 H5 联动打包仍取得完整资源。Web 发布入口保留,但不保证预置媒体在线可用;完整 H5 zip 仍按安卓更新流程上传。
本次不删除线上旧媒体,避免旧客户端失效。
旧缓存兼容
新版前端不再展示“清空静态资源缓存”,不再调用对应桥方法。原生 HTTP 缓存与桥实现暂保留,供旧 H5 回退兼容使用;新版预置资源走包内路径,不再受下载、过期或缓存淘汰影响。
不主动清除设备旧缓存,不修改学习记录、账号及家庭数据。旧 H5 回退后的远程资源行为沿用旧逻辑。
验证
大资源上传与恢复
发布入口配置 auto 模式:资源达到 20 MiB 时使用七牛分片 v2,默认分片 4 MiB;小文件保留表单上传。调用上传方法前立即记录文件大小和开始时间;进度显示已传字节、总量、已耗时与预计剩余时间,日志按秒节流。预计剩余时间按首次回调之后新增的字节估算,数据不足时显示“估算中”,重试进度回退时重新估算;网速波动或重试会影响估算结果。数据达到 100% 时显示“等待服务端确认”,收到成功响应后记录总耗时,包含初始化和重试等待。进度随 SDK 回调更新,不提供定时心跳。上传库保留原始错误原因及可用的错误码、状态码和请求标识,瞬时网络错误采用有限退避重试,权限或参数错误直接失败。
断点记录放在仓库根目录 .temp/qiniu-upload/,不保存凭据。记录按目标、文件路径、大小、修改时间和分片参数隔离,成功清理、失败保留,同一记录不允许并发写入。删除该目录仅影响续传效率。连接与响应等待超时均为单次请求限制,不代表整个上传的总期限。
项目已接入 nsuite@2.3.0 并同步依赖锁文件。分片阈值可通过 multipartThreshold 参数按字节配置;当前发布入口未传该参数,使用默认值 20 MiB。
上传失败后保留 zip 和发布目录中的 manifest,直接执行部署入口可避免重复打包与递增版本。在仓库根目录,以虚构 flavor sample 为例,分别设置 $env:H5_ONLY = "1"、$env:H5_PACKAGE_PATH = "<已有 zip 的绝对路径>",再执行:
powershell
node --env-file-if-exists=.env client/android/scripts/deploy.mts release sample1
已有 manifest 必须与 zip 的应用和 H5 版本一致;恢复入口先校验,不重新生成清单。完整 APK 发布不设置 H5_ONLY,并保留对应 APK。结束后清除本次环境变量。顶层发布入口可能因指纹未变化跳过,不能据此判断上传成功。
始终按 H5 → 可选 APK → manifest 上传,资源失败则不更新清单、不刷新 CDN。真实网络中断恢复与对象完整性需在另行授权的隔离对象路径验收。
回归检查
- Node 测试验证 public 上传排除、特殊文件名、代码保留及其他 flavor 默认行为。
- 构建后逐文件比较源 public、Vite 输出和独立 H5 zip 的路径与哈希。
- 真机验证新装首次联网下载与离线失败重试、图片显示、音频播放、视频播放与拖动,以及热更后断网和失败回退。
- 覆盖安装后本地完整包的复用及恢复需单独验证;编译通过不能替代设备验收。