Web 端上传 SDK

更新时间：2025-08-22

对于浏览器上传音视频的场景，智能点播平台提供了Web端上传SDK。

引入方式

script引入

使用CDN资源，在html中通过script标签引入sdk资源：

                HTML
                
                <script src="https://bce.bdstatic.com/lib/@baiducloud/media-sdk/{版本号}/vod-js-sdk.js"></script>

例如：

                HTML
                
                <!-- 指定版本 -->
<script src="https://bce.bdstatic.com/lib/@baiducloud/media-sdk/1.0.3.1/vod-js-sdk.js"></script>

<!-- 最新版本 -->
<script src="https://bce.bdstatic.com/lib/@baiducloud/media-sdk/@latest/vod-js-sdk.js"></script>

简单文件上传

SDK在上传时与使用方的交互有两步，具体如下：

步骤1：申请上传

SDK会上传前会通过getUploadUrl回调函数获取上传链接及临时sessionKey，函数定义如下：

                Javascript
                
                function getUploadUrl(params) {
    return axios.post(url, params).then(res => res.data);
}

步骤2：确认上传

当文件上传完成后，需要通过uploadComplete回调函数告知VOD服务文件已经上传完成，函数定义如下：

                Javascript
                
                function uploadComplete(params) {
    return axios.post(url, params).then(res => res.data);
}

说明：

1、参数params为调用VOD后端服务时所需要的数据，直接传给接口即可，具体格式见下方。

2、url为请求VOD服务时的接口地址，具体请参考API文档。

3、需要return接口返回的数据。

上传文件示例

                Javascript
                
            

                // 通过cdn引入后，会在window下挂在VodSDK变量
const uploader = window.VodSDK.VodUpload({
    getUploadUrl: getUploadUrl, // 上文所述申请上传函数
    uploadComplete: uploadComplete // 上文所述确认上传函数
});

uploader.upload({
    file: mediaFile // 待上传的媒体文件，类型为File
});

uploader.on('process', function(info) {
    console.log('上传进度', info.percent);
});

uploader.done().then(function(infos) {
    console.log('全部上传完成', infos);
}).catch(function(info) {
    console.log('文件名：', info.name, '，上传失败：', info.errMsg);
});
            

说明：

1、new VodUplaod(otps)中的参数具体可参考下方接口描述。

2、done方法为上传的所有文件都成功后才会执行.then回调，返回的是文件信息的数组。

高级功能

上传多个文件

当需要上传多个文件时，可循环调用upload方法

                Javascript
                
            

                // 通过cdn引入后，会在window下挂在VodSDK变量
const uploader = window.VodSDK.VodUpload({
    fileParallelLimit: 5, // 并行上传5个文件
    getUploadUrl: getUploadUrl, // 上文所述申请上传函数
    uploadComplete: uploadComplete // 上文所述确认上传函数
});

mediaFiles.forEach(function (mediaFile) {
    uploader.upload({
        file: mediaFile // 待上传的媒体文件，类型为File
    });
});

uploader.on('process', function(info, infos) {
    console.log('文件名：', info.name, '，上传进度：', info.percent);
});

uploader.done().then(function(infos) {
    console.log('全部上传完成', infos);
});
            

说明：

1、在初始化VodUpload时，可以通过 fileParallelLimit 配置项控制并行上传的文件数量，默认并行上传3个文件。

2、mediaFiles 是待上传的文件数组，类型为 Array<File>。

3、on事件回调函数有两个参数，第一个参数为执行此回调事件的文件信息，第二个参数为所有上传文件的信息。

暂停上传

SDK支持通过stop()方法，暂停正在上传的文件

                Javascript
                
                uploader.upload({
    file: mediaFile // 待上传的媒体文件，类型为File
});

uploader.stop()

说明：

1、stop函数支持传入文件id数组来制定暂停某个文件，如果为空时会暂停所有上传的文件，下方cancel、resume方法有同样的逻辑

取消上传

SDK支持通过cancel()方法，取消正在上传的文件

                Javascript
                
                uploader.upload({
    file: mediaFile // 待上传的媒体文件，类型为File
});

uploader.cancel()

恢复上传

已经暂停的文件，可以通过resume()方法恢复上传

                Javascript
                
                uploader.upload({
    file: mediaFile // 待上传的媒体文件，类型为File
});

uploader.stop(); // 暂停上传

setTimeout(function() {
    uploader.resume(); // 恢复上传
}, 2000);

说明：

1、stop函数支持传入文件id数组来制定暂停某个文件，如果为空时会暂停所有上传的文件。

断点续传

断点续传功能的前提是需要分片上传，SDK 默认开启了分片上传和断点续传功能，无需额外操作。但断点续传功能仅限于未关闭页面时，如果关闭浏览器页面则信息将会被清除。

应用场景：上传文件暂停后，如果恢复上传可以从可以从中断处继续上传，减少重复上传时间。

接口描述

VodUpload 初始化参数

VodUpload构造函数支持传入配置项，具体配置如下

参数	必填	类型	默认值	说明
getUploadUrl	是	function(params: GetUploadUrlParams): Promise<{sessionKey: string; urls: string[]}>	-	申请上传回调，获取上传链接
uploadComplete	是	function(params: UploadCompleteParams): Promise<{mediaId: string}>	-	确认上传回调
autoExtractCover	否	boolean	`false`	是否自动提取封面
isMultipartUpload	否	boolean	`true`	是否分片上传
enableResume	否	boolean	`true`	是否支持断点续传
fileParallelLimit	否	number	`3`	同一个实例下，上传的文件并发数
chunkSize	否	number	`16 * 1024 ** 2`	分片上传时，每个分片的大小
chunkParallelLimit	否	number	`6`	同一个上传文件进行分片上传时的并发数
chunkRetryTimes	否	number	`2`	分片上传时，出错重试次数

GetUploadUrlParams

参数	类型	说明
name	string	文件名称
container	string	音视频封装格式
isMultipartUpload	boolean	是否需要分片上传
numParts	number	分片数

UploadCompleteParams

参数	类型	说明
sessionKey	string	临时上传 key
isMultipartUpload	boolean	是否需要分片上传
etags	string[]	分片文件的版本标识
autoExtractCover	boolean	自动提取封面图

VodUpload API

方法名	类型	说明
infos	UploaderInfo[]	上传文件的信息
upload	function(params: UploadParams): UploaderInfo	上传文件
stop	function(ids?: string[]): void	停止上传
resume	function(ids?: string[]): void	恢复上传
retry	function(ids?: string[]): void	重试上传
cancel	function(ids?: string[]): void	取消上传
remove	function(ids?: string[]): void	清除上传记录
done	function(): Promise<UploaderInfo[]>	上传完成
on	function(event: string, callback: (info: UploaderInfo) => void): void	绑定事件，可以监听某个事件
off	function(event: string, callback: (info: UploaderInfo) => void): void	解除绑定事件
onEvent	function(callback: function(event: string, info: UploaderInfo, infos: UploaderInfo[]): void): void	统一绑定所有事件，所有事件变化均会调用该事件
offEvent	function(callback: function(event: string, info: UploaderInfo, infos: UploaderInfo[]): void): void	解除统一绑定事件

UploadParams

参数	必填	类型	默认值	说明
file	是	File	-	上传的文件
name	否	string	`file.name`	文件名称，默认使用 file.name
autoExtractCover	否	boolean	`false`	是否自动提取封面
isMultipartUpload	否	boolean	`true`	是否分片上传
enableResume	否	boolean	`true`	是否支持断点续传
chunkSize	否	number	`16 * 1024 ** 2`	分片上传时，每个分片的大小
chunkParallelLimit	否	number	`6`	同一个上传文件进行分片上传时的并发数
chunkRetryTimes	否	number	`2`	分片上传时，出错重试次数

UploaderInfo

参数	类型	说明
id	string	文件上传 id
name	string	文件名
size	string	文件大小
fileType	string	文件类型
suffixName	string	文件后缀名
status	string	上传状态
percent	number	文件上传进度百分比，范围：`[0, 100]`
errMsg	string	上传失败的错误信息
mediaId	string	服务端保存的媒资 Id，当上传完成后才有值

上传事件

事件	描述
ready	已就绪
process	上传中
success	上传成功
error	上传失败
stop	暂停上传
cancel	取消上传

可以通过on(),方法进行事件监听，如：

                Javascript
                
            

                // 通过cdn引入后，会在window下挂在VodSDK变量
const uploader = window.VodSDK.VodUpload({
    getUploadUrl: getUploadUrl, // 上文所述申请上传函数
    uploadComplete: uploadComplete // 上文所述确认上传函数
});

uploader.upload({
    file: mediaFile // 待上传的媒体文件，类型为File
});

uploader.on('process', function(info) {
    console.log('上传进度', info.percent);
});

uploader.on('csuccess', function(info) {
    console.log('上传成功', info.status);
});
            

常见问题

如何获取 File 对象？

使用input标签，type为file类型，即可拿到File对象。

上传的文件是否有大小限制?

最大支持5GB。

SDK 支持的浏览器版本有哪些？

Chrome、Firefox 等支持 HTML5 的主流浏览器，IE 方面支持的最低版本是 IE10。

版本信息

版本	改动
1.0.3.1	初始版本，支持文件分片上传、取消上传等操作

服务端上传

HarmonyOS NEXT 上传 SDK

智能点播平台 VOD