1. 项目概述为什么需要Native Gallery如果你在Unity里做过需要访问手机相册的功能比如让用户上传头像、保存游戏截图或者分享游戏内生成的图片那你一定遇到过这个经典难题Unity的API在移动平台上特别是涉及到系统原生功能时显得力不从心。Application.persistentDataPath里的图片用户在自己的相册App里根本找不到想调用系统相册选择图片却发现Unity没有提供现成的跨平台接口。这时候一个成熟、稳定的第三方插件就成了必需品。Native Gallery for Unity正是为解决这个痛点而生的。它不是一个简单的文件读写工具而是一个精心封装的、与Android的MediaStore和iOS的Photos Framework直接对话的桥梁。它的核心价值在于让Unity开发者可以用几乎相同的C#代码在Android和iOS上实现完整的相册交互功能保存图片/视频到相册、从相册中选择图片/视频、获取媒体文件的路径和元数据并且请求必要的权限。这避免了开发者分别去研究Android的Java/Kotlin和iOS的Objective-C/Swift将跨平台的复杂性封装在插件内部。我接手过好几个需要深度集成手机相册的项目从最初的自己写Android插件、iOS插件到后来统一使用Native Gallery效率的提升是肉眼可见的。这个“终极配置指南”就是把我趟过的坑、验证过的流程以及那些官方文档可能没细说但对项目稳定性至关重要的细节系统地梳理出来。目标很简单让你在30分钟内从一个干净的Unity项目开始到最终打包出能在真机上稳定运行的APK或IPA彻底搞定Native Gallery的集成与配置。2. 核心思路与前置准备理解插件的工作机制在开始动手之前花几分钟理解Native Gallery的工作原理能让你在后续配置和排查问题时事半功倍。这个插件本质上是一个“胶水层”Glue Layer。2.1 插件架构解析在Android端它内部包含了一个Android Library模块AAR。当你调用NativeGallery.SaveImageToGallery时C#代码会通过Unity的AndroidJavaClass和AndroidJavaObject接口调用到这个AAR里的Java方法。这个Java方法再去操作Android系统的MediaStoreAPI完成图片插入系统媒体库的工作。权限请求也是通过这个AAR发起的它会弹出系统的权限对话框。在iOS端它则通过Unity的[DllImport(__Internal)]特性调用预先编译好的原生C函数。这些C函数再通过Objective-C Runtime去调用iOS的UIImageWriteToSavedPhotosAlbum和PHPickerViewController等系统框架。iOS的权限Photo Library Access描述也需要在Xcode工程中配置。2.2 环境准备清单“工欲善其事必先利其器”。错误的开发环境是后续一切问题的根源。请严格按照以下清单核对你的环境不要跳过任何一步。Unity版本官方推荐使用2019.4 LTS或更新版本。我强烈建议使用一个LTS长期支持版本如2022.3 LTS它在稳定性和插件兼容性上表现最好。避免使用最新的Tech Stream版本可能会遇到未预料的兼容性问题。目标平台确认你的项目需要发布到Android、iOS或两者都要。本指南会涵盖双平台配置。Android环境Unity Hub中安装Android Build Support模块这是基础。JDK使用Unity内置的OpenJDK通常最省心在Player Settings - Publishing Settings中可指定。如果你想用自己安装的JDK请确保是JDK 8或11并设置好JAVA_HOME环境变量。高版本JDK如17可能导致Gradle构建失败。Android SDK NDK通过Unity Hub安装或自行下载。确保路径正确配置在Unity的Preferences - External Tools中。NDK版本建议使用Unity推荐版本如r23b。GradleUnity默认使用内置的Gradle。对于复杂项目可能需要使用本地Gradle。确保版本兼容通常Unity会指定。iOS环境macOS电脑这是必须的用于最后的Xcode构建和签名。Xcode安装最新稳定版。同时确保命令行工具已安装xcode-select --install。Apple开发者账号用于真机测试和上架。需要配置证书和描述文件。注意网络上很多“Unity关联JDK总是提示无法找到”的问题90%是因为JDK路径包含中文或特殊字符或者环境变量冲突。最稳妥的方案就是直接使用Unity内置的OpenJDK。3. 插件导入与基础配置避开第一个大坑拿到Native Gallery插件的.unitypackage文件后别急着双击导入。先关闭Unity进行项目备份然后按步骤操作。3.1 插件导入的正确姿势新建一个干净的Unity项目或确保你的现有项目没有其他可能冲突的媒体/文件插件。打开Unity在Project面板右键 -Import Package - Custom Package...选择你的.unitypackage文件。在导入对话框中务必展开所有目录仔细查看。通常插件会包含Plugins/Android和Plugins/iOS文件夹以及示例场景。全部勾选点击Import。导入后你可能会在Console窗口看到一些关于“API Compatibility Level”或“.NET Standard vs .NET Framework”的警告。先别慌我们一步步解决。3.2 Android平台关键配置详解这是配置的重中之重大部分问题都出在这里。切换平台打开File - Build Settings选择Android平台点击Switch Platform。等待编译完成。Player Settings设置Other SettingsPackage Name设置为你的应用唯一标识如com.yourcompany.yourgame。Minimum API Level建议设置为API Level 23 (Android 6.0 Marshmallow)或更高。因为动态权限请求是从Android 6.0开始的Native Gallery需要这个特性。Target API Level设置为你要适配的最高版本通常建议使用最新的稳定版如API Level 34。保持更新有助于应用商店合规。Scripting Backend选择IL2CPP。这是现代Unity项目的标准能带来更好的性能和安全性。如果项目必须用Mono请确保插件兼容。Target Architectures勾选ARMv7和ARM64。只勾选ARM64可以减小包体但会放弃一部分老旧设备。Publishing SettingsCustom Main Gradle Template这是关键一步勾选这个选项。这会在你的项目Assets/Plugins/Android目录下生成一个mainTemplate.gradle文件。Native Gallery的AAR依赖需要通过这个文件来声明。配置Gradle依赖打开生成的Assets/Plugins/Android/mainTemplate.gradle文件。找到dependencies区块在里面添加Native Gallery所需的依赖。通常插件文档会说明常见添加如下dependencies { // ... Unity自动生成的依赖 ... implementation com.android.support:exifinterface:28.0.0 // 用于处理图片EXIF信息 // 如果插件需要其他支持库也可能在这里添加 // implementation com.android.support:appcompat-v7:28.0.0 }实操心得有时插件AAR已经包含了所有依赖这里就不需要额外添加。但如果你在运行时遇到ClassNotFoundException首先就来检查这里。另一个常见错误是Gradle版本与支持库版本不兼容如果遇到构建失败可以尝试注释掉添加的依赖行看是否是这里的问题。权限配置在Assets/Plugins/Android目录下找到或创建一个名为AndroidManifest.xml的文件如果Unity没有自动生成你可以从Temp目录复制一个基础版本过来。在其中添加必要的权限?xml version1.0 encodingutf-8? manifest ... uses-permission android:nameandroid.permission.READ_EXTERNAL_STORAGE android:maxSdkVersion32 / uses-permission android:nameandroid.permission.WRITE_EXTERNAL_STORAGE android:maxSdkVersion32 / uses-permission android:nameandroid.permission.READ_MEDIA_IMAGES / uses-permission android:nameandroid.permission.READ_MEDIA_VIDEO / !-- 如果你的应用需要Android 13API 33以下的视频访问还需要这个 -- !-- uses-permission android:nameandroid.permission.READ_MEDIA_AUDIO / -- application ... ... /application /manifest注意Android权限策略变化对于Android 10 (API 29) 及以上作用域存储Scoped Storage被强制执行WRITE_EXTERNAL_STORAGE权限对于访问共享存储如下载、相册目录已经失效。Android 13 (API 33) 引入了更细粒度的媒体权限READ_MEDIA_IMAGES、READ_MEDIA_VIDEO、READ_MEDIA_AUDIO。因此我们需要一个兼容性的权限声明方案READ_EXTERNAL_STORAGE和WRITE_EXTERNAL_STORAGE加上android:maxSdkVersion32表示只对Android 12及以下设备申请。对于Android 13及以上声明READ_MEDIA_IMAGES和READ_MEDIA_VIDEO。Native Gallery的内部逻辑会处理不同系统版本的权限请求。3.3 iOS平台关键配置详解iOS的配置相对集中主要在Player Settings和后续的Xcode工程中。Player Settings设置在Build Settings中切换到iOS平台。在Player Settings - Other Settings中Target minimum iOS Version设置为11.0或更高。Native Gallery的现代API需要这个基础版本。Camera Usage Description和Photo Library Usage Description这两个字段必须填写这是苹果的隐私要求。填写清晰的理由告诉用户你为什么需要访问相机和相册。例如“用于保存游戏截图至您的相册”和“用于从您的相册中选择头像图片”。描述文字会显示在系统的权限弹窗上。准备Xcode工程在Unity中Build出Xcode工程后打开它。你需要确保签名与能力在Signing Capabilities中使用正确的Team和Bundle Identifier并确保AppTarget的Background Modes等能力符合你的需求对于纯相册功能通常不需要额外能力。权限描述再次确认在Info.plist文件中你应该能看到在Unity中设置的NSCameraUsageDescription和NSPhotoLibraryUsageDescription键值对。如果没有需要手动添加。4. 核心功能代码实现与详解配置好环境我们来写代码。Native Gallery的API设计得很简洁但每个参数和回调都值得细究。4.1 保存媒体文件到相册这是最常用的功能。以保存一张渲染纹理RenderTexture的截图为例。using UnityEngine; using System.Collections; public class GalleryDemo : MonoBehaviour { public RenderTexture screenshotRT; // 假设这是你要保存的渲染纹理 public void SaveScreenshotToGallery() { // 1. 将RenderTexture转换为Texture2D Texture2D tex new Texture2D(screenshotRT.width, screenshotRT.height, TextureFormat.RGB24, false); RenderTexture.active screenshotRT; tex.ReadPixels(new Rect(0, 0, screenshotRT.width, screenshotRT.height), 0, 0); tex.Apply(); RenderTexture.active null; // 2. 调用NativeGallery保存图片 string albumName MyGameScreenshots; // 相册中创建的文件夹名Android有效iOS会保存在相机胶卷 string filename Screenshot_ System.DateTime.Now.ToString(yyyyMMdd_HHmmss) .png; // 关键参数解析 // tex: 要保存的Texture2D // albumName: 自定义相册名Android // filename: 保存的文件名 // callback: 保存完成后的回调返回是否成功和文件路径 NativeGallery.Permission permission NativeGallery.SaveImageToGallery( tex, albumName, filename, (bool success, string path) { Debug.Log($Save image result: {success}, path: {path}); if (success) { // 保存成功可以提示用户或对path进行进一步操作 // 注意path在iOS上可能是ph://开头的Photos框架标识符不是直接的文件路径。 StartCoroutine(ShowSaveSuccessPopup()); } else { // 保存失败可能是权限被拒绝或磁盘空间不足 Debug.LogError(Failed to save image to gallery.); } } ); // 3. 处理权限结果SaveImageToGallery内部已包含权限请求 // 如果用户之前已拒绝并选择“不再询问”permission可能是 NativeGallery.Permission.Denied if(permission NativeGallery.Permission.Denied) { // 需要引导用户去应用设置手动开启权限 OpenAppSettings(); } // 4. 清理临时Texture2D Destroy(tex); } IEnumerator ShowSaveSuccessPopup() { // 简单的UI提示实际项目中替换为你的UI逻辑 yield return new WaitForEndOfFrame(); Debug.Log(图片已成功保存到相册); } void OpenAppSettings() { #if UNITY_ANDROID using (var unityClass new AndroidJavaClass(com.unity3d.player.UnityPlayer)) using (var currentActivity unityClass.GetStaticAndroidJavaObject(currentActivity)) { var intent new AndroidJavaObject(android.content.Intent, android.settings.APPLICATION_DETAILS_SETTINGS); var uri new AndroidJavaObject(android.net.Uri).CallStaticAndroidJavaObject(fromParts, package, currentActivity.Callstring(getPackageName), null); intent.CallAndroidJavaObject(setData, uri); currentActivity.Call(startActivity, intent); } #elif UNITY_IOS // iOS上系统设置跳转需要特定URL Scheme通常通过其他插件或告知用户手动操作 UnityEngine.Application.OpenURL(app-settings:); #endif } }注意事项性能SaveImageToGallery是异步操作不会阻塞主线程。但将大尺寸的RenderTexture转换为Texture2D并调用ReadPixels是一个非常耗CPU的操作务必避免在每帧调用。对于连续截图考虑使用ScreenCapture.CaptureScreenshotAsTexture较新版本或RenderTexture.GetTemporary进行优化。文件格式与质量保存为PNG是无损的但文件大。JPG可以指定质量参数通过重载方法但会有损压缩。根据需求选择。Android相册刷新有时保存后在系统相册App里不会立即看到新图片。这是因为MediaStore的数据库更新有延迟。可以尝试发送一个广播Android特定来通知媒体扫描器但这不是必须的通常等待几秒或重启相册App即可。4.2 从相册中选择图片/视频选择功能涉及权限请求和回调处理。public void PickImageFromGallery() { // 设置图片选择属性 NativeGallery.Permission permission NativeGallery.GetImageFromGallery((string path) { if (!string.IsNullOrEmpty(path)) { Debug.Log(Selected image path: path); // 将选中的图片加载为Texture2D StartCoroutine(LoadSelectedImage(path)); } else { Debug.Log(Image selection cancelled or failed.); } }, Select a PNG image, // 选择器标题 image/png); // MIME类型过滤只显示PNG图片。可设为image/*选择所有图片 Debug.Log(Permission status after pick request: permission); } IEnumerator LoadSelectedImage(string imagePath) { // 注意在Android上从相册返回的path可能是content:// URI不能直接用WWW或UnityWebRequest加载。 // NativeGallery提供了一个工具方法将其转换为可用的路径。 string loadablePath NativeGallery.ConvertMediaUriToFilePath(imagePath); // 使用UnityWebRequest加载图片 using (UnityWebRequest uwr UnityWebRequestTexture.GetTexture(file:// loadablePath)) { yield return uwr.SendWebRequest(); if (uwr.result UnityWebRequest.Result.Success) { Texture2D selectedTexture DownloadHandlerTexture.GetContent(uwr); // 现在你可以使用selectedTexture了例如赋值给RawImage // GetComponentRawImage().texture selectedTexture; } else { Debug.LogError(Failed to load image: uwr.error); } } }4.3 检查与请求权限最佳实践不应该在每次操作前都弹权限框。最佳实践是在应用启动或进入相关功能模块时检查并适时请求。public void CheckAndRequestPermission() { // 检查是否有权限读取媒体文件对于选择图片是必须的 NativeGallery.Permission readPermission NativeGallery.CheckPermission(NativeGallery.PermissionType.Read); if (readPermission NativeGallery.Permission.ShouldAsk) { // 尚未询问过主动请求 NativeGallery.RequestPermission(NativeGallery.PermissionType.Read, (NativeGallery.Permission permission) { Debug.Log(Read permission result: permission); if (permission NativeGallery.Permission.Granted) { // 权限已授予可以启用相册选择按钮 } else { // 权限被拒绝禁用相关功能并提示用户 ShowPermissionDeniedDialog(); } }); } else if (readPermission NativeGallery.Permission.Denied) { // 用户已拒绝且可能勾选了“不再询问”直接引导去设置 OpenAppSettings(); } // 如果是 Granted则已有权限 }5. 平台特异性问题与深度避坑指南即使配置和代码都正确不同平台、不同系统版本仍会带来挑战。以下是实战中总结的高频问题。5.1 Android平台深度避坑UnityWebRequest加载content://URI失败这是Android上最常见的坑。从相册返回的路径往往是content://media/external/images/media/12345这样的URI直接传给UnityWebRequest或WWW会失败。必须使用NativeGallery.ConvertMediaUriToFilePath(path)进行转换它会尝试将其转换为/storage/emulated/0/...形式的真实路径或者在无法转换时返回一个可通过File.ReadAllBytes读取的临时文件路径。Android 10 (Scoped Storage) 下的写入问题SaveImageToGallery方法内部已经适配了作用域存储。它通过MediaStore.Images.MediaAPI插入图片这是Google推荐的方式。切勿再尝试直接写文件到Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_DCIM)等旧路径这些方法在Android 10及以上可能失效或需要特殊权限。Gradle构建失败Program type already present这通常是依赖冲突。检查你的mainTemplate.gradle和插件自带的.aar文件。如果项目中还有其他插件如Firebase、Facebook SDK它们可能引入了不同版本的支持库如androidx.appcompat。解决方案是使用Gradle的exclude或强制指定统一版本。在mainTemplate.gradle的dependencies块末尾添加configurations.all { resolutionStrategy { force androidx.appcompat:appcompat:1.3.1 force androidx.exifinterface:exifinterface:1.3.3 // 强制其他可能有冲突的库版本 } }保存的图片在相册中不显示如前所述可能是媒体库未刷新。可以尝试在保存成功后执行以下代码仅Android#if UNITY_ANDROID using (AndroidJavaClass mediaScanner new AndroidJavaClass(android.media.MediaScannerConnection)) using (AndroidJavaObject context new AndroidJavaClass(com.unity3d.player.UnityPlayer).GetStaticAndroidJavaObject(currentActivity)) { mediaScanner.CallStatic(scanFile, context, new string[] { savedFilePath }, new string[] { image/png }, null); } #endif但请注意从Android 10开始对共享存储区的直接文件访问受限此方法可能不总是有效。依赖MediaStore的插入操作并等待系统同步是更可靠的做法。5.2 iOS平台深度避坑权限描述Usage Description缺失导致审核被拒这是上架App Store时的高频拒绝原因。确保Camera Usage Description和Photo Library Usage Description不仅填写了而且描述清晰、诚实符合应用的功能。敷衍的描述如“需要权限”会被拒绝。PHPhotoLibrary授权状态回调在iOS上用户可以选择“选中的照片”这种部分授权。Native Gallery应该能处理这种状态。但在你的代码中当用户拒绝或限制访问时要有友好的引导界面提示用户去系统设置Settings - 你的App中修改权限为“所有照片”。iOS保存路径的差异在iOS上SaveImageToGallery回调返回的path可能是一个以ph://开头的标识符而不是文件系统路径。你不能直接用它来读取文件数据。如果需要再次处理已保存的图片应该在保存前保留一份Texture2D的副本或者通过其他方式管理你的资源。构建到真机时Xcode报签名错误确保在Xcode中Signing Capabilities中选择正确的Team付费开发者账号。Bundle Identifier是唯一的。在Build Settings - Signing中Provisioning Profile选择了正确的描述文件通常Xcode自动管理即可。如果使用自定义能力Capabilities如iCloud、Push Notifications确保它们在Apple Developer Portal中已为你的App ID启用。5.3 通用性能与内存优化纹理尺寸手机相册的图片分辨率可能非常高1200万、4800万像素。直接加载这样的原图到Texture2D会瞬间消耗大量内存可能导致应用崩溃。务必在加载后对纹理进行缩放。IEnumerator LoadAndScaleTexture(string filePath, int maxSize) { // ... 使用UnityWebRequest加载纹理 ... Texture2D originalTex DownloadHandlerTexture.GetContent(uwr); // 计算缩放比例 int targetWidth, targetHeight; if (originalTex.width originalTex.height) { targetWidth Mathf.Min(maxSize, originalTex.width); targetHeight Mathf.RoundToInt((float)originalTex.height * targetWidth / originalTex.width); } else { targetHeight Mathf.Min(maxSize, originalTex.height); targetWidth Mathf.RoundToInt((float)originalTex.width * targetHeight / originalTex.height); } // 创建缩放后的纹理 Texture2D scaledTex new Texture2D(targetWidth, targetHeight, TextureFormat.RGBA32, false); Graphics.ConvertTexture(originalTex, scaledTex); // 高效缩放方法 // 或者使用更传统的ScaleTexture方法 // scaledTex ScaleTexture(originalTex, targetWidth, targetHeight); Destroy(originalTex); // 立即销毁大纹理 // 使用scaledTex... }异步操作与UI响应所有NativeGallery的调用都是非阻塞的但加载大文件、转换纹理是同步的。一定要在协程或异步方法中处理这些耗时操作避免卡住主线程。在操作期间显示一个加载指示器Loading Spinner是良好的用户体验。6. 进阶应用与扩展思路当基础功能稳定后可以考虑以下进阶优化提升用户体验和功能完整性。6.1 实现自定义图片选择器UINative Gallery调用的是系统原生的选择器。如果你需要更统一的UI风格或者想实现多选、滤镜预览等功能就需要自己实现一个。思路是使用NativeGallery.GetImagesFromGallery如果插件支持多选或多次调用单选择获取多个路径。使用UnityWebRequestTexture异步加载所有选中图片的缩略图。在Unity的UGUI或UI Toolkit中构建一个滚动视图动态生成这些缩略图供用户预览和确认。用户确认后再加载选中项的全分辨率纹理。这能提供完全可控的UI体验但代价是开发复杂度显著增加且需要自己处理大量图片的内存管理。6.2 视频文件的处理Native Gallery也支持视频。SaveVideoToGallery和GetVideoFromGallery的用法与图片类似。但需要注意视频格式不同设备支持的视频编码格式不同如H.264, HEVC。保存时尽量使用广泛兼容的格式。文件大小视频文件更大读写更耗时。处理视频时进度反馈和异步操作尤为重要。缩略图生成对于选中的视频你可能需要生成第一帧作为预览图。这可以通过UnityEngine.Video命名空间下的VideoPlayer组件来实现或者寻求其他专门处理视频帧的插件。6.3 与Unity新的媒体APIMobile Media Picker结合从Unity 2021.2开始Unity推出了实验性的UnityEngine.Media命名空间提供了MediaPicker等类旨在提供跨平台的媒体访问。截至我撰写本文时它的功能和稳定性可能还不及成熟的第三方插件如Native Gallery。但值得关注其发展。一个前瞻性的架构可以是用Native Gallery作为当前的主力方案同时抽象出一个“媒体访问接口”未来可以相对平滑地切换到官方的方案如果它成熟起来降低迁移成本。6.4 权限管理的模块化设计不要将权限检查代码散落在各个功能按钮的点击事件里。设计一个PermissionManager单例或服务类负责应用启动时检查必要的权限状态。提供统一的RequestPermissionAsync方法。监听权限变化Android的OnRequestPermissionsResult需要转发到Unity。提供方法引导用户跳转到应用设置页面。 这样能使代码更清晰也便于后续维护和扩展。配置Native Gallery的过程就像是在Unity的便捷世界和移动端原生系统的复杂世界之间架设一座坚固的桥梁。桥的蓝图插件已经给你了但打地基环境配置、架桥墩平台设置、应对不同地质系统版本差异这些活需要你亲自把关。这份指南里的每一个步骤和警告几乎都对应着我或我团队曾经遇到过的真实问题。特别是Android的权限演变和Gradle依赖冲突这两个地方最容易让新手卡上半天。最后分享一个我自己的习惯对于任何涉及原生交互的插件在项目里建立一个“PluginsTest”场景把所有核心API保存、选择、权限检查做成简单的按钮放在场景里。在真机测试阶段第一件事就是跑通这个场景确保基础功能在目标设备上正常工作。这比在复杂的游戏逻辑里埋点调试要高效得多。当这座“桥”稳固了你的应用与手机相册的交互之路才会真正畅通无阻。