移动端学习产品的难点不在于“把页面做出来”而在于同一套学习状态要跨越 App、小程序和 H5同时经受弱网、系统切后台、播放器生命周期和高频进度事件的考验。织码在线教育系统以UniApp Vue 3 uview-plus为基础把平台差异收敛到适配层把课程学习过程抽象为可恢复、可重试、可观测的状态链路。一、架构边界跨端框架解决交付业务层解决一致性建议将移动端拆成四个边界页面与组件层、状态与缓存层、平台适配层、统一请求层。课程页不直接调用原生能力播放器不直接修改全局业务状态所有跨端差异通过组件或工具函数暴露稳定接口。边界主要职责关键约束页面组件组合课程卡片、播放器、进度条不写平台判断状态缓存用户、课程、播放进度细粒度更新避免全页刷新平台适配视频、全屏、后台音频、网络条件编译集中管理请求服务鉴权、超时、重试、错误码写操作具备幂等语义二、请求层移动网络下的失败必须可解释统一请求封装至少要处理四类结果HTTP 成功且业务成功、登录态失效、业务错误、网络失败。对于 GET 请求可以有限重试对于进度保存、考试提交等写请求应携带幂等键不能简单重放。constRETRYABLE[ETIMEDOUT,NETWORK_ERROR]exportasyncfunctionrequest(options){constrequestIdoptions.methodPOST?uuid():undefinedconstresawaituni.request({url:BASE_URLoptions.url,method:options.method||GET,data:options.data,timeout:8000,header:{token:userStore.token||,X-Request-Id:requestId}})if(res.statusCode401||res.data.code401){awaituserStore.refreshOrLogout()}if(res.statusCode!200||res.data.code!200)thrownormalizeError(res)returnres.data}接口错误需要统一映射为可展示文案同时保留 traceId 上报日志。这样用户看到“请重试”时研发仍能在服务端定位具体请求。三、平台能力适配条件编译不等于复制三份页面#ifdef APP-PLUS、#ifdef MP-WEIXIN和#ifdef H5适合包住平台属性或原生调用不适合在每个业务页面复制完整模板。可以定义播放器适配接口exportconstplayerAdapter{play:()videoContext?.play(),pause:()videoContext?.pause(),seek:(seconds)videoContext?.seek(seconds),fullscreen:()videoContext?.requestFullScreen()}App 侧可接入后台音频和原生权限小程序侧重点是网络变化与组件限制H5 侧需要处理自动播放策略、浏览器缓存和全屏 API。统一接口让课程业务只关心“播放、暂停、跳转、错误”这些领域事件。四、播放状态机恢复、上报和退出要有明确时序播放器可以抽象为INIT - LOADING - PLAYING - PAUSED/ENDED任意阶段都可能进入ERROR。进入课程页先获取播放地址和历史进度只有两者准备完成后才初始化initialTime否则容易出现先从 0 秒播放、随后突然跳转的闪动。TransactionalpublicvoidsaveProgress(LonguserId,ProgressCommandcmd){checkChapterBelongsToCourse(cmd.getChapterId(),cmd.getCourseId());ProgressoldprogressMapper.find(userId,cmd.getChapterId());if(oldnull||cmd.getCurrentTime()old.getCurrentTime()){progressMapper.upsert(userId,cmd.getChapterId(),Math.min(cmd.getCurrentTime(),cmd.getDuration()),cmd.getRequestId());}}客户端按时间节流上报暂停、退出和结束时立即 flush服务端以章节为粒度做最大值更新并校验currentTime duration。这可以避免弱网重试导致进度回退也能降低频繁写库的压力。五、性能与可观测性从“感觉流畅”变成可量化性能优化要拆成网络、渲染、媒体和状态四层接口分页与缓存课程元数据列表触底加载、图片懒加载和分段渲染视频先显示封面进入可视区后再创建播放器Pinia 按字段更新避免进度变化触发整页重绘。可观测指标建议包括首屏渲染时间、接口 P95、视频起播耗时、播放错误率、进度上报成功率、页面崩溃率。指标按端、系统版本、机型和网络类型切分才能识别“某一类设备在弱网下起播失败”的真实问题。六、安全与发布移动端只是可信边界之外课程视频地址不应硬编码在前端。服务端鉴权后返回短时效签名 URL接口仍需校验用户是否拥有课程权限客户端 token 放在安全存储中日志禁止打印 token 和完整播放地址。发布前还应检查隐私权限说明、异常上报脱敏和不同端的资源包大小。七、总结一套跨端代码的价值最终取决于是否建立了清晰的工程边界。UniApp 负责多端交付适配层负责平台差异请求层负责失败语义播放器状态机负责断点续播进度接口负责幂等与一致性指标体系负责持续改进。如需私有化部署报价、远程产品演示可访问官网 https://www.weavecodes.com/ 私信作者领取企业落地案例。断点续播进度接口负责幂等与一致性指标体系负责持续改进。