Unity安卓打包权限全解析：从AndroidManifest到运行时申请避坑指南-平芜编程栈

1. 项目概述：为什么Unity安卓打包的权限问题如此棘手？

最近在社区里看到不少朋友，尤其是刚接触Unity移动端开发的同学，都在抱怨同一个问题：明明在Unity编辑器里跑得好好的，怎么一打包成安卓APK，游戏就各种“罢工”？要么是存档文件写不进去，要么是读取不到配置文件，要么是访问外部资源时直接崩溃。折腾半天，最后发现十有八九是栽在了“文件权限”这个坑里。这确实是个老生常谈但又常谈常新的问题，尤其是在Android系统权限模型不断收紧的背景下，2024年的今天，很多几年前的“解决方案”可能已经失效，或者引入了新的兼容性问题。

我自己在最近的一个跨平台项目中，就花了整整两天时间跟安卓的文件权限“斗智斗勇”。从AndroidManifest.xml的配置，到运行时动态权限申请的逻辑，再到不同Android版本（特别是Android 10/11的Scoped Storage和Android 13的细粒度权限）下的适配，每一步都可能有“惊喜”。这篇文章，就是把我踩过的坑、验证过的有效方案，以及一些容易忽略的细节，系统地梳理出来。无论你是正在为权限问题头疼的开发者，还是想提前避坑的学习者，希望这篇基于2024年最新环境和Unity版本（以Unity 2022 LTS为例）的实测指南，能帮你节省大量排查时间。

2. 核心思路拆解：理解Android权限模型是避坑的第一步

在动手改代码之前，我们必须先搞清楚Unity在打包安卓时，文件权限管理的“底层逻辑”是什么。很多问题之所以复杂，是因为我们混淆了“安装时权限”、“运行时权限”和“文件系统访问范围”这几个概念。

2.1 安装时权限（Declared Permissions） vs. 运行时权限（Runtime Permissions）

这是最容易混淆的一对概念。简单来说：

安装时权限：在AndroidManifest.xml文件中通过``标签声明的权限。这些权限在用户安装APK时，会在应用商店的安装页面以列表形式展示（对于旧版本Android），或者只是告知系统“我这个应用可能需要这些能力”。从Android 6.0（API 23）开始，这里声明的危险权限并不会在安装时自动授予，而需要我们在应用运行时动态申请。
运行时权限：特指那些被归类为“危险权限”（Dangerous Permission）的权限，例如读写外部存储、访问相机、录音等。这些权限必须由应用在运行时（通常是需要用到该功能的前一刻）弹出系统对话框，由用户手动点击“允许”才能获得。

对于文件操作，最相关的就是READ_EXTERNAL_STORAGE和WRITE_EXTERNAL_STORAGE这两个危险权限。一个关键认知是：即使在AndroidManifest.xml里声明了它们，也只是拿到了“申请资格”，真正的读写能力，必须经过用户同意才能生效。

2.2 Android文件存储空间演变：重点在“外部存储”

Unity中我们常用的文件路径，比如Application.persistentDataPath，在安卓平台下具体指向哪里？这直接决定了我们需要申请什么权限。

内部存储（Internal Storage）：每个应用私有的目录，路径类似于/data/data/<package_name>/。应用无需任何权限即可在此目录下自由读写文件，且其他应用和用户无法直接访问（除非设备已Root）。Application.persistentDataPath在Android上默认就指向这里的一个子目录（如files）。所以，如果你的文件只存在这里，那么恭喜你，根本不需要处理本文讨论的权限问题。
外部存储（External Storage）：这是“坑”最多的地方。它通常指设备的共享存储空间（如手机的“内部存储/机身存储”，不是SD卡）。外部存储又分为：
- 应用私有外部存储（App-specific external storage）：位于外部存储中一个以你应用包名命名的专属目录（如Android/data/<package_name>/）。从Android 4.4开始，应用在自己的这个私有目录下读写，也不需要WRITE_EXTERNAL_STORAGE权限。Unity的Application.persistentDataPath在某些旧版本或特定配置下，可能会指向这里，但现在更倾向于指向内部存储。
- 共享外部存储（Shared external storage）：就是用户常见的/storage/emulated/0/DCIM,/storage/emulated/0/Download等目录。只要你想访问这些共享区域，就必须申请并获取对应的运行时权限。

问题的复杂性在于，我们常常会使用一些插件或代码去访问共享外部存储（比如让用户选择图片、导出日志到下载目录、读取公共文件夹的音乐等），但却没有正确配置和申请权限。

2.3 Unity的权限处理机制：自动生成与手动覆盖

Unity在打包APK时，会自动生成一个基础的AndroidManifest.xml文件。它会根据你在Player Settings里的一些选项（比如勾选Internet Access）自动添加部分权限。但对于文件权限，Unity的自动处理是保守且可能不完整的。

例如，如果你在脚本中使用了System.IO命名空间下的File.ReadAllText去尝试读取一个绝对路径（如/storage/emulated/0/Download/test.txt），Unity的打包过程不会自动帮你把READ_EXTERNAL_STORAGE权限加到Manifest里。这就导致了“编辑器正常，打包后崩溃”的典型症状——因为权限根本没声明。

因此，我们的核心思路就是：手动接管关键权限的声明和申请流程，确保覆盖所有可能的文件访问场景，并适配不同Android版本的要求。

3. 实操全流程：从配置到代码的完整避坑方案

下面，我将按照一个完整的流程，从项目配置到代码编写，一步步说明如何正确设置。

3.1 第一步：创建并配置自定义的 AndroidManifest.xml

这是所有工作的基础。你不能依赖Unity自动生成的那个。

定位模板文件：在你的Unity安装目录下（例如C:\Program Files\Unity\Hub\Editor\2022.3.20f1\Editor\Data\PlaybackEngines\AndroidPlayer），找到Apk子目录。里面有一个AndroidManifest.xml文件，这就是Unity使用的默认模板。把它复制出来。
放入项目：在你的Unity项目Assets目录下，创建（或已有）一个名为Plugins/Android的文件夹。将复制出来的AndroidManifest.xml文件粘贴进去。
编辑权限声明：用任何文本编辑器打开这个文件。找到``标签内部。你需要添加或确认以下权限：

<!-- 如果应用需要从共享存储空间读取文件（如用户相册） --> <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" /> <!-- 如果应用需要向共享存储空间写入文件（如保存图片到相册、导出文件到下载目录） --> <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> <!-- 针对 Android 11 (API 30) 及以上，如果需要在所有文件管理权限（MANAGE_EXTERNAL_STORAGE） --> <!-- 注意：此权限审核严格，仅用于真正的文件管理器类应用，上架Google Play需声明用途。普通应用应避免使用。 --> <!-- <uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" /> --> <!-- 从 Android 10 (API 29) 开始，为了兼容Scoped Storage，即使申请了读写权限，默认也无法访问媒体文件。需要添加以下属性 --> <application ... android:requestLegacyExternalStorage="true" <!-- 关键！用于在Android 10上暂时禁用Scoped Storage，争取适配时间 --> >

重要提示：android:requestLegacyExternalStorage="true"这个属性是Android 10/11兼容性的关键。但它从Android 11（API 30）开始逐渐失效，对于以API 30+为目标的应用，Google Play会有警告。对于新项目，长远之计是必须适配Scoped Storage，使用MediaStoreAPI或Storage Access Framework。但这属于更进阶的内容，本文聚焦于让应用先跑起来。设置这个属性可以为你争取时间。

3.2 第二步：处理 Android 13+ 的细粒度媒体权限

Android 13引入了更细分的媒体权限。以前一个READ_EXTERNAL_STORAGE就能读所有媒体文件，现在不行了。

如果你的应用需要读取用户的图片、视频、音频文件，在AndroidManifest.xml中，应该用新的细分权限替换旧的READ_EXTERNAL_STORAGE：

<!-- 替换或补充旧的 READ_EXTERNAL_STORAGE --> <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" /> <uses-permission android:name="android.permission.READ_MEDIA_VIDEO" /> <uses-permission android:name="android.permission.READ_MEDIA_AUDIO" /> <!-- 如果仍需要访问非媒体类文件（如PDF、TXT），或需要写入，则仍需保留以下 --> <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" /> <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="32" />

注意android:maxSdkVersion="32"，这表示这些旧权限只对Android 12L（API 32）及以下的设备生效。对于Android 13+的设备，系统会忽略它们，转而使用上面的细分媒体权限。这是Google推荐的做法。

3.3 第三步：编写C#运行时权限申请脚本

权限声明好了，接下来就是在游戏运行时动态申请。我们需要一个脚本来管理这一切。

using System.Collections; using System.Collections.Generic; using UnityEngine; using UnityEngine.Android; // 引入Unity的Android权限工具类 using System.IO; public class AndroidPermissionManager : MonoBehaviour { // 定义你需要申请的权限列表 private readonly string[] permissions = { // 根据你的Manifest配置和Target API Level动态决定 // 示例：同时申请旧版和细分权限，系统会根据API级别处理 Permission.ExternalStorageRead, Permission.ExternalStorageWrite, // Android 13+ 的细分权限 "android.permission.READ_MEDIA_IMAGES", "android.permission.READ_MEDIA_VIDEO", "android.permission.READ_MEDIA_AUDIO" }; IEnumerator Start() { // 等待几帧，确保游戏初始化完成 yield return new WaitForEndOfFrame(); // 检查并申请所有必要的权限 foreach (string perm in permissions) { // 使用Unity封装的Permission类进行检查和申请 if (!Permission.HasUserAuthorizedPermission(perm)) { Debug.Log($"申请权限: {perm}"); Permission.RequestUserPermission(perm); // 重要：在移动端，尤其是Android，申请权限是异步的，且会弹出系统对话框。 // 这里不能立即检查结果，需要等待用户操作。 // 一个简单的做法是，在关键操作前再检查权限，或者设置一个“权限检查点”场景。 yield return new WaitForSeconds(0.5f); // 给对话框弹出留点时间 } else { Debug.Log($"权限已授予: {perm}"); } } // 所有权限请求发出后，可以进入下一步，但实际文件操作前仍需验证 Debug.Log("权限申请流程已发起。"); } // 一个在需要进行文件操作前调用的检查方法 public static bool CheckStoragePermission() { // 针对Android 13+，优先检查细分权限 if (CheckPermissionForAndroid13Plus()) { return true; } // 针对旧版本，检查传统权限 else if (Permission.HasUserAuthorizedPermission(Permission.ExternalStorageRead) && Permission.HasUserAuthorizedPermission(Permission.ExternalStorageWrite)) { return true; } return false; } private static bool CheckPermissionForAndroid13Plus() { #if UNITY_ANDROID && UNITY_2022_2_OR_NEWER // 简化的检查逻辑：如果你的应用只关心媒体文件，可以这样检查。 // 实际应根据应用具体访问的文件类型来检查对应的权限。 if (Permission.HasUserAuthorizedPermission("android.permission.READ_MEDIA_IMAGES")) { return true; } #endif return false; } // 示例：一个安全的文件写入方法 public void SafeWriteToPublicDownload(string filename, string content) { if (!CheckStoragePermission()) { Debug.LogError("没有文件存储权限，无法执行写入操作！"); // 这里可以触发UI提示，引导用户去设置页开启权限 ShowPermissionDeniedDialog(); return; } try { // 获取安卓的公共下载目录路径 string downloadPath = GetAndroidPublicDownloadPath(); string fullPath = Path.Combine(downloadPath, filename); File.WriteAllText(fullPath, content); Debug.Log($"文件已成功写入: {fullPath}"); } catch (System.Exception e) { Debug.LogError($"写入文件失败: {e.Message}"); // 即使有权限，在Android 11+的Scoped Storage下，直接写共享目录也可能失败。 // 此时应考虑使用MediaStore API或SAF（Storage Access Framework）。 } } private string GetAndroidPublicDownloadPath() { // 注意：此方法在Android 10+上可能无法直接访问。 // 仅作为示例，实际生产环境应使用更兼容的方法。 return "/storage/emulated/0/Download"; } private void ShowPermissionDeniedDialog() { // 实现一个UI弹窗，告知用户权限不足，并提供跳转系统设置页的按钮 // 可以使用Unity的NativeDialog插件，或自己调用Android原生API Debug.Log("请提示用户去应用设置中开启存储权限。"); } }

3.4 第四步：Player Settings 关键配置

回到Unity编辑器，打开File -> Build Settings -> Player Settings...。

Other Settings 区域:
- Minimum API Level: 根据你的用户群体设置。如果要支持Android 13的细分权限，Target API Level至少需要设置为33。但Minimum可以设低一些，如API 23（Android 6.0）。
- Target API Level:强烈建议设置为你要支持的最高版本（如API 34对应Android 14）。设为最新可以让Unity应用最新的行为变更（如Scoped Storage）。如果设低，系统会以“兼容模式”运行，可能掩盖一些权限问题，但不利于应用上架和长期兼容。
Publishing Settings 区域:
- 确保Custom Main Manifest和Custom Main Gradle Template等选项没有被误勾选，除非你确实提供了自定义文件。我们已经在Plugins/Android下放了AndroidManifest.xml，Unity会自动使用它。

4. 深度避坑与疑难排查

即使按照上述步骤操作，你可能还是会遇到一些奇怪的问题。下面是我总结的几个高频“坑点”和解决方案。

4.1 坑点一：Permission.HasUserAuthorizedPermission 在编辑器下总是返回True

这是最常见的困惑之一。在Unity编辑器中运行游戏，无论你怎么测试，Permission.HasUserAuthorizedPermission检查存储权限几乎总是返回true。这是因为编辑器环境并没有真正的Android权限系统。

避坑技巧：永远不要依赖编辑器环境的权限检查结果。测试权限逻辑的正确性，必须在真机或安卓模拟器上打包测试。你可以通过#if !UNITY_EDITOR预处理指令来包裹关键的权限申请和检查代码，避免在编辑器下干扰你的调试。

4.2 坑点二：Android 10/11 (API 29/30) 上，有权限也无法写入共享目录

这就是前面提到的Scoped Storage的影响。即使你申请并获得了WRITE_EXTERNAL_STORAGE权限，在Android 10及以上版本，应用默认也无法直接通过File.WriteAllText向/storage/emulated/0/Download这样的共享路径写文件。系统会抛出UnauthorizedAccessException。

解决方案：

临时方案（不推荐长期）：在AndroidManifest.xml的``标签中设置android:requestLegacyExternalStorage="true"。这能让应用在Android 10（API 29）和针对旧版SDK（targetSdkVersion < 30）构建时，暂时绕过Scoped Storage限制。但记住，以API 30+为目标的应用，此属性在Android 11+上无效，且上架Google Play可能受影响。
正确方案（必须掌握）：
- 使用MediaStoreAPI：如果要保存图片、视频、音频到公共媒体库，应使用Android原生的MediaStoreAPI。这需要通过Unity的AndroidJavaClass/AndroidJavaObject进行交互，或者使用成熟的插件（如NativeFilePicker、SimpleAndroidPermissionsForUnity的扩展功能）。
- 使用Storage Access Framework：如果要让用户选择保存位置（如下载目录、文档目录），应该使用SAF。通过Intent.ACTION_CREATE_DOCUMENT或Intent.ACTION_OPEN_DOCUMENT启动一个系统文件选择器，让用户自己指定保存位置，然后通过返回的URI进行读写。这是Android官方推荐的、向前兼容的方式。

4.3 坑点三：权限申请对话框不弹出，或者只弹出一次

不弹出：首先检查AndroidManifest.xml是否正确放置在Assets/Plugins/Android下，并且权限声明无误。其次，确保你的Target API Level设置正确。最后，在真机上检查“应用信息 -> 权限”，看看权限列表里是否有你声明的项。如果根本没有，说明Manifest没被正确合并。
只弹出一次：这是Android系统的设计。如果用户点击了“拒绝”，下次再调用Permission.RequestUserPermission，系统可能不会再次弹出对话框，而是直接返回“拒绝”的结果。此时，你需要引导用户手动到系统设置页为你的应用开启权限。你的应用应该有一个友好的提示界面，并调用以下代码打开设置页：

// 打开当前应用的系统设置页面 Application.OpenURL("package:" + Application.identifier);

4.4 坑点四：不同Unity版本和构建系统的差异

Unity的安卓构建系统从旧的Internal（内部）到Gradle，再到现在的Gradle或Gradle (Unity as a Library)，处理Manifest和资源的方式可能有细微差别。

使用Gradle构建系统：这是当前推荐的方式。当你使用Gradle时，Unity会将你的自定义AndroidManifest.xml与它自动生成的内容进行合并。如果合并失败或冲突，可能会导致权限丢失。务必检查打包日志（Build窗口），看是否有关于Manifest合并的警告或错误。
如果遇到合并冲突：你可能需要创建一个AndroidManifest.xml的合并规则文件（merge.xml），或者检查你的Manifest中是否有重复或冲突的属性（比如定义了两次``）。

4.5 坑点五：第三方插件引入的权限问题

很多Asset Store上的插件（尤其是涉及文件访问、相机、麦克风的）会在它们自己的AndroidManifest.xml中声明权限。当Unity打包时，它会将所有插件的Manifest与主Manifest合并。

问题：插件声明的权限可能过于宽泛（比如申请了所有权限），或者与你自定义的Manifest冲突。
排查：在打出的APK包上右键，用压缩软件打开，找到AndroidManifest.xml文件，用文本编辑器查看。这是最终合并后的结果。检查里面是否包含了你期望的权限，以及是否有你不想要的权限。
解决：如果插件声明了不必要的权限，你可以尝试找到插件自带的Manifest文件（通常在插件的Android文件夹里），修改或删除其中的权限声明。但要注意，这可能会影响插件功能。

5. 2024年实测有效的检查清单

在你打包APK并测试之前，对照这个清单快速过一遍：

[ ]Manifest文件：自定义的AndroidManifest.xml是否已放入Assets/Plugins/Android/？
[ ]权限声明：Manifest中是否已正确声明READ_EXTERNAL_STORAGE、WRITE_EXTERNAL_STORAGE或Android 13+的细分媒体权限？
[ ]Scoped Storage兼容：如果Target API Level >= 29，是否添加了android:requestLegacyExternalStorage="true"？（仅作为临时过渡方案，需知悉其限制）
[ ]Player Settings：Target API Level是否已设置为预期最高版本（推荐最新）？
[ ]运行时申请：代码中是否在合适的时机（如应用启动后、执行文件操作前）调用了权限申请逻辑？
[ ]真机测试：是否在安卓真机（或模拟器）上进行了测试，而非仅依赖编辑器？
[ ]权限引导：当用户拒绝权限后，是否有UI引导用户前往系统设置页手动开启？
[ ]路径检查：你的文件操作代码是访问Application.persistentDataPath（相对安全），还是硬编码了共享存储路径（需要权限且Android 10+可能失败）？
[ ]插件审查：是否检查了第三方插件可能引入的额外权限或冲突？

6. 总结与个人心得

跟Unity安卓打包的权限问题打交道，感觉就像是在跟一个不断更新规则的守门人博弈。Android系统每年都在收紧权限和隐私政策，这意味着我们开发者的适配工作不能一劳永逸。

我个人的体会是，尽早放弃“直接操作共享存储路径”的旧习惯。对于新项目，在架构设计时就应该把“通过MediaStore或SAF访问公共文件”作为首选方案。虽然学习成本和初期编码复杂度高一些，但这是通往未来版本的唯一稳定通道。android:requestLegacyExternalStorage="true"这根“拐杖”，迟早要被收走。

对于现有老项目的维护，本文提供的方案（正确声明+动态申请+临时兼容属性）能解决大部分燃眉之急，让你快速打出可用的APK。但务必在项目计划中，为“Scoped Storage完全适配”留出足够的技术债偿还时间。

最后一个小技巧：在调试权限相关问题时，善用adb logcat命令。在电脑上连接真机，在命令行运行adb logcat -s Unity，然后在手机上操作你的应用。Unity打印的Debug.Log以及Android系统抛出的权限拒绝异常，都会清晰地显示在这里，比在手机上抓日志方便得多。看到Permission Denial之类的关键字，就能快速定位问题根源。

文件权限虽是小问题，却直接影响应用的核心功能。希望这篇结合了最新环境实测的指南，能帮你填平这些坑，让打包过程更加顺畅。