前阵子接了个uniapp项目需求一句话App、H5、微信小程序三端都要能看视频视频得走阿里云点播。当时觉得这东西官方文档写得挺全做起来应该不复杂。真动手才发现坑全藏在“uniapp 三端 云点播”这三个词的交叉地带里App端不能用H5那套Aliplayer小程序端又没有现成的播放器SDK连播放凭证过期了怎么自动续这种事官方demo里都只是在初始化时传一次就完事了。我把这个过程完整记录一下从选型、概念梳理、三端接入到凭证续期和排错给后面要接类似需求的人一份能直接照着做的参考。这篇文章适合已经开始用uniapp、但对阿里云点播不熟或者两边都熟但没做过多端适配的朋友读。1. 我为什么放弃了“nginxMP4”这条省事路线1.1 一条MP4直链看似够用实际处处是坑很多项目一开始不会直接上云点播因为视频量少大家习惯性在服务器上开个目录放MP4nginx配好静态访问前端拿一条https://domain/videos/xxx.mp4就能播。在uniapp里这条链路也确实能走通H5端直接用video标签App端用video组件微信小程序把域名加到后台白名单后也能用原生video播。但等你把视频真正发出去问题就来了。第一是启动慢。MP4文件如果moov元数据在文件末尾播放器得先把整个文件尾巴拉下来才能拿到时长和索引用户看到的就是长时间转圈。这个可以用qt-faststart这类工具把元数据挪到文件头补救但每次上传都要处理一遍麻烦。第二是没有多清晰度。用户网速差的时候视频卡成PPT你一点办法都没有不可能同一份视频再转三份不同码率的文件手动切。第三是流量和防盗链。直链一旦被爬走别人可以随便盗用CDN流量哗哗走账单全算你头上。第四是能力缺失。倍速、记忆播放、跑马灯、视频加密这些都得从零写。当时项目里短视频还好客户的一批培训视频都是半小时起步还用MP4直链方案的话基本是拿用户体验开玩笑。1.2 云点播补上了哪些短板阿里云点播VOD做的事简单说就是把“存视频、转码、分发、播放安全”这些脏活全包了。你可以只上传原片点播会自动根据转码模板产出多码率输出播放器拿到视频ID后会自动选择合适清晰度。CDN分发也是阿里云自己的流量走内网回源成本比起公网服务器直出低不少。更关键的是播放安全。点播提供了播放凭证PlayAuth、STS临时凭证、URL鉴权、阿里云视频加密等多层手段。前端拿不到原始文件URL就算别人抓包也只是一串临时凭证过期就失效。这对商业视频、培训课程、知识付费类项目几乎是必选项。1.3 什么场景下依然可以不用云点播也别说我踩了坑就一味劝人上点播。如果项目满足这几条内部后台演示、播放几十秒的短视频、不追求多清晰度、不关心盗链风险、没有专业视频运营需求——那MP4直链video组件完全够用甚至更省事。选型这事没有绝对正确答案关键是别为了技术上的“体面”给项目带来不必要的成本和依赖。我当时坚持上云点播还有一个原因是客户明确要统计观看数据。点播控制台自带播放次数、UV、流量趋势和错误率分析不用自己埋点也能有个基础盘面这对后续运营决策很关键。2. 接入前必须理清的三样东西AccessKey、PlayAuth和STS2.1 AccessKey 是底线绝对不进前端阿里云点播的API调用靠AccessKeyId和AccessKeySecret。只要有了这一对密钥就等于拿到了你账号下视频资源的操作权限。很多人第一次接的时候图省事把AccessKey直接写死在uniapp项目里这是极其危险的行为——H5代码经webpack打包后在浏览器里一跑network面板和源码里就能看到密钥别人可以直接拿它调你的API上传、删除、获取播放地址后果根本不是播放器坏了这么简单。正确的姿势是AccessKey只在你的后端服务里保管前端一律通过自己的接口拿临时凭证。这个和后端ACCESS_KEY的托管方式是一样的必须走环境变量或密钥管理服务绝不能提交进git仓库。2.2 PlayAuth给你视频的“临时入场券”点播最常用的播放方式是vid playAuth。前端只传一个视频IDvid后端拿着AccessKey去调阿里云的GetVideoPlayAuth接口拿到一段PlayAuth字符串和视频元信息返回给前端。播放器用vid playAuth初始化内部自动去CDN拉取可播放的清晰度列表和真实的转码地址。这个设计的好处很明显前端从头到尾不接触任何原始MP4地址开启安全下载或HLS加密后就算抓包拿到播放地址也没法脱离播放器播放。PlayAuth默认有效期只有100秒控制台“配置管理 播放配置”里可以调也就是说它是一张“临时入场券”从后端取到到播放器初始化成功时间窗口很短。所以在接入前你要先和前端约定好**每次进入播放页先请求一次自家后端接口拿PlayAuth再拿它初始化播放器。**不要在前端缓存这个凭证反复用。2.3 STS有更长时效的临时钥匙如果视频比较长或者播放器初始化时间和用户实际点击播放时间隔得比较久比如先进入一个视频列表页用户20秒后才点开播放详情页那100秒的PlayAuth可能就会过期。这时候可以用STS临时凭证方案。STS的全称是Security Token Service你可以通过RAM角色给点播下发一个专属的临时密钥包含AccessKeyId、AccessKeySecret和SecurityToken有效期自己定一般几十分钟到几小时。播放器用STS初始化在有效期内可以反复做资源请求。代价是后端配置复杂度上去了需要建RAM用户、配权限策略、管理角色而且STS一旦泄露攻击者在有效期内也能拿着它访问你的点播资源。所以在移动端App场景下用STS更要谨慎尽量缩短有效期并绑定来源限制。实际项目中如果只是做一个普通视频AppPlayAuth基本够用要是做直播回放、长视频点播或者需要用户反复拖动、切换清晰度的场景STS能省掉很多“凭证过期”导致的播放中断问题。2.4 后端接口的最小实现不管用PlayAuth还是STS前端都只对接自家后端一个接口比如/video/playAuth?vidxxx。这里给一个Node.js的参考实现用阿里云官方alicloud/pop-core包其他语言的思路完全一样const RPCClient require(alicloud/pop-core).RPCClient; const client new RPCClient({ accessKeyId: process.env.ALIYUN_AK_ID, // 环境变量读取千万别硬编码 accessKeySecret: process.env.ALIYUN_AK_SECRET, endpoint: https://vod.cn-shanghai.aliyuncs.com, apiVersion: 2017-03-21 }); async function getPlayAuth(videoId) { const params { VideoId: videoId }; const playAuth await client.request(GetVideoPlayAuth, params, { method: POST }); return playAuth; }注意endpoint的地域要和视频实际所在区域一致否则会报错。前端拿到的返回结构里一般包含PlayAuth和VideoMeta封面、时长、清晰度列表等可以直接用来展示视频信息。3. 一套uniapp代码怎么同时喂饱App、H5和微信小程序3.1 三端方案总览uniapp最大的卖点是一套代码多端编译但视频播放恰恰是“三端差异最明显”的场景。视频播放器涉及大量原生能力不可能一套逻辑通吃。我最终的落地方案是这样的端播放载体推荐方式能用的高级能力H5阿里云Web播放器Aliplayer JSvid playAuth或直接传播放地址多清晰度、倍速、截图、跑马灯、加密播放AppAndroid/iOS原生播放器插件Aliplayer SDK封装vid playAuth/ URL方式能力同SDK播放稳定性远高于H5套壳微信小程序原生video组件后端取播放地址前端用URL播放功能相对受限清晰度切换需自己实现这里要强调一点**不要试图在App端用WebView套H5播放器。**虽然省事但WebView里的视频播放会出现层级遮挡、黑屏、播放器不跟随滚动等各种兼容性问题我后面会详细说坑。3.2 H5端挂载时机别踩坑H5端我用的Aliplayer按官方文档在index.html里引JS和CSSlink relstylesheet hrefhttps://g.alicdn.com/de/prismplayer/2.9.17/skins/default/aliplayer-min.css / script charsetutf-8 typetext/javascript srchttps://g.alicdn.com/de/prismplayer/2.9.17/aliplayer-min.js/script然后在页面模板放一个容器view classvideo-container view :idplayerId classplayer/view /view初始化代码必须等DOM渲染完成后再执行uniapp里要写在onReady生命周期里或者用nextTick包裹。新手最容易把初始化写在onLoad或created里此时页面节点还没渲染出来Aliplayer就会报“找不到容器”。onReady() { uni.request({ url: https://your-api.com/video/playAuth, data: { vid: this.videoId }, success: (res) { this.$nextTick(() { this.player new Aliplayer({ id: this.playerId, vid: this.videoId, playauth: res.data.data.playAuth, width: 100%, height: 100%, autoplay: false, controlBarVisibility: click, useH5Prism: true }, () { console.log(播放器初始化成功); }); }); } }); }这里注意几个细节容器id要保证页面内唯一vue页面多实例复用时很容易因为id重复导致播放器初始化错乱。autoplay对移动端H5不友好iOS下很容易因为自动播放策略被拦截建议默认设为false。如果页面在vue的v-if里控制显示切走时记得调用this.player.dispose()销毁播放器否则切回来会初始化一堆重复实例内存和事件全乱。3.3 App端用原生插件别自己套WebViewApp端不要在WebView里嵌套H5播放器。原因如下WebView里的视频是私有控件在Android上容易浮在所有页面之上弹窗、自定义导航栏都遮不住它体验很差。iOS上WebView全屏播放的时候状态栏、转屏控制、音量控制都可能不听话。正确做法是在DCloud插件市场搜“阿里云播放器”或“阿里云点播”找基于Aliplayer原生SDK封装的uniapp原生插件。付费插件基本都有免费试用挑选一看是否支持私有加密视频二看是否有缓存、倍速、多清晰度等能力三看维护频率和评价。我使用的插件暴露的API大致是这样const aliyunPlayer uni.requireNativePlugin(AliyunPlayer); aliyunPlayer.init({ vid: this.videoId, playAuth: this.playAuth, autoPlay: false, // 按需关闭不需要的功能按钮 disable: [screenShot, speed, quality] }, (ret) { console.log(播放器初始化结果, ret); });不同插件的API命名略有差异但底层逻辑一致vid playAuth初始化播放器自动完成鉴权、拉流、清晰度切换。App端用原生插件还有一个好处——它内部的网络请求、解码、渲染都是原生实现在低端Android机上的表现远好于WebView跑H5播放器。接入原生插件后uniapp Manifest.json的“App原生插件配置”里会多出对应项如果用的是云端打包记得选上插件并重新打自定义调试基座测试否则原生插件不会生效。这就是热词里“uniapp manifest配置”“uniapp离线打包uts插件怎么使用”等问题最常出现的地方。3.4 小程序端用原生video组件接播放地址微信小程序端的情况最特殊。阿里云没有给小程序的播放器SDK所以不能直接复用App端的原生插件也不能在H5里用WebView套Aliplayer。目前通用的做法是后端调阿里云的GetPlayInfo接口拿到可以直接播放的MP4或HLS地址前端用小程序原生video组件来播。video :srcplayUrl controls autoplayfalse :postercoverUrl erroronVideoError /video后端拿到播放地址后前端请求一次接口赋值给src即可。这里有三个必须注意的坑第一小程序对网络请求有域名白名单校验。拉取播放地址的接口域名要加进后台的request合法域名视频播放域名要加进downloadFile合法域名具体以微信公众平台实际校验为准。很多人只配了request结果播放的时候一直提示“域名不合法”就是这个原因。第二不要在小程序里用web-view嵌套网页播放器页面。微信对web-view的域名限制很严而且视频体验会差很多。第三如果想做清晰度切换小程序端没有现成的清晰度面板需要自己拉多码率地址用video的多个src或切换src实现。这部分代码得为小程序单独写条件编译。3.5 条件编译一套页面承载三套逻辑既然三端没法共用播放器那就做成“一套页面 条件编译”。在播放页里按平台区分代码块// #ifdef H5 // 这里走 Aliplayer JS 逻辑 this.initH5Player(); // #endif // #ifdef APP-PLUS // 这里走原生插件逻辑 const aliyunPlayer uni.requireNativePlugin(AliyunPlayer); // #endif // #ifdef MP-WEIXIN // 这里走接口拉播放地址 video 组件逻辑 this.fetchPlayUrl(); // #endif这样可以最大程度复用页面上的封面、标题、互动区域等UI逻辑只是播放器内核各走各的。三个平台的代码互不影响也不会导致编译包变大。4. 播放凭证只有100秒鉴权过期是播放事故的最大来源4.1 为什么一个凭证撑不完整个视频很多人第一次接点播时都会问我在页面加载时拿了一个PlayAuth初始化播放器然后用同一个凭证播完了整个视频没出问题是不是凭证不只有100秒其实这是因为部分播放器在初始化之后会内部刷新凭证或拉取资源时不需要再次鉴权。但在不同网络环境下特别是CDN回源和鉴权校验不稳定的情况下播放器在中途可能需要重新鉴权比如从标清切到高清、从播放界面切出去再回来、视频seek到很靠后的位置。如果原来的凭证已经过期播放器就会卡在正在加载或者直接报错。所以正确的认知是PlayAuth是“启动钥匙”不是“全程通行证”。播放器初始化之后资源真正拉取可能是在你点击播放键后才发生的隔着十几秒甚至几十秒凭证过期完全可能。4.2 前端统一的鉴权刷新思路我在项目里给播放器包了一个统一服务所有播放器的初始化、错误处理、凭证刷新都走这个服务。核心逻辑进入播放页先调用后端接口拿PlayAuth。播放器碰到error事件时先判断错误类型属于鉴权失败或凭证过期就重新调后端接口拿新凭证然后重新初始化播放器。如果是网络错误做一次自动重试重试次数限制在3次以内避免网络抖动时反复“摔跤”。伪代码大致这样class VODPlayer { async init(vid) { this.vid vid; this.playAuth await this.fetchPlayAuth(vid); this.createPlayer(); } createPlayer() { this.player new Aliplayer({ id: this.containerId, vid: this.vid, playauth: this.playAuth, // ... }); this.player.on(error, (e) { if (this.isAuthError(e)) { this.refreshPlayAuth(); } else { this.retry(); } }); } async refreshPlayAuth() { this.playAuth await this.fetchPlayAuth(this.vid); this.createPlayer(); } }这里要注意的是每次重新初始化播放器时最好先把旧的播放器实例销毁避免重复创建。Aliplayer有dispose()方法原生插件一般也有对应的销毁接口如destroy()或release()。不销毁就直接重新创建后续事件会多路触发最后可能同时有几个播放器在抢宿主层的渲染资源。4.3 常见错误与兜底策略错误现象可能原因兜底策略播放器初始化直接报错凭证无效、vid不存在、鉴权参数缺失重新取凭证后再init播放到一半卡住网络波动、CDN回源失败自动重试一次换清晰度切换清晰度失败旧凭证过期新凭证未拿到先刷新凭证再发起切换请求视频只能播前几秒未开启安全下载/加密、URL鉴权过期检查控制台播放配置换新播放地址不管用哪种兜底核心原则是**错误处理必须可观测。**播放器的错误事件一定要上报到日志系统不能只在前端console打一条。线上用户报“看不了视频”时你才能在后台按视频ID查到具体是凭证过期、网络超时还是解码失败不然只能靠猜。4.4 用URL直连方式替代凭证方式的取舍有些项目为了省事后端直接调GetPlayInfo拿播放URL返回给前端前端用URL初始化播放器或video标签播放。这在开发阶段很香因为一眼能看到真实地址调试方便。但隐患也大URL里通常带签名参数有有效时间过期后同样会播放失败而且URL本身暴露了CDN地址别人完全可以用另一个播放器直接拉流防盗链形同虚设。所以我的经验是**H5和App端尽量走vid playAuth小程序端迫不得已才走URL。**如果视频不是机密内容URL方案可以省很多凭证刷新的代码一旦涉及付费内容或者内部培训必须回到凭证方式。5. 高频播放问题的完整排查链路5.1 安卓WebView里视频黑屏但进度条在走这个坑我在App端的H5播放器方案里踩过。现象是Android手机上打开页面能看到播放器控制条、进度条也在走但画面区域是黑屏。排查链路先在浏览器开发者工具里用移动端模拟打开同一播放页看是否复现。如果浏览器里正常说明问题出在Android WebView的渲染层。检查项目是否开启了硬件加速。部分低版本Android WebView对视频合成有Bug视频会渲染到GPU表面的不同层级导致黑屏。在AndroidManifest里给activity加上android:hardwareAcceleratedtrue或者在WebView设置里开启setMediaPlaybackRequiresUserGesture(false)能解决一部分机型的问题。另一种可能是视频编码格式不被WebView支持。H5播放器默认优先HLS如果你的CDN回源只输出MP4且编码是HEVC部分WebView不支持解码就会黑屏。这时可以强制让Aliplayer走useH5Prism: true或format: m3u8或者后端配置转码模板兼容H.264AAC输出。最后我的结论是不建议在App端用WebView播放视频直接上原生插件是从根上解决问题的办法。5.2 H5播放卡在加载/只能播几秒H5页面上视频表现“只能播几秒就停”排查方向先锁定网络和CDN用curl直接请求播放地址看返回状态码。如果是403多半是防盗链/URL鉴权配置问题需要在控制台把播放域名或者白名单配好。如果返回206是正常的说明CDN支持Range请求问题不在鉴权。这时检查播放器是不是用了完整URL还是只用了相对路径。看Network面板的请求瀑布。如果某个分片耗时居高不下多半是CDN节点回源慢或者热点文件没有预热。点播控制台可以对视频做预热把热点视频提前推送到边缘节点能明显改善首次播放卡顿。另外H5播放器报MEDIA_ERR_SRC_NOT_SUPPORTED错误多半是音频编码不是AAC而是别的编码格式。阿里云转码模板一般默认输出AAC但如果你用自定义模板或者直接上传文件后没转码就播放就容易遇到。所以上传的视频一定要走转码流程不要用原片直接当播放源。5.3 小程序端报“域名不在合法域名列表”小程序播放视频报错时最常见的提示不是“无法播放”而是“url不在以下request合法域名列表中”或者“downloadFile合法域名校验失败”。排查步骤先确定报错的是接口请求还是视频播放。接口请求报域名不合法的去微信公众平台后台“开发管理 开发设置 服务器域名”把接口域名加进request合法域名。播放地址报域名不合法的把视频CDN域名加进downloadFile合法域名。这里有个容易被忽略的事如果播放地址用的CDN域名和接口域名不是同一个两个都要配。还有微信小程序要求域名必须支持HTTPS如果是HTTP地址直接报错。5.4 App端打包后播放器初始化失败H5端和App端调试时播放器都正常唯独打包成安卓安装包后初始化失败这种问题十有八九出在原生插件打包配置上。uniapp同时支持云端打包和本地离线打包如果你用了阿里云播放器的原生插件在云端打包时需要在“App原生插件配置”里勾选插件如果是离线打包则要确认Android工程的gradle里已经引入对应aar包并且清单文件权限齐全。这种问题特别容易在“Hbuilder X直接运行到手机”时被掩盖——因为开发运行时会自动把插件打进调试基座看起来一切正常。一旦正式打包配置漏一步就整个播放器起不来。所以项目里要有一个检查单原生插件是否勾选、版本是否一致、自定义调试基座是否重新打包、manifest里是否声明了相关模块权限。5.5 iOS / Android 表现不一致的排查思路两套系统对视频格式的默认支持不同。iOS对HLS支持非常好Android对HLS的支持则参差不齐尤其是非旗舰机型。如果你想做一套省心的逻辑最好让点播转码模板同时输出HLS和MP4两种格式在H5和App端优先用HLS。小程序Android端如果遇到HLS播放卡顿或无法seek兜底改用MP4地址。出现iOS/Android不一致时不要一上来就怀疑播放器的问题先用浏览器或原生播放器直接播放原始地址确定是“解码问题”还是“播放器问题”再决定是调整转码模板还是换播放器SDK。这是排查多端视频问题最有效的方法能把问题范围从几十个变量缩小到两三个。6. 观感与体验的几个进阶操作6.1 清晰度切换的自主实现vid playAuth模式下H5和App端播放器自带清晰度切换这一般不用你再写。但小程序端只能用video组件清晰度切换得自己兜。做法是后端在GetPlayInfo返回的PlayInfoList里同时返回多个清晰度的播放地址前端做成一个清晰度按钮组点击时切换src。切换时注意保留当前播放进度不要一换地址就从头开始。可以在切换前读取video组件的currentTime切换后手动设置到该进度onQualityChange(url, time) { this.playUrl url; this.$nextTick(() { this.videoContext.seek(time); }); }配合uni.createVideoContext(videoId, this)拿到的实例来做seek和play体验能接近App/H5的播放器。6.2 倍速播放与记忆进度倍速不用多说H5的Aliplayer自带倍速按钮App原生插件通常也自带或可以传参开启小程序端video组件没有原生倍速按钮但可以通过playbackRate属性或videoContext.playbackRate()接口设置。要注意的是倍速在某些老机型上音画会不同步尤其1.5倍以上这类问题无解只能加一个“如果播放器报错自动降回1倍速”的兜底。记忆播放进度是另一个刚需。做法很简单播放器监听timeupdate事件每播5秒秒级节流一次把videoId percent currentTime存到服务端或本地storage再次进入播放页时读取进度如果大于某个阈值比如5秒弹窗提示“继续观看”。uniapp里App端可以用uni.setStorageSync三端通用服务端存进度则能跨端同步。6.3 封面与首帧如果视频列表页需要显示封面别用实时解码截图直接用点播上传时设置的封面图URL或者用转码完成后自动生成的首帧截图。在后端接口返回字段里把封面地址和标题一起给前端前端loading状态就能变成一张静态图体验会好很多。另外不要在用户进入播放页时立刻autoplay拉起视频流很多场景下用户需要先看页面标题和简介再决定是否播放。拉流和初始化播放器是两件事播放器可以先初始化等用户点播放按钮再play()这样首帧和启动开销都明显更平滑。6.4 跑马灯、加密和防盗链跑马灯能防止录屏盗录播放器初始化时传入跑马灯配置就行。H5和App端都有对应配置项小程序端没有现成能力只能自己在视频上覆盖一层半透明文字轮播效果差不少但聊胜于无。加密方面如果视频是付费内容建议用阿里云视频加密私有加密或HLS标准加密。这两种加密方式要求播放器必须配套解密能力H5端用AliplayerApp端只能使用官方播放器SDK所以如果你的方案里用到了第三方播放器加密这条路基本走不通。这也是选型时的一个重要约束——所有安全能力和你的播放器形态是绑定关系。防盗链则可以在控制台配置Referer防盗链和URL鉴权。注意配置后一定要在测一遍H5页面正常能播App原生播放器因为请求头不带浏览器Referer可能直接被防盗链干掉。所以防盗链配置和播放端方案必须一起测试不能一边改一边测。6.5 数据埋点与播放质量监控点播控制台自带播放统计能看播放次数、播放时长、并发峰值这类数据。但如果你想看更细的“用户看视频在第10秒就退了”、分清晰度的卡顿率就需要自己在播放器事件里埋点。H5和App端可以监听start、pause、ended、error等事件把事件上报到自己后端或云日志服务。小程序端则监听onPlay、onPause、onEnded、onError。埋点数据最直接的价值是排障。比如某个视频在Android端报错率异常高你在后台能看到错误码集中为解码失败就能推断是转码模板或Android机型兼容问题这种问题在用户反馈之前根本发现不了。根据我踩过几次坑的经验视频播放这类功能最忌讳的是“看着能播就行”。播放器是强交互、强网络、强兼容性的组件三端差异又大上线前至少要在iOS、Android、微信开发者工具、Safari和Chrome等环境各过一遍把鉴权刷新、错误上报、封面、进度记忆这些边缘情况都验证好才敢交测试。如果你们项目里也有视频需求可以先从这篇的选型和凭证部分看起然后根据实际端类型补齐对应代码。搞定了三端播放之后再考虑加密、防盗链这些锦上添花的能力一步步来稳。