更新记录

1.0.1（2026-09-11） 下载此版本

v1.0.0

• 不依赖 FFmpeg，原生 API 生成缩略图
• 支持本地路径和 http(s) 在线视频
• 自定义时间、尺寸、格式、质量

平台兼容性

uni-app(4.83)

m-video-frame

支持本地视频（相册/录制/文件）和在线视频地址（http/https）抽取指定时间帧，可自定义尺寸、格式和质量。

原生实现

• Android：MediaMetadataRetriever，关键帧优先 + 精确降级，取帧后等比缩放
• iOS：AVAssetImageGenerator，自动纠正旋转、容差取帧、解码期约束尺寸

支持的视频地址

iOS 的 content:// 不是系统 URL 形式，不支持。

_doc/、_downloads/、uni-file:// 是 plus.io 虚拟协议，原生层按相对路径找不到文件会抽帧失败。App 端 uni.chooseVideo / uni.chooseMedia 返回的就是这种路径，调用前先转换：

// _doc/... -> 原生绝对路径
const url = plus.io.convertLocalFileSystemURL('_doc/uniapp_temp_xxx/camera/video_001.mp4')
// Android -> /storage/emulated/0/Android/data/<包名>/apps/<appId>/doc/uniapp_temp_xxx/...
// iOS     -> /var/mobile/Containers/Data/Application/<UUID>/Documents/uniapp_temp_xxx/...

基本使用方式

import { extractVideoFrame } from '@/uni_modules/m-video-frame'

// 本地视频
const res1 = await extractVideoFrame({ url: '/var/mobile/.../video_001.mp4' })

// 在线视频
const res2 = await extractVideoFrame({ url: 'https://example.com/demo.mp4' })

// 完整参数
const res3 = await extractVideoFrame({
  url: 'https://example.com/demo.mp4',
  timeSec: 1,
  format: 'jpg',
  quality: 90,
  maxWidth: 720,
  maxHeight: 720,
  fileName: 'video_thumb_001'
})

console.log(res.path) // file:// 绝对路径，可直接用于 <image> 展示

参数

返回值

type ExtractVideoFrameResult = {
  path: string      // 带 file:// 前缀的本地路径，两端统一，可直接用于 image 展示
  width: number     // 输出图片宽度（像素）
  height: number    // 输出图片高度（像素）
  format: string    // 实际输出格式 jpg / png
  timeMs: number    // 实际抽帧时间点（毫秒）
  size: number      // 文件大小（字节）
}

注意事项

1. 网络视频抽帧依赖系统框架，目标服务器必须支持系统播放器/解码器访问。
2. Android 读取相册本地媒体时，调用方需要自行确保有媒体读取权限。
3. 抽帧时间超出视频时长时插件会自动钳制到时长内（留 50ms 余量），返回的 timeMs 为实际取帧时间点
4. 插件对原生层的取帧错误只返回通用错误码 9030001，不透出原生具体原因；排查问题建议先在调用侧打印路径转换前后日志