Unity手游双端动态换图标：Android与iOS实战避坑指南

手游运营到一定阶段，图标这件事迟早会被提上台面。节日活动、版本大版本更新、渠道联运换皮、甚至是给核心玩家做一套"隐藏彩蛋图标"，都绕不开一个需求：不重新发版，让用户桌面上的 App 图标动起来。Android 这边有activity-alias这个老牌方案，iOS 这边从 10.3 开始也开放了setAlternateIconName接口，但真正落到 Unity 工程里，双端一起做的时候，坑远比想象中多。这篇就把我在几个上线项目里踩过的路完整梳理一遍，从原理到代码，从配置到审核，尽量让你少走弯路。

1. 先搞清楚双端图标切换的底层机制差异

很多人一上来就找插件、找现成方案，结果发现 Android 能跑、iOS 死活不生效，或者反过来。根本原因在于两个平台对"换图标"这件事的实现思路完全不同，理解了这个差异，后面所有配置和代码才有落脚点。

1.1 Android 的 activity-alias 到底做了什么

Android 允许一个应用注册多个activity-alias，每个 alias 指向同一个主 Activity，但可以各自声明不同的android:icon和android:label。系统桌面（Launcher）在扫描已安装应用时，会把每个被启用（android:enabled="true"）的 alias 都当成一个独立入口显示出来。所以"换图标"的本质，其实是启用目标 alias、禁用当前 alias，让 Launcher 重新读取组件列表。

这里有个关键点：同一时刻只能有一个 alias 处于启用状态，否则桌面上会出现多个图标。切换动作通过PackageManager.setComponentEnabledSetting()完成，这个操作是异步生效的，Launcher 收到PACKAGE_CHANGED广播后刷新。实测在大部分国产 ROM 上，切换后图标会在 1 到 3 秒内刷新，个别 ROM 需要用户手动触发一次桌面重绘（比如滑动一下）。

另一个容易忽略的点：主 Activity 本身如果也声明了android:icon，它和 alias 会同时存在。正确做法是把主 Activity 的android:enabled设为false，或者干脆不给主 Activity 配 icon，只让 alias 对外暴露。我一般推荐后者，结构更干净。

1.2 iOS 的 alternate icon 是另一套逻辑

iOS 从 10.3 起支持UIApplication.shared.setAlternateIconName(_:completionHandler:)，但它和 Android 完全不是一回事。iOS 的备用图标必须在打包时全部预置进 App Bundle，运行时只能在这些预置图标之间切换，不能动态下载新图标。也就是说，你想换的每一套图标，都得在发版前就塞进工程里。

图标文件放在工程目录下，命名规则是<PrimaryIconName>@2x.png、@3x.png这种，同时在Info.plist里通过CFBundleIcons→CFBundleAlternateIcons声明。切换时传入的alternateIconName就是你在 plist 里定义的 key。传nil表示切回主图标。

还有个体验上的坑：调用setAlternateIconName时，系统会弹一个"您已更改 App 图标"的提示框，这个提示框无法通过公开 API 去掉。网上有些取巧做法（比如在切换瞬间临时替换 keyWindow 的 rootViewController），但风险高、审核容易被拒，我后面会专门讲。

1.3 两端机制对比一览

这张表建议贴在工位上，每次做需求前对一遍，能省掉大量"为什么 iOS 不能像 Android 那样动态加图标"的无效沟通。

2. Unity 工程侧的 Android 配置落地

Unity 打包 Android 时，AndroidManifest.xml是自动生成的，直接改生成物没意义，下次打包就被覆盖。正确姿势是在Assets/Plugins/Android/下放一份自定义 Manifest，让 Unity 做合并。

2.1 自定义 AndroidManifest 的正确写法

在Assets/Plugins/Android/AndroidManifest.xml里，你需要声明主 Activity 和若干 alias。下面是我常用的模板结构：

<application android:label="@string/app_name" android:icon="@mipmap/app_icon_default"> <activity android:name="com.unity3d.player.UnityPlayerActivity" android:exported="true" android:enabled="false"> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter> </activity> <activity-alias android:name=".icon_default" android:targetActivity="com.unity3d.player.UnityPlayerActivity" android:enabled="true" android:exported="true" android:icon="@mipmap/app_icon_default" android:label="@string/app_name"> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter> </activity-alias> <activity-alias android:name=".icon_christmas" android:targetActivity="com.unity3d.player.UnityPlayerActivity" android:enabled="false" android:exported="true" android:icon="@mipmap/app_icon_christmas" android:label="@string/app_name"> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter> </activity-alias> </application>

几个必须注意的细节：android:exported在 Android 12 之后是强制要求的，漏了会直接编译失败；targetActivity必须写全限定名；每个 alias 的intent-filter必须和主 Activity 一致，否则桌面不认。图标资源放在Assets/Plugins/Android/res/mipmap-xxxhdpi/等对应目录下，Unity 会一起打进包。

2.2 图标资源目录与命名规范

Android 的 mipmap 目录按密度分：mipmap-mdpi、hdpi、xhdpi、xxhdpi、xxxhdpi。一套图标至少要覆盖xxhdpi和xxxhdpi，否则在高分屏上会糊。命名建议统一前缀，比如app_icon_default、app_icon_christmas、app_icon_newyear，方便脚本批量生成 Manifest。

我一般会写一个 Editor 脚本，读取一个图标配置表（ScriptableObject 或 JSON），自动生成 Manifest 里的 alias 段落。这样运营加一套新图标，只需要往配置表里加一行、丢两张图，重新打包即可，不用手改 XML。这个脚本大概长这样：

[MenuItem("Tools/Generate Icon Aliases")] static void GenerateAliases() { var config = AssetDatabase.LoadAssetAtPath<IconConfig>("Assets/IconConfig.asset"); var sb = new StringBuilder(); foreach (var icon in config.icons) { sb.AppendLine($"<activity-alias android:name=\".icon_{icon.key}\""); sb.AppendLine($" android:targetActivity=\"com.unity3d.player.UnityPlayerActivity\""); sb.AppendLine($" android:enabled=\"{(icon.isDefault ? "true" : "false")}\""); sb.AppendLine($" android:exported=\"true\""); sb.AppendLine($" android:icon=\"@mipmap/{icon.resName}\""); sb.AppendLine($" android:label=\"@string/app_name\">"); sb.AppendLine(" <intent-filter>"); sb.AppendLine(" <action android:name=\"android.intent.action.MAIN\" />"); sb.AppendLine(" <category android:name=\"android.intent.category.LAUNCHER\" />"); sb.AppendLine(" </intent-filter>"); sb.AppendLine("</activity-alias>"); } File.WriteAllText("Assets/Plugins/Android/aliases.xml", sb.ToString()); }

生成后手动贴进主 Manifest，或者用 Manifest 合并的占位符机制自动注入，看团队习惯。

2.3 运行时切换的 C# 封装

Unity 侧调用 Android 的PackageManager需要走AndroidJavaObject。核心代码如下：

public static void SwitchIcon(string aliasKey) { #if UNITY_ANDROID && !UNITY_EDITOR var context = new AndroidJavaClass("com.unity3d.player.UnityPlayer") .GetStatic<AndroidJavaObject>("currentActivity"); var pm = context.Call<AndroidJavaObject>("getPackageManager"); var pkgName = context.Call<string>("getPackageName"); // 先禁用所有 alias foreach (var key in AllIconKeys) { var comp = new AndroidJavaObject("android.content.ComponentName", pkgName, pkgName + ".icon_" + key); pm.Call("setComponentEnabledSetting", comp, 2, 1); // 2=DISABLED, 1=DONT_KILL_APP } // 启用目标 alias var target = new AndroidJavaObject("android.content.ComponentName", pkgName, pkgName + ".icon_" + aliasKey); pm.Call("setComponentEnabledSetting", target, 1, 1); // 1=ENABLED #endif }

setComponentEnabledSetting的第三个参数DONT_KILL_APP很关键，不加的话切换瞬间应用会被系统杀掉，用户体验极差。另外这个操作要在主线程调用，Unity 里直接调没问题，但如果你在子线程做逻辑，记得切回主线程。

注意：部分国产 ROM（尤其是定制较深的系统）对 alias 切换有缓存，切换后可能需要调用一次pm.Call("getInstalledPackages", 0)之类的操作触发刷新，或者干脆提示用户"图标将在几秒内更新"。别指望所有机型都秒切。

3. iOS 端备用图标的工程配置与调用

iOS 这边的复杂度主要在工程配置，代码反而简单。但正因为配置繁琐，很多 Unity 开发者第一次做会卡在"图标不显示"或者"审核被拒"上。

3.1 Info.plist 的 CFBundleIcons 结构

iOS 的备用图标声明分两部分：CFBundleIcons（主图标）和CFBundleAlternateIcons（备用图标）。在 Unity 里，你可以通过 PostProcessBuild 脚本往生成的 Xcode 工程 Info.plist 里注入这些字段，也可以直接在Assets/Plugins/iOS/下放一个 plist 片段做合并。

结构大概是这样：

<key>CFBundleIcons</key> <dict> <key>CFBundlePrimaryIcon</key> <dict> <key>CFBundleIconFiles</key> <array> <string>AppIcon60x60</string> </array> </dict> <key>CFBundleAlternateIcons</key> <dict> <key>christmas</key> <dict> <key>CFBundleIconFiles</key> <array> <string>icon_christmas_60</string> </array> <key>UIPrerenderedIcon</key> <false/> </dict> <key>newyear</key> <dict> <key>CFBundleIconFiles</key> <array> <string>icon_newyear_60</string> </array> <key>UIPrerenderedIcon</key> <false/> </dict> </dict> </dict>

CFBundleIconFiles里填的是图标文件名（不带扩展名），系统会自动找@2x、@3x版本。图标文件要放进 Xcode 工程的资源目录，命名必须严格匹配。比如icon_christmas_60@2x.png（120x120）和icon_christmas_60@3x.png（180x180）。

3.2 图标尺寸与命名对照表

iOS 对备用图标的尺寸要求比主图标宽松一些，但为了显示效果，建议按下面这套来：

命名上我踩过一个坑：如果文件名里带了@2x但实际尺寸不对，Xcode 编译不报错，但运行时图标会显示成空白或者被拉伸。建议用脚本批量校验尺寸，别靠肉眼。

3.3 Unity 调用 iOS 切换接口

iOS 侧需要写一个 Objective-C 的桥接文件，放在Assets/Plugins/iOS/下：

// IconSwitcher.mm #import <UIKit/UIKit.h> extern "C" void _SwitchAppIcon(const char* iconName) { NSString *name = iconName ? [NSString stringWithUTF8String:iconName] : nil; if ([UIApplication sharedApplication].supportsAlternateIcons) { [[UIApplication sharedApplication] setAlternateIconName:name completionHandler:^(NSError * _Nullable error) { if (error) { NSLog(@"Switch icon failed: %@", error.localizedDescription); } }]; } }

C# 侧用DllImport调用：

#if UNITY_IOS && !UNITY_EDITOR [DllImport("__Internal")] private static extern void _SwitchAppIcon(string iconName); public static void SwitchIcon(string iconKey) { _SwitchAppIcon(string.IsNullOrEmpty(iconKey) ? null : iconKey); } #endif

传null或空字符串表示切回主图标。注意supportsAlternateIcons这个判断不能省，虽然 iOS 10.3+ 都支持，但某些企业签名或特殊分发场景下可能返回 false。

3.4 那个绕不开的系统提示框

前面提过，调用setAlternateIconName时系统会弹"您已更改 App 图标"的提示。这个提示框在 iOS 10.3 到现在的所有版本都存在，官方没有提供关闭方式。网上流传的"替换 keyWindow rootViewController"方案，原理是在切换瞬间把 rootViewController 换成一个空的，让系统找不到弹窗的宿主，切换完再换回来。

这个方案我实测过，确实能去掉提示框，但有几个致命问题：一是时机极难把握，稍有不慎就会导致界面白屏或崩溃；二是 App Store 审核指南明确要求不能干扰系统行为，被拒风险很高；三是 iOS 版本更新后随时可能失效。我的建议是老老实实接受这个提示框，把它当成一次正常的用户交互。如果产品实在不能接受，那就别做 iOS 的动态图标，只做 Android。

4. 双端统一接口与状态持久化设计

两端机制不同，但上层业务逻辑应该统一。我一般会封装一个AppIconManager，对外只暴露SwitchTo(string key)和GetCurrentKey()两个方法，内部根据平台分发。

4.1 统一接口的抽象层

public static class AppIconManager { private const string PREF_KEY = "current_app_icon"; public static void SwitchTo(string key) { #if UNITY_ANDROID && !UNITY_EDITOR SwitchAndroid(key); #elif UNITY_IOS && !UNITY_EDITOR SwitchIOS(key); #endif PlayerPrefs.SetString(PREF_KEY, key); PlayerPrefs.Save(); } public static string GetCurrentKey() { return PlayerPrefs.GetString(PREF_KEY, "default"); } }

状态持久化用PlayerPrefs就够了，但要注意：Android 上 alias 的启用状态是系统层面记录的，即使你清了 PlayerPrefs，图标也不会自动切回默认。所以启动时要做一次状态校验：读取 PlayerPrefs 里的 key，和系统当前启用的 alias 对比，不一致就以系统为准（或者以 PlayerPrefs 为准强制同步一次）。我倾向于以系统为准，因为用户可能在设置里手动改过。

4.2 启动时的状态同步逻辑

Android 侧读取当前启用 alias 的方法：

public static string GetCurrentAndroidIcon() { var context = new AndroidJavaClass("com.unity3d.player.UnityPlayer") .GetStatic<AndroidJavaObject>("currentActivity"); var pm = context.Call<AndroidJavaObject>("getPackageManager"); var pkgName = context.Call<string>("getPackageName"); foreach (var key in AllIconKeys) { var comp = new AndroidJavaObject("android.content.ComponentName", pkgName, pkgName + ".icon_" + key); int state = pm.Call<int>("getComponentEnabledSetting", comp); if (state == 1) return key; // ENABLED } return "default"; }

iOS 侧直接读[[UIApplication sharedApplication] alternateIconName]即可。启动时把两端结果统一写回 PlayerPrefs，保证 UI 上显示的"当前图标"和实际一致。

4.3 图标资源的版本管理

这里有个容易被忽视的问题：如果运营要换一套新图标，Android 可以配合资源热更动态下发新图，但 iOS 必须重新发版。所以双端做图标功能时，图标集合的版本要和 App 版本绑定。我的做法是在配置表里给每套图标加一个minAppVersion字段，客户端启动时过滤掉当前版本不支持的图标，避免用户点了没反应。

另外，Android 动态下发图标资源时，alias 的android:icon指向的是打包时的资源 ID，运行时替换 mipmap 文件不会生效。真要动态换图，得走"下载新图 → 写入应用私有目录 → 用PackageManager的setComponentEnabledSetting配合自定义 Launcher 图标"的路子，复杂度陡增。所以我的建议是：Android 也尽量预置图标，动态下发只作为极少数场景的补充。

5. 上线前必须验证的兼容性与审核问题

功能跑通只是第一步，真正上线前还有一堆兼容性和审核的坑等着。这部分是我踩得最惨的地方，单独拎出来讲。

5.1 Android 各 ROM 的 alias 刷新差异

我在华为、小米、OPPO、vivo、三星几个主流机型上做过测试，结果差异明显：

应对策略：切换后给一个 Toast 提示"图标更新中，请稍候"，并延迟 3 秒再刷新应用内 UI。如果检测到 5 秒后仍未生效，提示用户"请尝试滑动桌面或重启桌面"。别小看这个提示，能挡掉大量客服工单。

5.2 iOS 审核的几条红线

iOS 备用图标在审核上有几个明确要求：一是所有备用图标必须和主图标风格一致，不能出现完全无关的图案（比如主图标是工具类，备用图标放个卡通人物）；二是不能通过换图标诱导用户付费或做任务（比如"换图标解锁隐藏内容"）；三是图标不能包含违规内容。我见过有项目因为备用图标里带了节日营销文案被拒的，理由是"图标作为 App 标识不应包含促销信息"。

另外，CFBundleAlternateIcons里的图标如果尺寸不全，审核时可能被标记为"资源不完整"。建议至少覆盖 iPhone 的 @2x 和 @3x，支持 iPad 的话把 iPad 尺寸也补齐。

5.3 切换失败的回滚与日志

无论哪端，切换都可能失败（Android 权限问题、iOS 资源缺失）。一定要做失败回滚：切换前记录当前 key，失败后切回原 key，并上报日志。日志里带上平台、系统版本、机型、目标 key、错误码，方便排查。我一般会在AppIconManager里加一个OnSwitchFailed事件，业务层可以监听并做 UI 提示。

提示：Android 的setComponentEnabledSetting在某些 ROM 上会抛SecurityException，尤其是应用被用户手动限制了后台权限时。捕获异常后不要直接崩溃，降级为"提示用户手动切换"。

6. 一些实战中攒下来的经验

做这个功能前后跨了三个项目，攒了几条文档里不会写的经验，分享出来。

第一，别在启动瞬间切图标。有些项目为了"每天自动换图标"，在Awake里就调切换接口。结果 Android 上应用还没完全起来，PackageManager调用可能失败；iOS 上系统提示框会盖在启动图上，体验极差。正确做法是等主界面加载完、用户有交互之后再切，或者干脆放到设置页里让用户手动触发。

第二，图标数量控制在 6 套以内。Android 虽然理论上不限，但每多一个 alias，Manifest 就大一圈，安装包体积和启动扫描时间都会增加。iOS 这边备用图标多了，Xcode 编译时间和包体也会明显上涨。我一般建议主图标 + 5 套备用，够用了。

第三，测试时一定要用真机。模拟器和 Editor 里都测不出 alias 切换的真实表现，iOS 的提示框也只有真机才有。我吃过亏，Editor 里跑得好好的，真机上一半机型不生效。

第四，给运营做一个后台开关。图标切换功能上线后，运营可能会想"今天换个节日图标"。如果每次都要发版，成本太高。Android 可以通过配置热更控制切哪套（图标本身预置），iOS 只能发版。所以后台要能区分两端，Android 走热更配置，iOS 走版本发布计划。

第五，保留一套"默认图标"作为兜底。用户如果遇到切换异常，至少能切回默认。默认图标的 alias 建议永远保持可用，不要禁用。

这套方案在几个上线项目里跑下来，Android 端覆盖率 95% 以上，iOS 端除了那个提示框之外没有其他问题。真正麻烦的从来不是代码，而是各 ROM 的差异和审核的边界。把这两块摸清楚，剩下的就是体力活了。