1. 项目概述为什么我们需要 Native Gallery 插件在 Unity 项目开发中尤其是面向移动平台Android/iOS时一个高频且“刚需”的功能就是访问设备的本地相册。无论是让用户上传头像、分享游戏截图还是保存生成的图片到本地都绕不开系统级的文件读写和相册交互。Unity 引擎本身并没有提供直接、稳定且跨平台的 API 来完成这些操作直接使用System.IO去读写移动设备的特定目录往往会遇到权限不足、路径错误、图片无法在系统相册中显示等一系列令人头疼的问题。这就是Unity Native Gallery 插件的价值所在。它本质上是一个桥梁封装了 Android 的MediaStoreAPI 和 iOS 的Photos Framework等原生接口为 Unity C# 脚本提供了简单、统一且功能完整的调用方式。我最近在一个社交类 App 项目中深度使用了这个插件亲测其免费版本的稳定性和易用性都相当出色完全能够满足绝大多数项目的需求。本指南将基于我的实际踩坑经验手把手带你完成从零开始的安装、配置到核心功能调用的全过程并分享那些官方文档里不会写的“实战心得”。2. 插件获取与项目导入的正确姿势2.1 官方渠道获取与版本选择首先最可靠的来源是 Unity Asset Store。在商店中搜索 “Native Gallery”通常能找到由 “Yasirkula” 开发的插件。确认作者很重要因为这是目前维护最活跃、社区反馈最多的版本。点击“添加到我的资源”并下载你会得到一个.unitypackage文件。注意网络上可能存在一些经过修改或捆绑的版本。为了项目安全与稳定性强烈建议只从官方 Asset Store 或开发者的 GitHub 仓库如https://github.com/yasirkula/UnityNativeGallery获取。免费版本功能已非常强大涵盖保存图片/视频到相册、从相册选取图片/视频、检查权限等核心功能。2.2 项目导入的详细步骤与潜在陷阱拿到.unitypackage文件后导入步骤看似简单但细节决定成败。打开目标 Unity 项目确保你的 Unity 编辑器版本与插件兼容。通常插件会支持较新的 LTS长期支持版本。我使用的是 Unity 2021.3 LTS经验证完全兼容。执行导入在 Unity 编辑器菜单栏点击Assets - Import Package - Custom Package...。选择文件在弹出的文件浏览器中找到你下载的NativeGallery.unitypackage文件名可能包含版本号如NativeGallery_v1.6.2.unitypackage点击“打开”。导入设置窗口此时会弹出一个窗口列出了插件包内所有待导入的文件和文件夹。这里有一个关键点不要无脑点击“Import”。你应该大致浏览一下文件结构。通常包含Plugins文件夹存放 Android AAR/JAR 和 iOS Framework、Scripts文件夹C# 脚本、Samples示例场景以及一些文档。确保所有文件都被勾选然后点击“Import”。Unity 会开始将文件解压并复制到你的项目 Assets 目录下。导入完成后你会在 Project 窗口的 Assets 目录下看到新增的 “NativeGallery” 或类似命名的文件夹。第一个常见坑点随之而来编译错误。特别是如果你的项目之前没有配置过移动端原生交互可能会立刻报出关于AndroidManifest.xml或Info.plist缺失某些权限或配置的错误。别慌这恰恰说明插件正在尝试引入必要的原生依赖我们下一步就是解决这些配置问题。3. 平台特异性配置详解Android iOS插件导入后核心的配置工作集中在平台特定的设置上。这是整个流程中最容易出错的部分需要仔细操作。3.1 Android 平台配置全流程Android 的配置主要涉及权限声明和AndroidManifest.xml文件的修改。自动检查与手动确认许多现代版本的 Native Gallery 插件会在导入时尝试自动向你的 Android 清单文件添加所需权限。你可以在Assets/Plugins/Android目录下找到一个可能由插件生成的AndroidManifest.xml文件。但不能完全依赖自动化。关键权限声明你需要确保以下权限被正确声明。打开你的主AndroidManifest.xml文件通常位于Assets/Plugins/Android如果不存在你需要创建一个Unity 在构建时会合并所有此类文件。 将以下代码插入到manifest标签内与application标签同级uses-permission android:nameandroid.permission.READ_EXTERNAL_STORAGE / uses-permission android:nameandroid.permission.WRITE_EXTERNAL_STORAGE / !-- 针对 Android 10 (API 29) 及以上还需要添加此权限以支持媒体文件访问 -- uses-permission android:nameandroid.permission.ACCESS_MEDIA_LOCATION /READ_EXTERNAL_STORAGE用于从相册读取图片/视频。WRITE_EXTERNAL_STORAGE用于保存图片/视频到相册。注意在 Android 10 上对于应用专属目录的写入可能不再需要此权限但为了向公共相册写入它仍然是必须的且插件内部逻辑依赖它。ACCESS_MEDIA_LOCATION如果你需要访问图片的 Exif 地理位置信息非必须则需要此权限。处理 Android 作用域存储Scoped Storage这是 Android 10 引入的重大变更。Native Gallery 插件已经做了适配。但为了确保兼容性建议在AndroidManifest.xml的application标签内添加以下属性android:requestLegacyExternalStoragetrue这个属性在针对 Android 10API 29时有效允许应用暂时以旧版存储模式运行。但请注意对于 Android 11API 30及以上此属性已失效。插件自身的逻辑会处理 Android 11 的兼容性问题通常通过使用MediaStoreAPI 来替代直接文件路径访问。配置 Player Settings转到File - Build Settings - Player Settings...。在Other Settings区域找到Write Permission确保其设置为External (SDCard)。这对应着WRITE_EXTERNAL_STORAGE权限的自动声明但手动声明上一步的权限仍是好习惯。检查Minimum API Level建议至少设置为API Level 21 (Android 5.0)以上以确保更好的兼容性。3.2 iOS 平台配置要点iOS 的配置相对简洁但要求非常精确主要涉及Info.plist文件中的权限描述。修改 Info.plist在 Unity 中Info.plist的配置是通过在Player Settings中添加描述来实现的。打开Player Settings切换到 iOS 平台。添加隐私描述在Other Settings区域找到Camera Usage Description和Photo Library Usage Description或类似的Privacy - Photo Library Usage Description。Camera Usage Description(NSCameraUsageDescription)如果你需要调用插件中可能涉及的相机功能例如先拍照再保存则需要填写此描述例如“需要访问相机来拍摄头像照片”。Photo Library Usage Description(NSPhotoLibraryUsageDescription)这是必须的。当插件尝试访问相册时系统会向用户展示这个描述。你必须填写一个清晰的理由例如“需要访问相册来上传图片或保存游戏截图”。这个字符串会直接显示在系统的权限弹窗上审核非常严格不能为空或敷衍。注意权限细分iOS 14从 iOS 14 开始相册权限分为“读取和写入”和“仅添加照片”。Native Gallery 插件通常需要“读取和写入”权限。Unity 的Player Settings可能还提供了Photo Library Additions Usage Description仅添加的选项但为了完整功能确保主描述读写权限已正确设置。4. 核心 API 使用与实战代码解析配置妥当后就可以在 C# 脚本中愉快地调用 Native Gallery 的功能了。其 API 设计得非常直观。以下是我在项目中实际使用的几个核心场景代码并附上了详细注释。4.1 保存图片到系统相册这是最常用的功能比如保存游戏截图、生成的分享图等。using UnityEngine; using System.Collections; // 引入 NativeGallery 命名空间 using NativeGallery; public class ImageSaver : MonoBehaviour { public void SaveTextureToGallery(Texture2D texture, string filename MyScreenshot.png) { // 1. 权限检查异步 StartCoroutine(CheckAndSave(texture, filename)); } private IEnumerator CheckAndSave(Texture2D texture, string filename) { // 检查是否有写入相册的权限 var permission NativeGallery.CheckPermission(NativeGallery.PermissionType.Write); // 如果权限状态是“应该询问”或“未知”则请求权限 if(permission NativeGallery.Permission.ShouldAsk || permission NativeGallery.Permission.Unknown) { permission NativeGallery.RequestPermission(NativeGallery.PermissionType.Write); // 等待权限请求完成这是一个异步操作但在协程中我们可以等待 // 注意在真实项目中你可能需要更复杂的UI流程来处理用户拒绝的情况 while(permission NativeGallery.Permission.ShouldAsk) yield return null; } // 2. 权限获取成功后执行保存 if(permission NativeGallery.Permission.Granted) { // 关键步骤将Texture2D转换为字节数组。PNG格式最通用。 byte[] imageBytes texture.EncodeToPNG(); // 调用保存API // 参数1自定义相册文件夹名称可为null则保存到默认的“Pictures”或“相册” // 参数2自定义文件名不含路径 // 参数3扩展名用于系统识别文件类型 // 参数4图片字节数据 // 参数5回调函数接收保存是否成功以及文件路径的信息 NativeGallery.SaveImageToGallery( imageBytes, MyGameScreenshots, // 在相册中创建一个“MyGameScreenshots”文件夹 filename, (success, path) { Debug.Log($图片保存{(success ? 成功 : 失败)}路径{path}); if(success) { // 可以在这里触发UI提示如“截图已保存到相册” } } ); } else { Debug.LogError(没有写入相册的权限保存操作被拒绝。); // 这里应该引导用户去系统设置中手动开启权限 } } }实操心得EncodeToPNG()是一个同步的CPU密集型操作如果纹理很大如4K截图可能会造成主线程卡顿。对于大纹理建议在子线程或使用JobSystem进行编码再将字节数组传回主线程调用SaveImageToGallery。回调函数中的path是系统返回的媒体库Uri路径content://...或file://...不要尝试直接用这个路径去File.Read它可能不是直接的文件路径。如果后续需要读取应再次通过插件的LoadImageAtPath等方法。4.2 从相册中选择图片用于头像上传、图片分享等场景。using UnityEngine; using UnityEngine.UI; // 假设我们要将选中的图片显示在RawImage上 using NativeGallery; public class ImagePicker : MonoBehaviour { public RawImage displayImage; // UI上的RawImage组件 public void PickImage() { // 检查读取权限流程与保存时类似PermissionType.Read NativeGallery.Permission permission NativeGallery.CheckPermission(NativeGallery.PermissionType.Read, NativeGallery.MediaType.Image); if(permission NativeGallery.Permission.ShouldAsk || permission NativeGallery.Permission.Unknown) { permission NativeGallery.RequestPermission(NativeGallery.PermissionType.Read, NativeGallery.MediaType.Image); // 实际项目中需要处理异步等待和用户拒绝 } if(permission NativeGallery.Permission.Granted) { // 打开系统图片选择器 // 参数1选择后的回调函数 // 参数2选择框标题 // 参数3支持的文件类型描述 NativeGallery.GetImageFromGallery((path) { if(!string.IsNullOrEmpty(path)) { Debug.Log($选中图片路径{path}); // 使用插件提供的工具方法加载图片为Texture2D Texture2D loadedTexture NativeGallery.LoadImageAtPath(path, -1, false, false, false); if(loadedTexture ! null) { // 应用加载到的纹理 displayImage.texture loadedTexture; // 注意加载的Texture2D需要在使用完毕后手动Destroy否则会造成内存泄漏 // 通常可以在替换纹理前销毁旧的Destroy(displayImage.texture as Texture2D); } else { Debug.LogError(从路径加载图片失败 path); } } else { Debug.Log(用户取消了图片选择。); } }, 选择一张图片, image/*); } else { Debug.LogError(没有读取相册的权限。); } } }避坑指南LoadImageAtPath方法参数详解path选择器返回的路径。maxSize-1表示加载原始尺寸可以指定一个最大宽度/高度来限制纹理大小节省内存。markTextureNonReadable设为true可节省少量内存但之后无法调用GetPixels()等读取像素的方法。根据需求选择。generateMipmaps是否生成Mipmap链对于3D物体贴图通常需要。linearColorSpace是否使用线性颜色空间加载。如果你的项目是Gamma空间通常设为false。内存管理由LoadImageAtPath创建的Texture2D对象是new出来的Unity 不会自动管理。务必在不再需要时如切换图片时手动调用Destroy(oldTexture)否则会导致严重的内存泄漏。4.3 保存与选择视频视频操作与图片类似API 命名也高度一致。// 保存视频例如录屏功能 public void SaveVideoToGallery(string existingVideoPath) { // 假设 existingVideoPath 是你已经录制好的视频文件在应用沙盒内的路径 NativeGallery.SaveVideoToGallery(existingVideoPath, MyGameVideos, MyRecording.mp4, (success, path) { Debug.Log($视频保存{(success ? 成功 : 失败)}路径{path}); }); } // 选择视频 public void PickVideo() { NativeGallery.GetVideoFromGallery((path) { if(!string.IsNullOrEmpty(path)) { Debug.Log($选中视频路径{path}); // 你可以使用 Unity 的 VideoPlayer 组件来播放这个路径的视频 // 注意在 Android 上返回的 path 可能是一个 Content UriVideoPlayer 可能无法直接播放。 // Native Gallery 插件提供了一个工具方法 NativeGallery.IsMediaPickerBusy() 和 NativeGallery.GetVideoThumbnail 来获取视频缩略图。 // 对于视频播放更可靠的方式是使用插件提供的 NativeGallery.GetVideoProperties 获取信息或使用其他专门处理 Content Uri 的插件。 } }, 选择一个视频, video/*); }重要提醒在 Android 上处理视频特别是播放比图片更复杂因为返回的path很可能是一个content://URIUnity 的标准VideoPlayer或WWW/UnityWebRequest可能无法直接处理。如果你需要播放从相册选取的视频可能需要额外的原生插件或更复杂的流处理方案。Native Gallery 插件主要解决了“获取”这个入口问题。5. 实战中遇到的典型问题与解决方案即使配置和代码都正确在实际真机测试中你依然可能会遇到一些“诡异”的问题。下面是我和团队踩过的一些坑以及解决办法。5.1 Android 构建失败“Failed to merge android manifests”问题现象在 Build Android APK 时控制台报错提示清单文件合并冲突。原因分析这通常是因为项目中存在多个AndroidManifest.xml文件例如来自不同的插件它们定义了相同的组件或权限但属性冲突。Native Gallery 插件自带的清单文件可能与其他插件如 Firebase、广告 SDK的清单产生冲突。解决方案定位冲突文件查看错误日志找到具体是哪个节点冲突例如application的android:theme属性或者某个activity。使用主清单覆盖在 Unity 的Player Settings - Publishing Settings中勾选Custom Main Manifest和Custom Main Gradle Template如果使用Gradle构建。这允许你创建一个主清单文件来统一管理配置。创建主 AndroidManifest.xml在Assets/Plugins/Android目录下创建AndroidManifest.xml如果已有则编辑它。将必要的配置如权限、application属性整合进去。对于冲突的属性以你的主设置为准。你可以参考插件生成的清单内容但将其合并到你的主文件中然后删除或重命名插件带来的额外清单文件例如将NativeGallery/Plugins/Android/AndroidManifest.xml改名为AndroidManifest.xml.bak以禁用之。使用 Gradle 属性排除如果使用 Gradle可以在mainTemplate.gradle中添加packagingOptions来排除重复的元数据文件但这对于清单合并冲突效果有限主要针对资源冲突。5.2 iOS 构建后相册权限弹窗不出现或描述不显示问题现象在 iOS 真机上调用相册功能时系统没有弹出权限请求窗口或者弹窗上的描述文字是空的。原因排查描述字符串为空回头检查Player Settings - iOS - Camera Usage Description和Photo Library Usage Description确保里面填入了非空的、有意义的字符串。即使你不需要相机权限如果代码中可能触发也最好填上。Info.plist 条目缺失Unity 的 Player Settings 应该能正确生成Info.plist。但有时构建后可以检查生成的 Xcode 工程中的Info.plist文件看对应的NSCameraUsageDescription和NSPhotoLibraryUsageDescription键值是否存在且正确。权限请求时机iOS 有严格的权限请求策略。切忌在应用一启动就请求所有权限这很可能被系统拒绝或导致用户反感。应该在实际需要用到该功能的前一刻例如用户点击“上传头像”按钮时才调用NativeGallery.RequestPermission。插件内部的请求逻辑是符合这个最佳实践的。5.3 在 Android 10/11 上保存成功但在相册中看不到图片问题现象调用SaveImageToGallery回调显示成功path也有返回值但打开系统相册或图库App却找不到刚保存的图片。问题根源这是 Android 作用域存储Scoped Storage的典型表现。从 Android 10 开始应用向媒体库MediaStore插入条目后系统需要一段时间进行索引Media Scanning索引完成后图片才会在所有图库应用中可见。这个过程可能有几秒到几分钟的延迟。解决方案与验证使用系统“媒体扫描”通知保存完成后可以尝试发送一个广播通知系统立即扫描该文件但此方法在 Android 10 上可能受限或无效。// 这是一个传统方法在新系统上可能不总是有效 AndroidJavaClass unityPlayer new AndroidJavaClass(com.unity3d.player.UnityPlayer); AndroidJavaObject currentActivity unityPlayer.GetStaticAndroidJavaObject(currentActivity); AndroidJavaObject intent new AndroidJavaObject(android.content.Intent, android.intent.action.MEDIA_SCANNER_SCAN_FILE); AndroidJavaObject uri new AndroidJavaObject(android.net.Uri, file:// filePath); // 注意需要文件路径不是content uri intent.CallAndroidJavaObject(setData, uri); currentActivity.Call(sendBroadcast, intent);更可靠的方法使用 MediaStore API 直接插入。幸运的是Native Gallery 插件内部已经使用了MediaStoreAPI。所以如果你使用的是最新版插件理论上它已经处理了索引问题。回调成功意味着条目已插入媒体数据库。验证方法等待一分钟左右再查看相册。使用系统的“文件管理”App导航到Pictures/目录下你指定的相册文件夹如MyGameScreenshots看看文件是否确实存在。如果文件存在说明保存是成功的只是系统相册的索引有延迟。重启手机或等待更长时间索引通常最终会完成。5.4 纹理格式与性能问题问题保存或加载大尺寸图片时如 4K 截图游戏帧率骤降或内存飙升。分析与优化编码/解码在主线程如前所述Texture2D.EncodeToPNG()和LoadImageAtPath内部解码是 CPU 密集型操作。优化保存对于保存可以考虑在子线程中进行编码。Unity 本身不支持多线程调用大部分 API但你可以将纹理数据GetRawTextureData复制到一个字节数组然后在ThreadPool或使用System.Threading.Tasks进行压缩需自行实现或使用第三方库最后回到主线程调用SaveImageToGallery。优化加载LoadImageAtPath的maxSize参数是你的好朋友。对于仅用于 UI 显示的缩略图将maxSize设置为 512 或 1024可以大幅减少内存占用和解码时间。如果需要原图再考虑异步或分步加载。纹理格式确保你保存的纹理格式是RGBA32或RGB24。一些渲染纹理或压缩格式如DXT可能无法直接EncodeToPNG需要先通过ReadPixels和Apply转换到一个新的Texture2D。6. 进阶技巧与扩展思路掌握了基础功能后可以探索一些更进阶的用法来提升用户体验和功能完整性。6.1 实现异步等待与用户友好的权限引导权限请求是异步的且用户可能拒绝。我们需要一个更健壮的流程。public class RobustGalleryManager : MonoBehaviour { public System.Actionbool OnPermissionCompleted; // 权限请求完成回调 public IEnumerator RequestGalleryPermission(NativeGallery.PermissionType type) { var permission NativeGallery.CheckPermission(type); if (permission NativeGallery.Permission.ShouldAsk) { // 显示一个自定义的UI弹窗解释为什么需要权限 // yield return ShowPermissionExplanationDialog(); permission NativeGallery.RequestPermission(type); // 等待权限状态不再是 ShouldAsk while (permission NativeGallery.Permission.ShouldAsk) { yield return null; } } bool granted (permission NativeGallery.Permission.Granted); if (!granted permission NativeGallery.Permission.Denied) { // 权限被拒绝显示引导用户去系统设置开启权限的UI // yield return ShowGoToSettingsDialog(); // 注意无法通过代码直接跳转到应用设置页但可以提示用户如何操作 Debug.Log(权限被拒绝请前往系统设置中为应用开启存储权限。); } OnPermissionCompleted?.Invoke(granted); } // 在需要权限的地方调用 public void TrySaveScreenshot() { StartCoroutine(RequestGalleryPermission(NativeGallery.PermissionType.Write)); // 在 OnPermissionCompleted 回调中执行实际的保存操作 } }6.2 与其他插件如截图插件协同工作Native Gallery 常与截图插件如ScreenCapture.CaptureScreenshot或更高级的Unity Screenshot插件配合使用。public IEnumerator TakeAndSaveScreenshot() { yield return new WaitForEndOfFrame(); // 等待一帧渲染结束 Texture2D screenshot new Texture2D(Screen.width, Screen.height, TextureFormat.RGB24, false); screenshot.ReadPixels(new Rect(0, 0, Screen.width, Screen.height), 0, 0); screenshot.Apply(); // 现在有了 screenshot 纹理调用之前写的保存方法 SaveTextureToGallery(screenshot, $Screenshot_{System.DateTime.Now:yyyyMMdd_HHmmss}.png); // 清理纹理 Destroy(screenshot); }注意ReadPixels和Apply也是主线程操作对于高分辨率屏幕可以考虑分块读取或使用异步截图插件。6.3 针对特定平台的微调Android 文件名与中文保存文件时尽量避免在文件名中使用特殊字符或中文虽然现代系统支持较好但为求稳妥使用英文、数字和下划线组合是最安全的选择。iOS 相册分组在 iOS 上SaveImageToGallery的相册文件夹参数如MyGameScreenshots会对应系统相册中一个独立的“相簿”。如果该相簿不存在系统会自动创建。这是一个很好的功能能让用户整理的图片归类清晰。内存与缓存频繁地保存和加载大图会迅速消耗内存。建立对象池管理临时Texture2D或及时Destroy不再需要的纹理对象。对于需要展示的相册图片列表优先加载和显示缩略图。通过以上从安装配置、核心API使用到问题排查和进阶技巧的完整梳理你应该能够顺利地在你的 Unity 项目中集成并驾驭 Native Gallery 插件。记住移动端原生交互总是伴随着平台差异和权限管理耐心测试尤其是真机测试和查阅插件官方文档通常GitHub Wiki上有最新信息是解决问题的最终捷径。