更新记录

0.0.1（2026-06-04）

• 首个版本发布。
• 新增 iOS 原生竖屏视频录制能力，用于解决部分场景下 iOS 竖屏视频录制、预览或上传后方向变横屏的问题。
• 支持录制时长限制，默认最短 10 秒、最长 180 秒。
• 支持录制达到最长时长后自动停止。
• 支持录制完成后的预览流程，用户可选择“重拍”或“完成”。
• 支持录制时间实时显示。
• 支持前置、后置摄像头切换。
• 支持自定义录制界面的按钮文案和错误提示。
• 支持录制质量配置、静音录制、后置摄像头补光灯。
• 支持返回视频本地路径、视频时长、文件大小和封面图路径。

平台兼容性

uni-app(3.7.8)

iOS 竖屏视频录制插件

snowfee-ios-portrait-video-recorder 是一个基于 UTS + iOS 原生 AVFoundation 实现的视频录制插件，主要用于 uni-app / uni-app x 在 iOS 真机中录制竖屏视频。

这个插件最初是为了解决 iOS 使用系统相机或部分压缩流程后，竖屏视频预览、上传或播放时可能变成横屏的问题。插件通过原生录制流程固定竖屏方向，并返回本地临时视频路径，适合校园动态、课堂记录、表单上传、短视频采集等场景。

功能特性

• 使用 iOS 原生 AVFoundation 录制视频
• 固定竖屏录制，减少竖屏视频变横屏的问题
• 支持 10-180 秒录制时长控制，默认最短 10 秒、最长 180 秒
• 达到最长时长后自动停止录制
• 支持录制后预览，并提供“重拍”和“完成”操作
• 录制时间实时显示
• 录制时长不足最短限制时，点击完成会展示错误提示
• 支持前置、后置摄像头切换
• 支持自定义原生按钮文案
• 支持录制质量配置
• 支持静音录制
• 支持后置摄像头补光灯，使用 iOS torch 常亮模式
• 返回视频本地路径、时长、大小和封面图路径

平台支持

权限说明

插件需要以下 iOS 权限：

• NSCameraUsageDescription
• NSMicrophoneUsageDescription

如果设置 enableAudio: false，插件不会主动请求麦克风权限，但项目中仍建议保留麦克风权限描述，避免后续切换为有声录制时遗漏配置。

插件不采集用户数据，不上传文件，不访问网络。录制完成后只返回本机临时文件路径，由业务方自行决定后续上传、压缩或保存逻辑。

安装和打包

1. 将插件导入 uni-app 项目的 uni_modules 目录。
2. 在 HBuilderX 中重新制作 iOS 自定义基座，或直接进行 iOS 云打包。
3. 使用真机调试。相机能力无法在普通浏览器、H5 或 iOS 模拟器中完整验证。

基本用法

import { recordPortraitVideo } from '@/uni_modules/snowfee-ios-portrait-video-recorder'

recordPortraitVideo({
  success: (res) => {
    console.log('视频路径:', res.tempFilePath)
    console.log('封面路径:', res.posterPath)
    console.log('视频时长:', res.duration)
    console.log('文件大小:', res.size)
  },
  fail: (err) => {
    console.log(err.errCode, err.errMsg)
  }
})

完整示例

recordPortraitVideo({
  minDuration: 10,
  maxDuration: 180,
  cameraPosition: 'back',
  preset: 'high',
  enableAudio: true,
  flashMode: 'off',
  torchEnabled: false,
  posterTime: 0,
  texts: {
    record: 'Record',
    stop: 'Stop',
    retake: 'Retake',
    complete: 'Complete',
    cancel: 'Cancel',
    minDurationError: 'Video must be at least {seconds} seconds',
    switchCamera: 'Flip',
    flashOn: 'Flash On',
    flashOff: 'Flash Off'
  },
  success: (res) => {
    console.log(res.path)
    console.log(res.tempFilePath)
    console.log(res.posterPath)
    console.log(res.duration)
    console.log(res.size)
  },
  fail: (err) => {
    console.log(err.errCode, err.errMsg)
  },
  complete: (res) => {
    console.log('record complete', res)
  }
})

参数说明

texts 文案说明

success 返回值

{
  path: string
  tempFilePath: string
  duration: number
  size: number
  type: string
  posterPath?: string
}

fail 返回值

{
  errCode: number
  errMsg: string
}

常见错误码：

关于补光灯

iOS 视频录制不使用拍照时的瞬间闪光灯，而是使用后置摄像头的 torch 常亮模式。也就是说：

• flashMode: 'on' 会尝试打开后置摄像头补光灯
• torchEnabled: true 也会尝试打开后置摄像头补光灯
• 前置摄像头通常没有 torch，因此切换到前置摄像头时补光灯不会生效
• 部分设备或系统状态下可能禁用 torch，例如设备过热、电量过低、相机被其他模块占用等

注意事项

• 插件只支持 iOS App 端，需要使用自定义基座或云打包后在真机验证。
• 如果业务还需要压缩视频，建议录制完成后再调用单独的视频压缩插件或业务压缩流程。
• maxDuration 使用原生录制时长限制，到达最长时长后会自动停止录制。
• minDuration 在录制后的完成按钮处校验，时长不足时用户可以选择重拍。
• 返回的视频是本地临时文件，业务方上传完成后可按需清理。
• 插件内部不上传、不压缩、不持久化保存视频文件。