Unity手游动态更换App图标：Android与iOS双端完整方案

大概率是从某个运营节点或者版本大事件开始的。某天早上产品跑过来跟我说：“咱们 App 图标能不能换个样？春节过了换元宵，上线当天换联名版，最好再做个 A/B 测试看哪个图标点击率高。”你一听，在 Unity 里做手游，换图标不就是动态换张图吗？真动手才发现，Android 和 iOS 两套机制差得十万八千里——Android 靠清单文件里埋活路由，iOS 靠系统私有 API 级别的能力。这篇文章我就把我在 Unity 手游里做动态更换 App 图标的完整思路、代码、坑点全部拆出来，双端方案都会讲到，正在被产品追着要“一个按钮换图标”的兄弟可以直接抄作业。

先说结论：Android 和 iOS 都没有提供“运行期直接改桌面图标文件”的公共 API，所以思路完全不一样。Android 的通行解法是利用activity-alias（活动别名）配合PackageManager动态启停组件，本质上是“给同一个入口换了件马甲”；iOS 则从 10.3 开始提供了setAlternateIconName系统接口，但所有可选图标必须在打包时就塞进 App 里，运行时只是告诉系统“切到预设好的哪一个”。理解了这两条主线，后面所有的配置和代码就都顺了。

1. Android 端的正统解法：Activity-alias 与组件启停

1.1 为什么是 activity-alias 而不是“直接换一张图”

我一开始也想简单，在 C# 里拿到 Application 的 icon 路径，然后把图标文件替换掉、再通知 Launcher 刷新，事实证明这条路走不通。Android 桌面图标并不是读你磁盘里的某个 PNG 文件，而是 Launcher 通过PackageManager查询“带 LAUNCHER 入口的组件”，拿到组件里声明的 icon 资源 ID，再绘制到桌面上。也就是说，图标和清单文件里某个入口组件是绑定的，运行期改文件内容不会触发 Launcher 刷新，改了也白改。

社区里从 Android 4.x 时代玩到现在的正统做法，就是activity-alias。你可以理解成：给已经存在的MainActivity多注册几个“透明跳板”，每个跳板有自己的android:icon，默认全部关闭；需要在桌面上显示哪个图标，就通过setComponentEnabledSetting打开对应的跳板、关掉其他的。Launcher 检测到组件启用状态变化后，会自动更新桌面图标。之所以用 alias 而不是新建多个 Activity，是因为你的游戏入口永远只有一个MainActivity实例，alias 只是给它换了套图标和名字，不会引入第二个真实入口，进程状态、启动参数都能保持一致。

1.2 AndroidManifest 完整配置与资源组织

先看清单文件。假设你的主 Activity 是com.yourgame.game.MainActivity，我想加一个春节图标，就声明一个 alias，目标指向同一个 Activity，图标换成@mipmap/icon_spring：

<application android:icon="@mipmap/icon_default" android:label="@string/app_name"> <activity android:name=".MainActivity" android:exported="true" android:configChanges="orientation|screenSize|keyboardHidden"> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter> </activity> <activity-alias android:name=".MainActivityAliasSpring" android:enabled="false" android:exported="true" android:icon="@mipmap/icon_spring" android:label="@string/app_name" android:targetActivity=".MainActivity"> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter> </activity-alias> </application>

几个细节我必须强调：

1. android:enabled="false"是默认关闭状态，否则一装包桌面就会出现两个图标。
2. android:exported="true"是给 Launcher 看的，如果不写或者写成 false，部分厂商桌面会把该入口视为不可启动，导致开关后不刷新。
3. intent-filter必须和主 Activity 保持一致，alias 才会被识别为可启动入口。
4. 每个 alias 的android:name必须全局唯一，我用MainActivityAliasSpring这种带场景后缀的命名，后面用代码开关时不容易写错。

如果你有多套图标，就多复制几段activity-alias，每套对应一个android:icon。资源文件放到Assets/Plugins/Android/res/mipmap-*下，对应 mdpi、hdpi、xhdpi、xxhdpi、xxxhdpi 五档。需要注意的是，Unity 工程里默认用的是AndroidManifest.xml和res目录，如果你用的是mainTemplate.gradle方式，清单文件的路径在Assets/Plugins/Android/AndroidManifest.xml，图标资源建议直接丢到同目录的res下，构建时 Gradle 会自动合并进 APK。

1.3 Unity C# 侧调用 PackageManager 的完整封装

配置好清单之后，运行时的核心就一句：通过PackageManager.setComponentEnabledSetting把目标 alias 设为启用、把其他入口设为禁用。在 Unity C# 里调 Android API，需要借助AndroidJavaObject和AndroidJavaClass。

我封装了一个可直接拷走的工具类：

using UnityEngine; public static class AndroidIconManager { private const int COMPONENT_ENABLED_STATE_ENABLED = 1; private const int COMPONENT_ENABLED_STATE_DISABLED = 2; private const int DONT_KILL_APP = 1; public static void SwitchToAlias(string fullAliasName) { using (var unityPlayer = new AndroidJavaClass("com.unity3d.player.UnityPlayer")) using (var activity = unityPlayer.CallStatic<AndroidJavaObject>("currentActivity")) using (var pm = activity.Call<AndroidJavaObject>("getPackageManager")) { AndroidJavaObject component; // 注意：第二个参数是完整的组件名，前面带包名 component = new AndroidJavaObject( "android.content.ComponentName", activity, fullAliasName ); pm.Call("setComponentEnabledSetting", component, COMPONENT_ENABLED_STATE_ENABLED, DONT_KILL_APP); } } public static void SwitchToDefaultIcon() { string packageName = Application.identifier; SwitchToAlias(packageName + ".MainActivity"); } }

这里有几个坑要特别说明：

• fullAliasName必须是带包名的完整形式，比如com.yourgame.game.MainActivityAliasSpring，你可以从Application.identifier拼出来，也可以把包名和别名用常量管理。
• 第三个参数flags我传了DONT_KILL_APP。这个标志位表示“切换组件时不要杀掉当前进程”，对游戏来说特别关键——如果没有它，你切个图标可能整个进程被系统强制重启，玩家直接闪退。
• 切到默认图标时，要把主 Activity 显式置为ENABLED而不是DEFAULT。Android 的组件状态有默认、启用、禁用三种，如果不小心把主 Activity 设置成了禁用而忘记恢复，结果是应用彻底无法启动，这在线上是非常严重的事故。

2. Android 的兼容性深水区：每个人都会撞上的三个坑

2.1 Android 11 包可见性：不配置 queries 就白干

动态换图标这功能我最早在 Android 9 上跑通，当时一切正常，后来把测试机换到 Android 11，代码没变，图标却怎么都切不过去。排查到最后发现，问题出在 Android 11 引入的“包可见性”机制。

Android 11 开始，应用默认只能看到自己和少数系统组件，查询其他应用信息会受到限制。虽然你开关的是自己包里的组件，但某些厂商系统在PackageManager查询 LAUNCHER 入口时行为很诡异，如果清单里没有声明queries，查询结果会返回空，Launcher 压根不知道你有这个 alias。解决办法是在AndroidManifest.xml的manifest节点下加一段：

<queries> <intent> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent> </queries>

这段声明告诉系统：我需要查询具有 MAIN/LAUNCHER 属性的组件。加上之后，Android 11 和 12 的设备都能正常切换了。建议无论目标版本是多少，都提前加上，成本为零但能避免一次线上事故。

2.2 厂商桌面图标缓存与快捷方式残留

如果你只在 Pixel 和三星上测过，会觉得这功能还挺稳。一旦放到国产厂商系统上，就有意思了。

我实测过的设备里，MIUI 和部分 ColorOS 机型在切换后，桌面图标并不会立刻变化，有的要等几秒，有的要等锁屏再解锁才刷新，还有的会短暂出现“新图标和旧图标重叠”的视觉效果。原因很简单：厂商桌面普遍有自己的图标缓存，在自定义 Launcher 的机型上，图标刷新的时机由厂商桌面自己决定，不一定响应系统的组件状态广播。

最实用的处理办法是把切换时机放在冷启动流程里。游戏启动时先显示自己的 Splash 或 Loading 界面，在这个阶段调用切图标逻辑，哪怕桌面暂时没刷新，玩家也不会有明显感知。等玩家切回桌面时，图标大概率已经更新完毕。另外我还在部分机型上发现，切换图标后旧图标会残留在“最近任务”里，这个是系统层面的缓存，应用层基本没办法清理，不建议在这上面花时间。

2.3 切回主图标时的组件顺序问题

第三个坑非常隐蔽，也是我线上踩过最疼的一次：运营活动结束后，客户端收到服务器指令切回默认图标，结果部分 Android 设备桌面上出现了两个应用图标。

排查过程是这样的：正常切换逻辑是“先禁用旧入口，再启用新入口”，但如果这两个操作之间进程被杀，或者某个机型对setComponentEnabledSetting的生效不是同步返回，就可能出现“旧的还没禁用掉，新的已经启用了”的中间态，Launcher 一扫描，两个入口同时有效，桌面就多了一个图标。

我的解决思路是调整状态设置顺序：先启用目标入口，再禁用其他入口，然后立刻读一次目标入口的启用状态做校验；同时基于DONT_KILL_APP保证操作过程中进程不死。另外，所有入口都要有一个统一的开关管理器，不要在业务代码里散落SwitchToAlias调用。我封装时维护了一个静态字典，记录所有 alias 的完整名称，切任何图标都是“全量重置”，不是“增量修改”，从根上避免状态错乱。

3. iOS 端的系统级方案：setAlternateIconName 与 Info.plist 配置

3.1 API 原理理解：图标切换是系统行为

如果说 Android 是“手动改路由”，那 iOS 就是“请系统帮忙”。iOS 直到 10.3 才开放了UIApplication的setAlternateIconName:(nullable NSString *)alternateIconName completionHandler:接口，这是目前唯一公开支持的动态换图标方式。

要注意的是，这个 API 并不是让你“传一张任意图片进去”，而是让你传一个在Info.plist里预先声明好的图标标识符。所有可切换的图标必须在 App 打包时就放进Assets.xcassets，并登记到Info.plist的CFBundleAlternateIcons字段里。运行时调用切换接口后，系统会自动完成图标替换，并弹窗询问用户“是否更换主屏幕图标”，这个弹窗不可跳过，也不需要申请任何权限。

所以 iOS 端的核心工作分两块：一是打包配置（plist + xcassets），二是运行时调用 API 并处理回调。配置错了或者图标标识符传错了，系统回调里会返回错误，但不会崩溃。

3.2 Info.plist 与 Asset Catalog 的配置细节

先看Info.plist。我以春节图标为例，标识符用SpringIcon：

<key>CFBundleIcons</key> <dict> <key>CFBundleAlternateIcons</key> <dict> <key>SpringIcon</key> <dict> <key>CFBundleIconFiles</key> <array> <string>AppIconSpring</string> </array> <key>UIPrerenderedIcon</key> <false/> </dict> </dict> </dict>

里面SpringIcon是代码里要传的标识符，AppIconSpring是对应 Asset Catalog 里的图片集名称。注意不要搞反：API 传的是外层 key，也就是SpringIcon，而不是AppIconSpring。

再看 xcassets 的组织方式。在Assets.xcassets里新建一个App Icon类型的图片集，命名为AppIconSpring，里面按 iPhone 的图标规格放图片：

• 60x60 pt 对应 120x120 @2x 和 180x180 @3x；
• 让Contents.json生成正确的idiom、size、scale三元组。

最简单的方式是用 Xcode 新建图标集后直接拖图，但 Unity 开发者没有 Xcode 也不怕，手动创建目录加Contents.json完全可以，模板长这样：

{ "images" : [ { "filename" : "AppIconSpring_120.png", "idiom" : "iphone", "size" : "60x60", "scale" : "2x" }, { "filename" : "AppIconSpring_180.png", "idiom" : "iphone", "size" : "60x60", "scale" : "3x" } ], "info" : { "author" : "xcode", "version" : 1 } }

图标背景建议不要用带 alpha 的透明 PNG，苹果渲染时会把透明区域显示成黑色，这是很多第一次做换图标的人会踩的坑。

3.3 必须知道的六条限制

iOS 端的坑不像 Android 那么多，但每一条都绕不开，我列成清单：

1. 系统版本限制：只有 iOS 10.3+ 支持。低于这个版本的系统调用无效果，需要在 C# 里先做版本判断。
2. 弹窗不可跳过：切换时系统会弹“是否更换应用图标”的确认框，用户体验上会有一次打扰，需要产品提前知晓。游戏场景建议先通过自己的 UI 说明“即将更新桌面图标”，再触发系统弹窗。
3. 同一个会话内不能反复切换：Activity 把一个图标切到 A 之后，立刻切回默认图标，或者再次切 A，系统回调会返回错误。实际测试中，短时间内连切多次还会触发系统限频。稳妥做法是每次冷启动最多切换一次，业务层做节流。
4. 图标必须打包在 App 内：这是最硬的一条限制。别想着服务器下发一个 zip 解压后切图标，iOS 不允许运行时加载未签名资源作为应用图标。
5. 回调可能有延迟：completionHandler并不保证在主线程、也不保证在某个时间范围内回调。不要在回调里做跟 UI 同步强绑定的逻辑，比如“等回调完了再进游戏主界面”，这样可能会卡住。
6. 审核风险：App Store 审核时，如果发现应用内频繁切换图标，审核员可能询问用途。建议在审核备注里写明这是运营活动的正常需求，并且保证所有图标素材不涉及第三方版权、不包含引导用户做出错误操作的内容。

4. 双端统一管理：服务器下发与客户端调度逻辑

4.1 图标配置协议设计与优先级

客户端能换图标只是第一步，真正做运营时，你不可能每次活动都发版，所以必须让服务器远程下发“当前该用哪套图标”。

我设计的协议非常简单，用一个 JSON 配置：

{ "key": "spring_2024", "iconName": "SpringIcon", "androidAlias": "com.yourgame.game.MainActivityAliasSpring", "iosIconKey": "SpringIcon", "startTs": 1709136000, "endTs": 1711814400, "priority": 10, "channel": "all" }

字段含义解释一下：

• key：配置的唯一标识，用于客户端去重，防止重复切换；
• iconName：运营侧可读的名称，方便排查问题；
• androidAlias和iosIconKey：双端各自需要的入口标识符，客户端按平台取用；
• startTs / endTs：生效时间窗口，时间戳统一用秒；
• priority：优先级。如果同时存在多套配置，数值大的生效。比如“周年庆”和“春节”同时下发时，保证只显示优先级最高的一套；
• channel：渠道白名单，可以按渠道区分，方便灰度验证。

客户端拿到配置后的调度逻辑，我用伪代码写出来：

收到配置后： 1. 先判断平台，Android 取 androidAlias，iOS 取 iosIconKey； 2. 判断当前时间是否在 startTs 和 endTs 之间，不在则忽略； 3. 比较 priority，低于当前生效配置则忽略； 4. 与本地缓存的 last_icon_key 比对，相同则忽略； 5. 调用平台层切换接口； 6. 切换成功后，把 key 写入本地缓存。

这套逻辑看似简单，但下面两个细节需要注意。第一，本地缓存一定不能省，否则玩家每次启动都触发一次切换，在 iOS 上很快就会被系统限频，表现为回调返回错误、图标切换失败。第二，服务器配置一定要带endTs，活动结束后客户端要把图标切回默认，否则活动结束玩家桌面还留着旧图标，是典型的运营事故。

4.2 切换时机与启动闪屏的衔接

我发现很多人忽略一个关键点：图标切换的时机，直接决定玩家能不能感知到“图标变了”。

如果游戏是热启动（进程还在后台），切图标不会及时反映到桌面；如果游戏是冷启动，又急着在 Loading 阶段立刻切，此时 Launcher 可能还没完成桌面刷新，玩家看到 Splash 结束后还是老图标。我的做法是：

1. 冷启动进入游戏、请求远程配置之前，先用本地缓存的配置切一次图标，保证“上次活动还没结束”时，桌面图标是对的；
2. 异步请求服务器拿到最新配置后，如果和本地缓存不同，再切一次；
3. 所有切换动作放在场景加载的黑屏间隙或 Loading 遮罩下面执行，玩家基本无感知。

iOS 端的弹窗问题需要额外处理。前面说过，iOS 切换图标会有系统确认弹窗，如果玩家正在看剧情或操作 UI，突然弹出来很突兀。我的建议是：iOS 端先检测“当前是否存在有效图标配置”，如果需要切换，弹出游戏内确认框解释原因，玩家点击确认后再调用原生 API，把系统弹窗带来的割裂感降到最低。

4.3 Unity Editor 扩展：批量生成双端图标资源

运营给你三四套图标，每套要做 Android 五个分辨率加 iOS 两个分辨率，手工一张张拖进工程，然后手改 Manifest 和 plist，人很容易崩溃。我当时写了一个 Unity Editor 窗口，把重复劳动全部自动化。

原理不复杂，核心就三步：

第一步，在Assets/Plugins/Android/res/下创建mipmap-mdpi、mipmap-hdpi、mipmap-xhdpi、mipmap-xxhdpi、mipmap-xxxhdpi目录，把源图等比缩放到对应尺寸后写进去。Android 的图标尺寸参考：

密度	尺寸
mdpi	48x48
hdpi	72x72
xhdpi	96x96
xxhdpi	144x144
xxxhdpi	192x192

第二步，生成 iOS 的AppIconSpring.appiconset目录和Contents.json，把 120x120 和 180x180 两张图写进去。

第三步，用XmlDocument读写AndroidManifest.xml，自动追加activity-alias节点；用PlistDocument读写Info.plist，自动追加CFBundleAlternateIcons条目。

每次运营提需求，我只要在 Editor 窗口里选择源图、填图标名，再点一次“生成”，资源和配置全部就位，构建验证只需要几秒钟。这个工具不仅省时间，更重要的是避免了手改文件导致的大小写错误、漏配资源等问题。

5. 实测中的诡异问题与双端验收清单

5.1 两起真实的线上案例

先聊两个我实际遇到的线上问题，大家以后遇到类似现象可以直接对号入座。

第一个是 Android 端的“双图标”案例。某次活动上线后，运营反馈有玩家桌面出现了两个游戏图标，一个旧的一个新的。查日志发现，客户端在收到两条配置指令：一条是活动开始的换图标指令，一条是几分钟后的活动预结束指令。两条指令几乎同时到达，第一条执行到一半进程被系统回收，第二条又在恢复时执行了一次，最终“旧 icon 的 alias 没有完全禁用、新 icon 的 alias 已经启用”，桌面自然出现了两个入口。这个问题的根因就是指令乱序和进程被杀导致的中间态，后来我把所有切换操作收敛到同一个函数里，切换前先清掉所有时间窗口外的配置，并加了一层“同 key 三秒内不重复执行”的节流，线上再没出现过双图标。

第二个是 iOS 端的“切了等于没切”案例。有玩家反馈，点了游戏内换图标按钮之后，桌面上确实弹了系统确认框，但点完确认，图标没变，再点一次按钮却提示“切换失败”。查下来发现：玩家第一次点击后，系统弹窗没有立即出现，玩家以为没生效，又连续点了几次，触发了系统限频和“同一图标不能重复设置”的限制，导致回调返回错误。这个问题的处理方式是，在 C# 层做了一个图标状态机：点击按钮之后标记“切换中”，在收到原生回调前不可再次点击，同时在回调返回错误时明确提示玩家“请稍后重试”，而不是静默失败。

5.2 双端验收测试清单

功能上线前，我建议逐项过一遍下面的清单：

Android 侧：

• 冷启动后桌面图标正确切换；
• 热切换图标时进程没有被杀掉（观察DONT_KILL_APP是否生效）；
• 切到默认图标后桌面只有一个入口；
• Android 8、9、10、11、12、13 各选一台设备验证；
• 小米、华为、OPPO、vivo 各测一台，重点看桌面缓存刷新的延迟；
• 按两次“启用”操作，确认不出现双图标。

iOS 侧：

• iOS 12、13、14、15、16 至少各测一台；
• 首次切换时弹窗出现正常；
• 玩家点击“取消”后，游戏状态不受影响；
• 冷启动后连续切换三次，确认第三次回调返回正确错误信息且不崩溃；
• 低内存状态下切换，回调延迟时 UI 不被阻塞。

另外还有一个很不起眼但容易出问题的点：Android 和 iOS 的图标规格不一样，很多团队会让美术出一套图然后两端乱用，结果 Android 的图标在部分机型上被拉得变形，或者 iOS 的图标边角被裁掉。我建议在 Editor 工具里就强制校验尺寸，格式不对直接报错，宁可构建失败也不要带到线上。

最后分享一点个人体会：动态换图标这个需求，从技术难度上不算高，但它牵扯到客户端、服务器、运营配置、双端原生层，是最能体现“全链路思维”的功能之一。我的建议是，第一版不要贪多，Android 先跑通，iOS 再接上，最后再做 server 下发和灰度，分三步走远比一次梭哈稳。希望这篇内容能帮你少踩几个坑。