企业官网建设流程全解析

前阵子接了个uniapp项目，需求一句话：App、H5、微信小程序三端都要能看视频，视频得走阿里云点播。当时觉得这东西官方文档写得挺全，做起来应该不复杂。真动手才发现，坑全藏在“uniapp + 三端 + 云点播”这三个词的交叉地带里：App端不能用H5那套Aliplayer，小程序端又没有现成的播放器SDK，连播放凭证过期了怎么自动续这种事，官方demo里都只是在初始化时传一次就完事了。

我把这个过程完整记录一下，从选型、概念梳理、三端接入，到凭证续期和排错，给后面要接类似需求的人一份能直接照着做的参考。这篇文章适合已经开始用uniapp、但对阿里云点播不熟，或者两边都熟但没做过多端适配的朋友读。

1. 我为什么放弃了“nginx+MP4”这条省事路线

1.1 一条MP4直链看似够用，实际处处是坑

很多项目一开始不会直接上云点播，因为视频量少，大家习惯性在服务器上开个目录放MP4，nginx配好静态访问，前端拿一条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和STS

2.1 AccessKey 是底线，绝对不进前端

阿里云点播的API调用靠AccessKeyId和AccessKeySecret。只要有了这一对密钥，就等于拿到了你账号下视频资源的操作权限。很多人第一次接的时候，图省事把AccessKey直接写死在uniapp项目里，这是极其危险的行为——H5代码经webpack打包后在浏览器里一跑，network面板和源码里就能看到密钥，别人可以直接拿它调你的API上传、删除、获取播放地址，后果根本不是播放器坏了这么简单。

正确的姿势是：AccessKey只在你的后端服务里保管，前端一律通过自己的接口拿临时凭证。这个和后端ACCESS_KEY的托管方式是一样的，必须走环境变量或密钥管理服务，绝不能提交进git仓库。

2.2 PlayAuth：给你视频的“临时入场券”

点播最常用的播放方式是vid + playAuth。前端只传一个视频ID（vid），后端拿着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更要谨慎，尽量缩短有效期并绑定来源限制。

实际项目中，如果只是做一个普通视频App，PlayAuth基本够用；要是做直播回放、长视频点播，或者需要用户反复拖动、切换清晰度的场景，STS能省掉很多“凭证过期”导致的播放中断问题。

2.4 后端接口的最小实现

不管用PlayAuth还是STS，前端都只对接自家后端一个接口，比如/video/playAuth?vid=xxx。这里给一个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最大的卖点是一套代码多端编译，但视频播放恰恰是“三端差异最明显”的场景。视频播放器涉及大量原生能力，不可能一套逻辑通吃。我最终的落地方案是这样的：

这里要强调一点：**不要试图在App端用WebView套H5播放器。**虽然省事，但WebView里的视频播放会出现层级遮挡、黑屏、播放器不跟随滚动等各种兼容性问题，我后面会详细说坑。

3.2 H5端：挂载时机别踩坑

H5端我用的Aliplayer，按官方文档在index.html里引JS和CSS：

<link rel="stylesheet" href="https://g.alicdn.com/de/prismplayer/2.9.17/skins/default/aliplayer-min.css" /> <script charset="utf-8" type="text/javascript" src="https://g.alicdn.com/de/prismplayer/2.9.17/aliplayer-min.js"></script>

然后在页面模板放一个容器：

<view class="video-container"> <view :id="playerId" class="player"></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端：用原生插件，别自己套WebView

App端不要在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 :src="playUrl" controls autoplay="false" :poster="coverUrl" @error="onVideoError" ></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 常见错误与兜底策略

不管用哪种兜底，核心原则是：**错误处理必须可观测。**播放器的错误事件一定要上报到日志系统，不能只在前端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:hardwareAccelerated="true"，或者在WebView设置里开启setMediaPlaybackRequiresUserGesture(false)，能解决一部分机型的问题。
• 另一种可能是视频编码格式不被WebView支持。H5播放器默认优先HLS，如果你的CDN回源只输出MP4且编码是HEVC，部分WebView不支持解码，就会黑屏。这时可以强制让Aliplayer走useH5Prism: true或format: 'm3u8'，或者后端配置转码模板兼容H.264+AAC输出。

最后我的结论是不建议在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端用Aliplayer，App端只能使用官方播放器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等环境各过一遍，把鉴权刷新、错误上报、封面、进度记忆这些边缘情况都验证好，才敢交测试。如果你们项目里也有视频需求，可以先从这篇的选型和凭证部分看起，然后根据实际端类型补齐对应代码。搞定了三端播放之后再考虑加密、防盗链这些锦上添花的能力，一步步来，稳。