1. 从“选择”到“上传”：一个看似简单却暗藏玄机的需求

在移动端和跨平台应用开发里，“让用户从手机里选张照片、挑个视频或者找个文件”这个需求，几乎和“登录注册”一样基础。无论是发布动态、上传头像，还是提交作业、发送附件，都离不开这个功能。在UniApp这个“一套代码，多端运行”的框架里，实现这个功能，你可能会觉得不就是调用一个uni.chooseImage或者uni.chooseFile的API吗？这有什么好讲的？

如果你真这么想，那可能已经踩在坑边上了。我见过太多项目，在这个“基础”功能上栽了跟头：在安卓机上选图流畅无比，到了iOS上却提示“没有权限”；选好了10MB的视频，上传时才发现只拿到了一个几KB的临时路径，根本传不上去；在微信小程序里运行良好，打包成App后文件选择器却一片空白。这些问题的根源，就在于开发者只看到了API调用的“形”，没理解多端差异和文件系统管理的“神”。

UniApp的本地资源选取，远不止一个API调用那么简单。它涉及到H5的<input type=“file”>、小程序的wx.chooseMedia、App端的原生模块（plus.gallery、plus.io）等多套底层实现的桥接与兼容。更关键的是，你“选”到的那个东西，到底是什么？是一个可以直接使用的本地文件路径？一个需要进一步处理的临时文件？还是一个仅仅存在于内存中的二进制数据？不同的平台、不同的API、甚至不同的调用参数，给出的答案天差地别。

这篇文章，我就以一个趟过无数坑的过来人身份，带你彻底拆解UniApp中选取图片、视频、文件的完整流程。我们不止看“怎么选”，更要深究“选到了什么”、“怎么用”，以及如何优雅地处理那些令人头疼的兼容性和性能问题。目标是让你写出的代码，无论在哪个平台，都能稳定、高效、符合用户预期地工作。

2. 核心API全景图：不止是chooseImage

当你准备实现文件选择时，第一反应可能是去翻UniApp的API文档，然后你会发现好几个长得像的API：uni.chooseImage,uni.chooseVideo,uni.chooseFile，还有uni.chooseMedia。它们之间是什么关系？该怎么选？这第一步如果走错，后面就会步步维艰。

2.1 各API的定位与适用场景

首先，我们必须摒弃“一个API通吃”的想法。UniApp提供了不同颗粒度的API来适应不同场景：

uni.chooseImage：专注图片选择这是最常用的API，专门用于从相册或相机获取图片。它的参数设计非常图片化，比如count（选择数量）、sizeType（是否压缩原图）、sourceType（相册或相机）。它的返回值tempFilePaths是一个临时文件路径数组，在大部分平台（特别是小程序和H5）下，这个路径是应用私有临时区的地址，应用重启后可能失效，不能当作永久存储路径使用。

uni.chooseVideo：专注视频选择与chooseImage类似，专为视频设计。除了选择，它还可以调起相机直接拍摄。它的核心参数是maxDuration（最大录制时长），返回值中除了临时文件路径tempFilePath，还包含视频的时长、大小、高度、宽度等元信息。这里有一个巨大的坑：在小程序平台，通过这个API选择的视频，其临时路径的有效期非常短，且通常有大小限制（如25MB），如果你需要上传大视频，这个API可能不是最佳选择。

uni.chooseFile：通用的文件选择这是一个更底层的、通用的文件选择器。它不关心文件是图片还是视频，只要是设备上能访问的文件，都可以选择。它的参数非常灵活，可以指定extension（文件扩展名过滤，如[‘.pdf‘， ‘.docx’]）和type（如‘all‘， ‘image’， ‘video’）。这个API在H5和App端表现强大，可以访问设备存储目录。但是，在微信小程序平台，这个API的能力被严重阉割，只能选择聊天文件或手机存储中的少数几种类型，且用户体验与原生选择器相差甚远。

uni.chooseMedia：微信小程序生态的“新贵”这个API是随着微信小程序基础库更新而加入的，旨在统一图片和视频的选择（特别是支持了同时选择图片和视频）。它返回的数据结构更丰富，包含了文件的临时路径、文件类型、尺寸、时长等。关键在于，对于微信小程序，uni.chooseMedia是官方推荐的最新选择方式，它在性能、用户体验和未来兼容性上都优于旧的chooseImage和chooseVideo。但在非微信平台（如H5、其他小程序、App），这个API可能不存在或行为不一致。

看到这里，你应该明白了：没有“最好”的API，只有“最适合”当前平台和场景的API。我的经验是，在项目初期就要明确你的核心平台和文件类型需求，然后制定一个兼容策略。

2.2 制定跨平台兼容策略：条件编译与降级方案

面对这么多API，我们不可能为每个平台写一套代码。UniApp的条件编译#ifdef和#endif就是解决这个问题的利器。一个稳健的兼容策略通常如下：

1. 优先使用平台最优解：在微信小程序中，优先尝试使用uni.chooseMedia，因为它功能最全，体验最好。
2. 提供降级方案：如果chooseMedia不可用（例如在低版本基础库），则降级到uni.chooseImage或uni.chooseVideo。
3. 区分App与H5：在App端，uni.chooseFile能力最强，可以配合plus.io进行更复杂的文件操作。在H5端，uni.chooseImage和uni.chooseFile都是基于原生<input>标签，但需要注意样式和多次选择的问题。
4. 统一返回数据结构：无论底层调用哪个API，最终都应处理成你业务逻辑期望的统一数据结构。例如，都返回一个包含filePath（临时路径）、size、type、name的对象数组。

下面是一个示例代码片段，展示了如何为“选择图片或视频”设计一个兼容函数：

// utils/fileChooser.js export const chooseMediaFiles = (options = {}) => { const { count = 9, mediaType = [‘image‘， ‘video’], sourceType = [‘album‘， ‘camera’] } = options; return new Promise((resolve, reject) => { // #ifdef MP-WEIXIN // 微信小程序平台，优先使用 chooseMedia if (uni.chooseMedia) { uni.chooseMedia({ count, mediaType: mediaType.includes(‘video‘) ? [‘image‘， ‘video’] : [‘image’], sourceType, success: (res) => { // 统一处理微信返回的数据结构 const files = res.tempFiles.map(item => ({ path: item.tempFilePath, size: item.size, type: item.fileType, width: item.width, height: item.height, duration: item.duration, thumbTempFilePath: item.thumbTempFilePath // 视频封面 })); resolve(files); }, fail: reject }); } else { // 低版本微信小程序降级处理 _chooseMediaFallback(options).then(resolve).catch(reject); } // #endif // #ifdef APP-PLUS // App端，使用功能更强的 chooseFile，或直接调用 plus.gallery.pick _chooseFileForApp(options).then(resolve).catch(reject); // #endif // #ifdef H5 // H5端，使用 chooseImage 和 chooseFile 的组合 _chooseMediaForH5(options).then(resolve).catch(reject); // #endif }); }; // 降级或平台特定实现函数 async function _chooseMediaFallback(options) { // 实现降级逻辑，可能需分别调用 chooseImage 和 chooseVideo } async function _chooseFileForApp(options) { // 实现App端选择逻辑，可能用到 plus.io } async function _chooseMediaForH5(options) { // 实现H5端选择逻辑，处理 input 标签 }

这个策略的核心思想是：利用条件编译隔离平台差异，在各自平台使用最优API，并通过适配层输出统一数据格式。这样，你的业务页面只需要调用chooseMediaFiles这个函数，完全不用关心底层是哪个API在工作。

3. 选完文件之后：临时路径的陷阱与永久化处理

当你成功调用API，拿到那个tempFilePaths数组时，万里长征其实才走了第一步。这个“临时路径”是接下来所有操作的基石，也是最容易出问题的地方。

3.1 理解“临时路径”的生命周期

不同平台对临时路径的定义和管理策略截然不同：

• 微信小程序：临时路径位于小程序沙盒内的临时目录。它的生命周期受限于本次小程序会话。当小程序被销毁（如长时间后台被系统清理）、或主动调用wx.cleanStorage时，这些文件会被清除。最关键的限制是：你不能直接把这个路径传递给诸如<image src=“...”>以外的其他API（特别是网络请求）进行上传。你需要使用wx.getFileSystemManager().readFile或wx.uploadFile来操作。
• App端：通过uni.chooseImage获取的路径，通常是应用沙箱内的临时目录。而通过plus.gallery.pick选择的，可能是相册的真实路径。临时文件在应用运行期间相对稳定，但应用重启后不一定存在。App端的好处是，你可以使用plus.io接口将文件复制到应用的持久化目录（如_doc、_www）下，获得一个真正的“永久”可访问路径。
• H5端：在浏览器中，你拿到的其实是一个File对象的本地引用（Blob URL），它仅存在于当前页面生命周期和内存中。页面刷新或关闭，这个引用就失效了。H5没有真正的“临时文件”概念，一切都是基于Blob对象在内存中处理。

所以，拿到临时路径后，第一个要问自己的问题是：我接下来要立刻使用它，还是需要存储起来后续再用？

3.2 场景一：即时预览与上传

如果用户选择文件后，你只是要立刻在页面上显示预览图，或者紧接着就上传到服务器，那么直接使用临时路径是最高效的。

预览示例：

<template> <view> <image v-for=“(item, index) in imageList” :key=“index” :src=“item” mode=“aspectFill”></image> </view> </template> <script> export default { data() { return { imageList: [] }; }, methods: { chooseImage() { uni.chooseImage({ success: (res) => { // 直接将临时路径赋值给image组件进行预览 this.imageList = res.tempFilePaths; } }); } } }; </script>

对于H5的File对象，预览需要先通过URL.createObjectURL()生成一个Blob URL用于<img>标签的src。

上传示例（以微信小程序上传图片到后端为例）：这里有一个关键点：你不能直接把tempFilePaths拼接到uni.request的data里。文件上传必须使用uni.uploadFileAPI。

// 假设 tempFilePaths 是 chooseImage 返回的数组 const uploadTask = uni.uploadFile({ url: ‘https://your-server.com/upload‘, filePath: tempFilePaths[0], // 直接使用临时路径 name: ‘file‘, formData: { ‘userId‘: ‘123’ }, success: (uploadRes) => { console.log(‘上传成功：‘， uploadRes.data); }, fail: (err) => { console.error(‘上传失败：‘， err); } }); // 如果需要监听上传进度 uploadTask.onProgressUpdate((res) => { console.log(‘上传进度：‘， res.progress); });

注意：在App端，如果文件较大，直接上传临时文件可能遇到权限问题。更稳妥的做法是先将文件用plus.io.resolveLocalFileSystemURL和plus.io.FileReader读取为二进制数据（Blob），或复制到应用文档目录后再上传。

3.3 场景二：持久化存储与后续使用

如果你的应用场景是：用户选择文件后，可能不会立刻上传（比如草稿箱），或者需要在应用下次启动时还能访问到这个文件（比如离线缓存的内容），那么你必须将文件从临时区域移动或复制到应用的持久化存储空间。

在App端，这是必须掌握的技能：

// 将临时文件复制到应用持久化目录 _doc（私有，用户不可见） function saveFilePermanently(tempFilePath) { return new Promise((resolve, reject) => { // 生成一个唯一的文件名 const fileName = `file_${Date.now()}_${Math.random().toString(36).substr(2)}.jpg`; const destPath = `_doc/${fileName}`; // _doc 是应用私有文档目录 plus.io.resolveLocalFileSystemURL(tempFilePath, (entry) => { entry.copyTo(plus.io.URLToLocalURL(`file://${destPath}`), (newEntry) => { // 复制成功，newEntry 是新文件的入口 // 现在你可以安全地使用 destPath 了，它在应用卸载前一直有效 resolve(destPath); }, (e) => { reject(new Error(`复制文件失败: ${JSON.stringify(e)}`)); }); }, (e) => { reject(new Error(`解析临时文件失败: ${JSON.stringify(e)}`)); }); }); } // 使用示例 uni.chooseImage({ success: async (res) => { const tempPath = res.tempFilePaths[0]; try { const permanentPath = await saveFilePermanently(tempPath); console.log(‘文件已保存至：‘， permanentPath); // 将 permanentPath 存储到本地数据库（如 uni.setStorage）或状态管理中 } catch (error) { uni.showToast({ title: ‘保存文件失败‘， icon: ‘none’ }); } } });

这个_doc目录是应用私有的，用户通过文件管理器无法直接访问，适合存储应用内部数据。如果你希望文件能被系统相册或其他应用访问，可能需要保存到公共目录，如DCIM/Camera/，但这需要动态申请额外的存储权限（android.permission.WRITE_EXTERNAL_STORAGE），并且从Android 10（API 29）开始，对外部公共目录的写入受到了严格限制，推荐使用MediaStoreAPI。

在H5端，持久化只能依靠浏览器的IndexedDB或直接将文件上传到服务器，没有本地文件系统的操作权限。

4. 性能、体验与边界情况实战指南

功能能跑通只是及格线，要让用户体验流畅、不崩溃，还需要处理大量细节。下面是我在实际项目中总结的几个关键实战要点。

4.1 大文件处理与内存管理

当用户选择高清图片或长视频时（动辄几十MB甚至上百MB），直接读取到内存中进行操作可能导致应用卡顿甚至闪退。

• 压缩与缩略图：对于图片，uni.chooseImage的sizeType参数可以指定是否选择压缩图。对于预览，永远使用压缩图或生成缩略图。UniApp的image组件和uni.compressImageAPI 可以帮助你。
• 分片读取与上传：对于超大文件（如视频），切忌一次性读取整个文件。在上传时，应使用支持分片上传的后端接口，并利用FileReader或plus.io.FileReader的readAsArrayBuffer方法分段读取文件内容。虽然UniApp的uni.uploadFile本身不支持分片，但你可以在App端通过plus.io接口自己实现，在H5端可以使用Blob.slice方法。
• 及时释放资源：在H5中，通过URL.createObjectURL()创建的Blob URL，在使用完毕后（如图片预览组件销毁时），一定要调用URL.revokeObjectURL()来释放内存。否则，这些内存会一直占用，直到页面关闭。

4.2 权限申请与用户引导

尤其是在App端，访问相册、相机、文件存储都需要权限。UniApp虽然做了封装，但开发者仍需主动处理。

• 动态申请：不要在应用一启动就申请所有权限，这会让用户反感。应该在用户触发相关操作（如点击“选择图片”按钮）时，再动态申请。使用uni.authorize或plus.android.requestPermissions。
• 优雅降级：如果用户拒绝了权限，不能只是弹出一个错误 toast。应该引导用户去系统设置页手动开启权限。可以封装一个统一的权限处理函数：

function requestPermission(scope, successCallback, failCallback) { uni.authorize({ scope: scope, success: successCallback, fail: (err) => { // 用户拒绝，引导去设置 uni.showModal({ title: ‘提示‘， content: ‘需要您授权访问相册/相机功能，是否去设置打开？’, success: (res) => { if (res.confirm) { uni.openSetting(); // 打开小程序设置页（小程序端） // App端需要更复杂的逻辑打开系统应用设置页 } else { failCallback && failCallback(err); } } }); } }); }

• iOS的相册权限细分：从iOS 14开始，相册权限分为“所有照片”和“选中的照片”。如果你的应用需要持续访问相册（如做图片备份），需要申请“所有照片”权限（NSPhotoLibraryUsageDescription），并在info.plist中配置好描述文案。如果只是让用户选一次图，使用PHPickerViewController（对应UniApp的API）则无需申请权限，系统会提供独立的选图界面。

4.3 多端UI与交互一致性

不同平台的原生选择器UI和交互是不同的。微信小程序的选图界面和App端调用系统相册的界面风格迥异。如果你对UI一致性有较高要求，有两条路：

1. 接受平台差异：向用户解释这是系统自带的功能，体验往往是最好的。这是成本最低、最稳定的方案。
2. 自定义文件选择器：在H5端，你可以完全自定义一个<input type=“file”>的样式，隐藏原生的丑陋按钮。在App端，你可以使用原生插件或自己用plus.io接口遍历目录，实现一个仿相册的列表界面。但这条路工作量巨大，且很难达到系统原生组件的性能和体验，非必要不推荐。

4.4 常见“坑点”与排查清单

• iOS上选择视频返回的路径无效：可能是临时文件被系统过早清理。解决方案：在选择成功后，立即使用uni.saveVideoToPhotosAlbum（需要权限）保存到相册，或者像前面讲的那样，复制到App的_doc目录。
• 安卓某些机型选择文件时崩溃：可能是选择了超大文件或特殊格式文件，内存溢出。需要加入文件大小和类型校验，在用户选择前就给出提示。
• H5端，uni.chooseImage在iOS Safari上只能选一张图：这是Safari浏览器的限制。解决方案是设置count: 1，或者通过创建多个<input type=“file”>元素来模拟多选，但体验不佳。通常建议在H5端对iOS用户做单选的引导。
• 选择文件后，获取到的文件名是乱码或无效：特别是从微信聊天文件中选择时。不要依赖API返回的name字段，最好自己从文件路径中提取后缀名，或者通过读取文件头信息来判断真实类型。
• 在模拟器上正常，真机上报错：永远要以真机调试为准。模拟器的文件系统和权限环境与真机有很大差异。

处理本地资源选取，本质上是在与各个移动操作系统的文件系统和权限模型打交道。UniApp提供了一层良好的抽象，但并没有消除底层的复杂性。理解每个API在不同平台下的真实行为，理解“临时路径”的真实含义，并做好兼容、降级和错误处理，是保证这个基础功能稳定可靠的关键。记住，用户不会关心这是Android、iOS还是小程序的差异，他们只关心在你的应用里，选择文件是否顺畅、快速、不出错。把这些细节做到位，应用的质感自然就上来了。