使用JavaScript SDK上传文件

浏览器要求

Demo下载地址

• 下载地址：Demo源码

快速集成

安装

npm install aliyun-vod-upload-sdk

SDK提供ESM、CJS、UMD三种构建产物，支持所有现代打包工具（Vite/webpack/Rollup/esbuild）。

CDN 引入

<script src="https://g.alicdn.com/apsara-media-box/imp-web-vod-upload/2.1.0/vod-upload.umd.js"></script>
<script>
  const { createUploader, UploadError } = window.AliyunVodUpload;
</script>

5 行代码上传

import { createUploader } from 'aliyun-vod-upload-sdk';

const uploader = createUploader({
  getAuth: () => fetch('/api/vod/auth').then(r => r.json()),
});

const { videoId } = await uploader.upload(file);

后端接口要求

在getAuth模式下，SDK不直接调用阿里云OpenAPI，而是通过getAuth回调委托你的后端获取上传凭证。后端需实现以下接口（对应VOD OpenAPI）：

后端返回的JSON原样透传给SDK即可，SDK 内部自动完成base64解码和字段映射。

如果服务端仅提供STS临时凭证，可以使用STS直传模式getSTS：SDK 会在浏览器中直接签名调用上述VOD OpenAPI，无需实现这些接口。

基础功能

视频上传

import { createUploader } from 'aliyun-vod-upload-sdk';

const uploader = createUploader({
  getAuth: async (ctx) => {
    switch (ctx.kind) {
      case 'create-video':
        return fetch('/api/vod/create-auth', {
          method: 'POST',
          body: JSON.stringify({ fileName: ctx.file.name, ...ctx.meta }),
        }).then(r => r.json());
      case 'refresh-video':
        return fetch(`/api/vod/refresh-auth?videoId=${ctx.videoId}`)
          .then(r => r.json());
    }
  },
});

const result = await uploader.upload(file, {
  meta: { title: '我的视频', cateId: 1000, tags: '教程,示例' },
});
console.log('上传成功，videoId:', result.videoId);

getAuth回调接收一个ctx参数，SDK会根据场景自动决定ctx.kind：

• create-video— 首次上传，需后端调用CreateUploadVideo。

• refresh-video—续传或凭证过期时刷新，需后端调用RefreshUploadVideo。

• create-image—上传图片，需后端调用CreateUploadImage。

• create-attached-media—上传辅助媒资，需后端调用CreateUploadAttachedMedia。

图片上传

图片上传使用同一个 upload() 方法，SDK 根据 file.type 自动识别（image/* 类型走图片链路）：

const uploader = createUploader({
  getAuth: async (ctx) => {
    if (ctx.kind === 'create-image') {
      return fetch('/api/vod/image-auth', {
        method: 'POST',
        body: JSON.stringify({ imageType: 'default' }),
      }).then(r => r.json());
    }
  },
});

const result = await uploader.upload(imageFile);
console.log('图片上传成功，imageId:', result.imageId);

辅助媒资上传（水印 / 字幕 / 素材）

水印图、字幕文件（srt / ass / vtt）、素材（zip / 图片 / 视频片段）需调用CreateUploadAttachedMedia - 获取辅助媒资上传地址和凭证：在 meta里带上 businessType 即路由到该链路，其余用法与视频 / 图片完全一致（进度 / 取消 / 超时重试 / 埋点）。

// 字幕：.srt 不带 businessType 会被视频链路接走，生成一条类型错误的视频记录
const r1 = await uploader.upload(srtFile, { meta: { businessType: 'subtitle' } });

// 素材
const r2 = await uploader.upload(materialFile, { meta: { businessType: 'material' } });

// 水印图：走辅助媒资（产物与「图片链路 + imageType: 'watermark'」是两类不同资源）
const r3 = await uploader.upload(logoFile, {
  meta: { businessType: 'watermark', mediaExt: 'png' },
});

console.log('mediaId:', r1.mediaId);   // 三路统一字段：视频 = VideoId、图片 = ImageId、辅助媒资 = MediaId

businessType / mediaExt 等字段说明：

两点行为差异：

• 不参与断点续传：视频点播没有该接口的Refresh 版本（凭证约 3000 秒有效，过期只能重新 Create 并拿到新 MediaId），所以 SDK 不为辅助媒资读写 checkpoint，中断后重传是全新一次上传。

• png 水印有两条官方路径：图片链路（VodImageMeta.imageType = 'watermark'）与辅助媒资链路（businessType: 'watermark'）产物是两类不同资源，SDK不会自动决定；传 businessType 才走辅助媒资，不传就按文件类型走图片链路。

uploadAuth 模式下getAuth会收到ctx.kind === 'create-attached-media'，把ctx.meta.businessType转给后端即可；STS模式（getSTS）下SDK自动完成签名调用，getSTS无需任何改动。

上传进度

const result = await uploader.upload(file, {
  onProgress: (percent, loaded, total) => {
    // percent: 0..1 (如 0.5 表示 50%)
    // loaded:  已上传字节数
    // total:   文件总字节数
    progressBar.value = percent;
    console.log(`${(percent * 100).toFixed(1)}% - ${loaded} / ${total}`);
  },
});

SDK 保证上传完成时 percent 最终一定等于 1。

取消上传

• 方式一：task.abort() — 最简单

  const task = uploader.upload(file);
  
  cancelBtn.onclick = () => task.abort();
  
  try {
    const result = await task;
  } catch (e) {
    if (e.name === 'AbortError') {
      console.log('用户取消了上传');
    }
  }

• 方式二：AbortSignal — 适合 React/Vue 组件生命周期

  const ctrl = new AbortController();
  cancelBtn.onclick = () => ctrl.abort();
  
  try {
    const result = await uploader.upload(file, { signal: ctrl.signal });
  } catch (e) {
    if (e.name === 'AbortError') {
      console.log('已取消');
    }
  }

取消后 checkpoint 会保留，下次再upload(file)会自动从断点续传（仅视频；图片与辅助媒资不走断点续传，再次上传是全新一次上传）。

断点续传

断点续传是默认开启的，无需任何额外配置（仅视频上传支持，图片与辅助媒资上传不走断点续传）。SDK 自动：

1. 将已完成的分片进度存入 localStorage。

2. 页面刷新后再次 upload(file)，自动从上次中断处继续。

3. 匹配规则：相同 file.name + file.size + file.lastModified → 命中 checkpoint。

// 第一次上传（上传到 40% 时用户关闭页面）
await uploader.upload(file);

// 用户重新打开页面后再次上传同一个文件
// SDK 自动从 40% 继续，不会重复上传
const result = await uploader.upload(file);

关闭断点续传：

const uploader = createUploader({
  getAuth: myGetAuth,
  checkpoint: false,  // 关闭
});

高级功能

批量上传

SDK 提供单文件 upload() API，批量上传使用标准 JavaScript 异步原语组合：

// 串行上传（最简单）
for (const file of files) {
  const result = await uploader.upload(file, {
    onProgress: p => updateProgress(file.name, p),
  });
  console.log(`${file.name} 完成，videoId: ${result.videoId}`);
}

// 并发上传（大带宽 + 小文件）
const results = await Promise.all(
  files.map(f => uploader.upload(f)),
);

// 限并发（推荐，大文件场景）
import pLimit from 'p-limit';

const limit = pLimit(2); // 最多同时上传 2 个文件
const results = await Promise.all(
  files.map(f => limit(() => uploader.upload(f, {
    onProgress: p => updateItemProgress(f, p),
  }))),
);

暂停与恢复

SDK没有显式的暂停API。暂停效果通过取消 + 续传实现：

// 暂停：取消当前上传
task.abort();

// 恢复：重新上传同一文件，自动从 checkpoint 续传
const result = await uploader.upload(file);

超时取消与多源取消

// 60 秒超时自动取消
await uploader.upload(file, {
  signal: AbortSignal.timeout(60_000),
});

// 多源取消：用户手动取消 或 60 秒超时
const userCtrl = new AbortController();
await uploader.upload(file, {
  signal: AbortSignal.any([
    userCtrl.signal,
    AbortSignal.timeout(60_000),
  ]),
});

React / Vue 集成

import { useEffect, useRef, useState } from 'react';
import { createUploader } from 'aliyun-vod-upload-sdk';

function useUploader(getAuth) {
  const uploaderRef = useRef(null);

  // 在 effect 里创建：避免每次渲染都 createUploader；
  // StrictMode 下 effect 会「执行 → 清理 → 再执行」，清理时 dispose 的实例会被重新创建
  useEffect(() => {
    const uploader = createUploader({ getAuth });
    uploaderRef.current = uploader;
    return () => {
      uploader.dispose(); // 组件卸载时释放，同时取消进行中的上传
      uploaderRef.current = null;
    };
  }, []);

  return uploaderRef;
}

function UploadButton({ file }) {
  const uploaderRef = useUploader(myGetAuth);
  const ctrlRef = useRef(null);
  const [progress, setProgress] = useState(0);

  const handleUpload = () => {
    const uploader = uploaderRef.current;
    if (!uploader) return;
    const ctrl = new AbortController();
    ctrlRef.current = ctrl;

    uploader.upload(file, {
      signal: ctrl.signal,
      onProgress: p => setProgress(p),
    }).then(result => {
      console.log('成功', result.videoId);
    }).catch(e => {
      if (e.name !== 'AbortError') {
        console.error('失败', e);
      }
    });
  };

  return (
    <>
      <button onClick={handleUpload}>上传 ({(progress * 100).toFixed(0)}%)</button>
      <button onClick={() => ctrlRef.current?.abort()}>取消</button>
    </>
  );
}

import { onUnmounted, ref } from 'vue';
import { createUploader } from 'aliyun-vod-upload-sdk';

export function useUploader(getAuth) {
  const uploader = createUploader({ getAuth });
  const progress = ref(0);

  onUnmounted(() => uploader.dispose());

  async function upload(file) {
    return uploader.upload(file, {
      onProgress: p => { progress.value = p; },
    });
  }

  return { upload, progress };
}

API文档

createUploader(config)

创建 Uploader 实例。

import { createUploader } from 'aliyun-vod-upload-sdk';

const uploader = createUploader(config);

UploaderConfig

RetryPolicy

uploader.upload(file, options?)

上传单个文件。返回UploadTask：既是Promise<UploadResult>，也带.abort()方法。

const task = uploader.upload(file, options);

UploadOptions

VodVideoMeta（视频元数据）

VodImageMeta（图片元数据）

VodAttachedMediaMeta（辅助媒资元数据）

UploadResult（上传结果）

UploadTask

upload() 返回的对象同时是 Promise<UploadResult> 和带 .abort() 方法的对象。

type UploadTask = Promise<UploadResult> & {
  abort(): void;
};

uploader.dispose()

释放资源：取消所有进行中的上传并清除内部状态。

uploader.dispose();

调用后该 uploader 实例不可再使用。在 React/Vue 组件卸载时务必调用，避免内存泄漏。

凭证回调 getAuth

type GetAuth = (ctx: AuthContext) => Promise<AuthResult>;

AuthContext

SDK 根据上传场景传入不同的 ctx：

AuthResult

后端返回的 OpenAPI 原始 JSON，SDK 内部自动解码：

getAuth 最简实现：

// 后端统一路由。注意 ctx.file 是 File / Blob，JSON.stringify 会把它变成 {}，
// 需要把后端用到的文件信息（如 fileName）单独取出来
createUploader({
  getAuth: ({ file, ...rest }) => fetch('/api/vod/auth', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ ...rest, fileName: file.name, fileSize: file.size }),
  }).then(r => r.json()),
});

refresh-video 失败自动降级：当续传凭证刷新失败时，SDK 自动 fallback 到 create-video 重新上传，对调用方完全透明。

STS直传模式getSTS

getAuth模式需要由服务端调用VOD OpenAPI获取UploadAuth/UploadAddress。如果你的服务端仅提供STS 临时凭证，可以使用getSTS模式：SDK会在浏览器中使用该凭证签名调用VOD OpenAPI，获取上传凭证后再上传文件。

type GetSTS = () => Promise<STSCredential>;

interface STSCredential {
  accessKeyId: string;
  accessKeySecret: string;
  securityToken: string;
}

createUploader({
  region: 'cn-shanghai',              // getSTS 模式必填，决定 vod.<region>.aliyuncs.com 端点
  getSTS: async () => {
    const { AccessKeyId, AccessKeySecret, SecurityToken } = await fetch('/api/sts').then(r => r.json());
    return { accessKeyId: AccessKeyId, accessKeySecret: AccessKeySecret, securityToken: SecurityToken };
  },
});

要点：

• 必须运行在HTTPS或localhost：STS模式的V3签名依赖Web Crypto crypto.subtle，普通HTTP页面不可用；getAuth模式不受此限制。

• 与getAuth互斥：两者只能传一个。

• 无参数、不含expiration：SDK 不主动判断STS凭证是否过期；VOD返回InvalidSecurityToken.Expired时自动重新调一次getSTS()并重试一次。

• 不做缓存、不做并发去重：多个并发upload()会各自调getSTS()，需要缓存请自己实现。

• Title/FileName由SDK从文件派生：FileName=file.name（Blob时用meta.fileName），Title=meta.title ?? FileName；派生值截断到 128 字符，显式传的meta.title不截断。

• FileSize由SDK填：每次CreateUploadVideo无条件带上FileSize=file.size（v1要用户自己在userData里传，漏传VOD侧就缺大小）。

• VOD调用失败时错误码为UPLOAD.VOD.CREATE_FAILED/UPLOAD.VOD.REFRESH_FAILED，suggestion里带VOD的排障链接；VOD原始Message不会进UploadError（可能含明文凭证），只会脱敏后上报到埋点。

• 超时与重试复用timeout/retry.count配置；4xx/5xx都不重试（只有上面那一处过期码例外）。

错误处理

UploadError 结构

所有上传错误都是UploadError实例（继承自Error）：

import { UploadError } from 'aliyun-vod-upload-sdk';

class UploadError extends Error {
  readonly code: string;           // 结构化错误码，如 'UPLOAD.OSS.ACCESS_DENIED'
  readonly message: string;        // 错误描述
  readonly suggestion: string;     // 中文修复建议
  readonly cause?: unknown;        // 底层原始错误
  readonly uploadTaskId?: string;  // 上传任务 ID（可用于售后排障）
}

用户取消上传不是 UploadError，而是标准的 DOMException（name === 'AbortError'）。

错误码清单

错误码格式：UPLOAD.{层级}.{类型}

使用错误码常量

推荐使用 ErrorCode 常量而非字符串字面量：

import { ErrorCode, UploadError } from 'aliyun-vod-upload-sdk';

try {
  await uploader.upload(file);
} catch (e) {
  if (e instanceof UploadError) {
    switch (e.code) {
      case ErrorCode.AUTH_GET_AUTH_FAILED:
        showToast('凭证获取失败，请刷新页面重试');
        break;
      case ErrorCode.NETWORK_TIMEOUT:
      case ErrorCode.NETWORK_ERROR:
        showToast('网络异常，请检查网络后重试');
        break;
      case ErrorCode.OSS_ACCESS_DENIED:
        showToast('上传权限不足，请联系管理员');
        break;
      default:
        showToast(`上传失败：${e.suggestion || e.message}`);
    }
  }
}

排障指引

每个 UploadError 都携带 uploadTaskId，这是整次上传的全局串联 ID。提交给阿里云售后时可快速定位问题：

catch (e) {
  if (e instanceof UploadError) {
    // 发给你的技术支持团队
    const diagnostic = {
      code: e.code,
      message: e.message,
      uploadTaskId: e.uploadTaskId,
      suggestion: e.suggestion,
    };
    reportToSupport(diagnostic);
  }
}

UploadResult.uploadTaskId 同样可用于成功上传后的日志关联：

const result = await uploader.upload(file);
myLogger.info('上传成功', { videoId: result.videoId, uploadTaskId: result.uploadTaskId });