做手游运营的同事大概都经历过类似的场景某个版本想蹭春节节点运营提了个工单——“周五之前把游戏在手机桌面上的图标换成春节版活动结束再换回来”。这个需求听起来简单落地却涉及 Unity 手游在 Android 与 iOS 双端如何动态更换 App 图标。很多项目做到了玩法、UI、性能优化一碰上系统层面的功能就有点发懵桌面图标不是打包时写死的吗运行时还能改这篇文章我就把两条平台路线的原理、接入步骤、边界限制和实际踩过的坑一次讲清楚适合 Unity 客户端主程、原生扩展开发以及所有被运营追着要功能的朋友参考。1. 需求拆解运营要的“换个图标”到底是在换什么先说结论动态更换 App 图标指的是系统桌面Android Launcher / iOS 主屏幕上显示的这个应用图标在 App 运行期间被切换成另一套预置图标资源。它不等于游戏启动画面不等于应用内主题更不是桌面小组件的换肤。这个区别必须先跟运营对齐否则后面所有工作都会跑偏。从运营视角看换图标的诉求这几年越来越高频节日活动春节、中秋、双十一、周年庆期间换一套氛围图标提高商店页和桌面端的辨识度。版本联动大版本更新时配合美术风格把图标提前换成新 Key Visual。限时返场某 IP 联动活动结束后把图标改回普通版本。用户自选更进一步的玩法让玩家在多个官方图标里选一个作为个性入口。工程上这四种诉求其实分属于两种技术路径诉求类型实现方式工作量和风险平时换新图标下次版本直接改打包资源重新发版最低限时/动态换图标本次活动运行时切换预置图标中等本文主题用户自选图标动态切换 多套预置图标 持久化较高从服务器拉取新图标再换Android/iOS 均不支持不可行为什么“从服务器拉一张图运行时换到桌面”不可行这是需求沟通时要讲清楚的第一条红线。iOS 的setAlternateIconName只认 App Bundle 内声明的图标文件Android 的 Activity-alias 也只认 Manifest 里配置的资源都不允许运行时下载一张图片直接当图标用。运营提的“活动图标”必须在发版前以资源形式打进安装包。所以做这功能本质是在“提前内置 N 套图标”和“运行时切换显示哪套”之间做文章而不是真的动态下载。这个功能适合的场景也很明确游戏已经有稳定的版本节奏运营活动可以提前规划图标美术资源能跟着版本一起提交。如果运营每次活动前一天才给图那谁来做都救不了及早回复“不行”也是专业的一部分。2. Android 老路线Activity-alias 组件的启用与禁用细节Android 上经典的动态换图标方案是通过 Manifest 里的多个activity-alias指向同一个主 Activity再用PackageManager.setComponentEnabledSetting在运行时切换启用/禁用状态。这也是今天绝大多数国内手游还在用的方式。2.1 AndroidManifest 中 alias 的注册姿势以一个MainActivity 默认图标 春节图标为例Manifest 核心配置长这样activity android:namecom.yourgame.activity.MainActivity android:exportedtrue android:screenOrientationlandscape /activity !-- 默认图标入口 -- activity-alias android:namecom.yourgame.activity.MainActivity_Default android:targetActivitycom.yourgame.activity.MainActivity android:exportedtrue android:enabledtrue android:iconmipmap/ic_launcher android:labelstring/app_name intent-filter action android:nameandroid.intent.action.MAIN / category android:nameandroid.intent.category.LAUNCHER / /intent-filter /activity-alias !-- 春节图标入口 -- activity-alias android:namecom.yourgame.activity.MainActivity_Spring android:targetActivitycom.yourgame.activity.MainActivity android:exportedtrue android:enabledfalse android:iconmipmap/ic_launcher_spring android:labelstring/app_name_spring intent-filter action android:nameandroid.intent.action.MAIN / category android:nameandroid.intent.category.LAUNCHER / /intent-filter /activity-alias注意几个关键点每个 alias 独立声明 icon 和 labellabel 也可以随活动换文案。android:enabled默认只有一个为true否则桌面会出现两个相同 App 入口这是最常见的翻车点。所有 alias 必须能处理 MAIN/LAUNCHER intent-filter系统才会把它们当作可启动的桌面入口。Unity 工程里这个配置要写进AndroidManifest.xml并且要注意 2019 之后 Unity 默认把 MainActivity 写在unityLibrary的清单里合并规则不熟的人容易改错文件改完发现没生效。建议把 alias 单独放一个 Manifest 片段通过AndroidManifest.xml的tools:nodemerge合并进最终清单。2.2 PackageManager 切换的关键代码与执行顺序原生侧切图标的代码核心就一个方法public static void setAlias(Context context, String enableAlias, String disableAlias) { PackageManager pm context.getPackageManager(); ComponentName disableComp new ComponentName(context, disableAlias); ComponentName enableComp new ComponentName(context, enableAlias); // 先禁用旧入口再启用新入口 pm.setComponentEnabledSetting( disableComp, PackageManager.COMPONENT_ENABLED_STATE_DISABLED, PackageManager.DONT_KILL_APP); pm.setComponentEnabledSetting( enableComp, PackageManager.COMPONENT_ENABLED_STATE_ENABLED, PackageManager.DONT_KILL_APP); }为什么是“先禁用再启用”因为如果先启用新的两个入口有瞬间同时存在桌面会出现短暂双图标虽然通常只有几十毫秒但部分低端机 Desktop 刷新慢可能让用户看到两个图标体验很差。先禁用旧的虽然也可能让入口短暂消失但至少不会两个并存。另外一个容易忽略的点ComponentName的 class 名要完整包名不是简单写.MainActivity_Spring。Android 官方虽然是点号开头但在new ComponentName(context, String)时如果你传的是相对名系统在部分 ROM 上能解析、在 AOSP 上不一定。最好是完整名实测下来最稳。切换完成后Launcher 是通过接收PACKAGE_CHANGED广播来刷新图标的所以不需要我们主动去通知桌面。但不同厂商桌面对这个广播的处理时机不一样华为 EMUI 和三星 One UI 表现都不同有些是秒刷新有些要等几秒真机验证时别一看到没立即变就以为失败。3. Android 新路线与兼容退路targetSdk 34 之后怎么办Activity-alias 方案虽然经典但从Android 14targetSdk 34开始这条路已经不太平了。谷歌在这个版本上收紧了运行时动态图标的支持官方兼容性说明明确提到通过setComponentEnabledSetting切换 activity-alias enabled 状态来更换图标在 targetSdk 34 的 App 上有很大概率不再触发桌面图标刷新你的入口状态可能变了但桌面图标就是纹丝不动。这对做海外市场的团队几乎是致命的因为 Google Play 从 2024 年 8 月之后新版本内更新要求 targetSdk 34。所以现在的 Android 侧实现我建议做按系统版本分流3.1 低版本继续走 aliasAndroid 13 及以下这块按上面第二章节的配置实现即可稳定、直接、可批量配置。唯一要注意的是如果你的图标用到了Adaptive Icon那每个 alias 的 icon 资源要同时准备 foreground/background 层不能只给一个普通 PNG。Android 8 的桌面默认用 Adaptive Icon 的遮罩如果只给普通图很多桌面会把它放到一个白色圆形底里效果非常违和。3.2 高版本降级Pinned ShortcuttargetSdk 34 上官方推荐的能力是Shortcut / Pinned Shortcut。它的好处是不改变组件 enabled 状态而是直接创建一个“固定快捷方式”到桌面可以带自定义图标。代码大致这样ShortcutManager shortcutManager context.getSystemService(ShortcutManager.class); if (shortcutManager ! null) { ShortcutInfo shortcut new ShortcutInfo.Builder(context, shortcut_spring) .setShortLabel(春节版) .setIcon(Icon.createWithResource(context, R.mipmap.ic_launcher_spring)) .setIntent(new Intent(Intent.ACTION_MAIN) .setClassName(context, com.yourgame.activity.MainActivity) .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)) .build(); Intent intent shortcutManager.createShortcutResultIntent(shortcut); // 需要配合 PendingIntent 调用这里省略 shortcutManager.requestPinShortcut(shortcut, null); }注意requestPinShortcut是系统会弹窗让用户确认的不是无声无息地替换图标而且创建出来的是独立的快捷方式不是替换原 App 图标这是两个概念。所以它只能算“降级交差”方案不能直接说支持Android 14动态换图标。3.3 最高保底方案弹窗引导如果快捷方式也弹窗、用户不接受那最后的兜底是发版前预置多套图标活动切换时给用户一个“如何手动更换图标”的引导流程。这种方案参与感更强但转化率低只适合没有硬性指标的时候用。事实上很多只做国内安卓的团队现在还在用targetSdk 30/33Activity-alias 方案继续跑没什么问题但只要哪天你准备上 Google Play 或把 targetSdk 升到 34就必须提前把降级链路做好否则活动期间图标没法换运营可是会直接找上门的。4. iOS 端实现setAlternateIconName 与 Info.plist 的配对法则iOS 这边比 Android 清爽很多因为系统从 iOS 10.3 开始就提供了官方 APIUIApplication.setAlternateIconName(_:completionHandler:)。但清爽不等于没坑最大的坑就是名字配对你调用 API 传的名字必须和 Info.plist 里声明的一致否则系统直接回调错误。4.1 Info.plist 配置必须遵守的配对关系在 Xcode 工程或 Unity 生成的 Info.plist 里要加这样一段keyCFBundleIcons/key dict keyCFBundleAlternateIcons/key dict keyIconSpring/key dict keyCFBundleIconFiles/key array stringIconSpring/string /array /dict /dict /dict然后往 Xcode 工程里放两张图IconSpring2x.png120x120和IconSpring3x.png180x180并且确保它们被 Copy Bundle Resources。注意 CFBundleIconFiles 里写的是“无后缀的基础名”不是带 2x 的文件名系统会自动按 scale 找IconSpring2x.png/IconSpring3x.png。这里有几个硬性限制踩过的人都懂图标图片不能包含 alpha 通道否则 App Store 审核会有警告部分审核情况下会以“图标不符合规范”驳回。图片必须随包放在 main bundle 里不能放到 StreamingAssets 或沙盒目录运行时下载更是不行。如果支持 iPad要额外处理CFBundleIcons~ipad下的CFBundleAlternateIcons配置常见坑是 iPhone 配了、iPad 没配真机一测 iPad 图标不生效。4.2 OC 插件与 C# 侧调用Unity 工程里要调用这个能力最省事的做法是写一个 Objective-C 插件用extern C导出给 C# 调用#import UIKit/UIKit.h extern C void _ChangeAppIcon(const char *iconName) { NSOperatingSystemVersion version [[NSProcessInfo processInfo] operatingSystemVersion]; if (version.majorVersion 10 || (version.majorVersion 10 version.minorVersion 3)) { UnitySendMessage(AppIconBridge, OnComplete, unsupported); return; } NSString *name nil; if (iconName ! NULL) { name [NSString stringWithUTF8String:iconName]; } dispatch_async(dispatch_get_main_queue(), ^{ [[UIApplication sharedApplication] setAlternateIconName:name completionHandler:^(NSError *error) { if (error) { UnitySendMessage(AppIconBridge, OnComplete, fail); } else { UnitySendMessage(AppIconBridge, OnComplete, ok); } }]; }); }必须在主线程调用且一旦用户首次使用这个能力系统会弹一个确认弹窗如果用户点了不允许completionHandler 里的 error 不为空要处理这个分支而不是默认一定成功。iOS 的动态换图标还有一些体验层面的细节比如切换后主屏幕图标会立即变但 App 内、Spotlight 搜索、设置列表里的图标可能存在不一致这在 iOS 17 上会多一些同步优化但老版本表现差异明显上线前要跟运营讲清楚别让他们在测试机上看到了什么奇怪反馈就紧张。5. Unity 桥接层把原生能力封装成双端统一的 C# 接口按上面的方案原生逻辑已经就绪但 Unity 工程里不能每个调用点都去区分 Android/iOS。这里我建议做一个AppIconManager静态类提供统一的 C# API上层无论是 UI 按钮、Lua 脚本、服务端配置都只跟这个类打交道。5.1 统一接口设计与平台分发public static class AppIconManager { public static event Actionbool OnIconChanged; #if UNITY_ANDROID !UNITY_EDITOR private static readonly AndroidJavaClass IconHelperClass new AndroidJavaClass(com.yourgame.common.IconHelper); #endif #if UNITY_IOS !UNITY_EDITOR [System.Runtime.InteropServices.DllImport(__Internal)] private static extern void _ChangeAppIcon(string iconName); #endif public static void SetIcon(string iconId) { if (string.IsNullOrEmpty(iconId)) { RestoreDefault(); return; } #if UNITY_ANDROID !UNITY_EDITOR IconHelperClass.CallStatic(setIcon, iconId); OnIconChanged?.Invoke(true); #elif UNITY_IOS !UNITY_EDITOR _ChangeAppIcon(iconId); #endif } public static void RestoreDefault() { #if UNITY_ANDROID !UNITY_EDITOR IconHelperClass.CallStatic(restoreDefault); OnIconChanged?.Invoke(true); #elif UNITY_IOS !UNITY_EDITOR _ChangeAppIcon(null); #endif } public void OnComplete(string result) { OnIconChanged?.Invoke(result ok); } }这里要注意第三方的回调桥接iOS 插件跑完会UnitySendMessage(AppIconBridge, OnComplete, ok)所以场景里需要一个名为AppIconBridge的 GameObject挂一个脚本接收消息然后转发给AppIconManager.OnComplete。Android 那边因为切换是同步请求异步桌面刷新我一般在 C# 里直接当成成功处理但发送完以后不要立刻让玩家切到桌面看效果建议等 0.5~1 秒再提示“已切换”否则玩家切出去时桌面还在刷新会误以为失败了。5.2 回调、状态持久化与 Lua 侧暴露更完整的工程还会把当前图标状态持久化到PlayerPrefs这样用户强杀游戏再回桌面图标还保持切换后的状态。但只记自己这一侧不够iOS 侧最好在启动时读一下系统的当前状态因为系统可能会因某些原因回退默认图标跟本地记录对不上。读取很简单NSString *currentIcon [[UIApplication sharedApplication] alternateIconName];Android 侧也可以通过PackageManager查各 alias 的 enabled 状态来判断当前生效的是哪一套不过写法比较繁琐。更推荐的做法是以服务端活动配置为唯一事实来源客户端启动时拉一下活动状态发现活动结束就调RestoreDefault别依赖本地记录。这样即使本地记录坏了也能被服务端纠正回来。如果你的游戏是 Lua 驱动的桥接层再加一层轻封装即可local AppIconManager require(Game.Utils.AppIconManager) AppIconManager.SetIcon(spring)上层代码完全感知不到平台差异后续接入新活动也只是多配一个图标 ID 的事。6. 恢复策略、审核红线与真机验证清单功能上线后真正的考验其实是“什么时候换回去”和“换不回去怎么办”。我在实际项目里没少被这个事坑过。6.1 恢复时机与常见失效场景恢复默认图标的时机要考虑三块服务端活动结束信号每次启动/回前台时检查如果活动已过期就恢复默认。客户端内活动倒计时结束活动结束后立即恢复图标避免玩家活动都结束了桌面上还挂着春节图标直到运营线下催你。版本更新Unity 发新版本后Android alias 状态和 iOS alternate icon 状态到底保不保留关于第三点实测结果如下iOS系统会保留 alternate icon 状态覆盖安装后如果新包仍含相同图标资源一般不会自动回退。但如果你在新版本里删掉了旧的图标资源系统会遇到资源找不到的情况表现不稳定所以升级版本时最好显式恢复默认一次。AndroidsetComponentEnabledSetting的状态会持久化覆盖安装一般会保留。但 Android 14 因为不吃这套很可能“看似保留了状态但桌面图标没刷新”这才是最麻烦的所以高版本还是要走 fallback 链路。还有一类很隐蔽资源 ProGuard/shrinkResources 混淆后图标资源被裁剪掉了。Release 包如果没正确配置 keepalias 引用的mipmap/ic_launcher_spring可能在打包时被优化掉切图标后桌面显示的是系统兜底灰色图标用户和运营都一脸问号。解决方式是在 ProGuard 规则里 keep 所有R.mipmap资源或者给持续引用的图标资源加tools:keepmipmap/ic_launcher_spring。6.2 提审说明与国内厂商真机验证iOS 上使用setAlternateIconName本身是官方开放能力一般不因为“你调用了动态换图标”而被拒。但审核风险在于提交的备用图标内容是否符合内容规范比如不能用动态图标做赌博、色情、仿冒系统应用等擦边行为。提审时审核助手会读取 Info.plist 里的CFBundleAlternateIcons所以备用图标也必须在设计上跟 App 图标保持同一标准。Android 这边国内厂商虽然没有统一审核但各家桌面的兼容性差异非常大。我建过一张真机验证清单团队在上线前会按这个打点测试项关注点华为 EMUI / 小米 HyperOS / ColorOS / OriginOS切换后桌面图标是否自动刷新、是否出现双图标覆盖安装更新图标状态是否保留、quick settings 和相关入口是否正常Android 14 真机是否走了 fallback 链路、用户手动确认时文案是否正确iOS 12~17首次弹窗授权、拒绝后能否再次触发、恢复默认图标是否正常App 冷启动/热启动启动时读服务端配置是否有延迟是否出现短暂默认图标还有一个小建议别在代码里做太多“智能恢复”。早期我写过一个每次进游戏都检查当前桌面图标跟服务器配置是否一致的逻辑导致用户手动改了其他图标也被强制“纠正”回去反而收到了差评。正确的做法是服务器只在活动开始/结束两个节点下发配置客户端在这两个节点切一次图标中间不干预用户的选择。最后分享一个可以少走弯路的经验动态换图标功能一旦接上每次运营活动都会来排队找你要“再加一版图标”。所以接入时把表结构设计好图标配置表字段建议是icon_id / alias_name / ios_key / resource_path / 活动开始时间 / 活动结束时间服务端下发时把过期时间一起带下来。这样后续做节日图标、联动图标都只是往配置表里加一行的事不再需要客户端发版。我在项目里把这套东西跑稳之后最直观的感受是运营的“节日换图标”需求从两天开发量降到了半小时资源配置量这才是这个功能真正的价值所在。