更新记录

1.0.0（2026-01-26）

实现App 图标动态切换插件，支持 Android 和 iOS。

平台兼容性

uni-app(3.91)

uni-app x(3.91)

uni-change-icon

App 图标动态切换插件，支持 Android 和 iOS。

平台支持

使用前必读

1. Android: 切换图标实际上是切换 activity-alias，会导致应用重启，这是系统机制，无法避免。
2. iOS: 系统限制无法修改应用名称，只能修改桌面图标。
3. 资源预埋: 所有要切换的图标必须预先打包在 App 中，无法通过网络动态下载设置。

快速开始

1. 准备图标资源

在你的项目根目录下创建 nativeResources 文件夹（如果不存在），并按以下结构放置图标：

ProjectRoot/
├── AndroidManifest.xml           <-- Android activity-alias 配置（必须在根目录）
├── Info.plist                    <-- iOS CFBundleAlternateIcons 配置（必须在根目录）
├── nativeResources/
│   ├── android/
│   │   └── res/
│   │       └── drawable/
│   │           ├── icon.png        <-- 默认图标
│   │           ├── icon_vip.png    <-- Android 备选图标 (全小写，无特殊符号)
│   │           └── icon_xmas.png
│   └── ios/
│       └── Resources/              <-- iOS 资源必须放在 Resources 子目录
│           ├── VipIcon.png         <-- iOS 备选图标 (区分大小写)
│           └── XmasIcon.png

2. 配置 AndroidManifest.xml

在项目根目录创建 AndroidManifest.xml，配置 activity-alias。 推荐使用统一命名，使 Android Alias 名称与 iOS Key 保持一致。

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="你的包名">
    <application>
        <!-- 默认别名: 用于恢复默认图标 -->
        <activity-alias
            android:name=".DefaultIcon"
            android:enabled="true"
            android:exported="true"
            android:icon="@drawable/icon"
            android:label="@string/app_name"
            android:targetActivity="io.dcloud.PandoraEntry">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity-alias>

        <!-- VIP 图标别名 (命名与 iOS 保持一致) -->
        <activity-alias
            android:name=".VipIcon"
            android:enabled="false"
            android:exported="true"
            android:icon="@drawable/icon_vip"
            android:label="VIP版"
            android:targetActivity="io.dcloud.PandoraEntry">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity-alias>
    </application>
</manifest>

3. 配置 Info.plist (iOS)

在项目根目录创建 Info.plist 文件，配置 CFBundleAlternateIcons。

参考文档：uni-app iOS 原生资源配置

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleIcons</key>
    <dict>
        <key>CFBundlePrimaryIcon</key>
        <dict>
            <key>CFBundleIconFiles</key>
            <array>
                <string>AppIcon60x60</string>
            </array>
            <key>UIPrerenderedIcon</key>
            <false/>
        </dict>
        <key>CFBundleAlternateIcons</key>
        <dict>
            <key>VipIcon</key>
            <dict>
                <key>CFBundleIconFiles</key>
                <array>
                    <string>VipIcon</string>
                </array>
                <key>UIPrerenderedIcon</key>
                <false/>
            </dict>
            <key>XmasIcon</key>
            <dict>
                <key>CFBundleIconFiles</key>
                <array>
                    <string>XmasIcon</string>
                </array>
                <key>UIPrerenderedIcon</key>
                <false/>
            </dict>
        </dict>
    </dict>
    <!-- iPad 配置 -->
    <key>CFBundleIcons~ipad</key>
    <dict>
        <key>CFBundlePrimaryIcon</key>
        <dict>
            <key>CFBundleIconFiles</key>
            <array>
                <string>AppIcon76x76</string>
            </array>
            <key>UIPrerenderedIcon</key>
            <false/>
        </dict>
        <key>CFBundleAlternateIcons</key>
        <dict>
            <key>VipIcon</key>
            <dict>
                <key>CFBundleIconFiles</key>
                <array>
                    <string>VipIcon</string>
                </array>
                <key>UIPrerenderedIcon</key>
                <false/>
            </dict>
            <key>XmasIcon</key>
            <dict>
                <key>CFBundleIconFiles</key>
                <array>
                    <string>XmasIcon</string>
                </array>
                <key>UIPrerenderedIcon</key>
                <false/>
            </dict>
        </dict>
    </dict>
</dict>
</plist>

4. 代码调用

import { changeIcon } from '@/uni_modules/uni-change-icon'

const isAndroid = uni.getSystemInfoSync().platform === 'android';

// 切换到 VIP 图标 (统一命名，Android 和 iOS 使用相同参数)
const result = await changeIcon('VipIcon');
if (result.success) {
    uni.showToast({ title: result.message, icon: 'success' });
} else {
    uni.showToast({ title: result.message, icon: 'error' });
}

// 恢复默认图标
if (isAndroid) {
    await changeIcon('DefaultIcon');
} else {
    await changeIcon(null);  // iOS 传 null 恢复默认
}

API

changeIcon(iconName: string | null): Promise\<ChangeIconResult>

切换应用图标。

参数:

• iconName: 图标名称。Android 传入 Alias 名称，iOS 传入 plist 中的 Key。传 null (仅 iOS) 恢复默认图标。

返回值:

interface ChangeIconResult {
    success: boolean;  // 是否成功
    message: string;   // 结果描述
}

统一命名规范

推荐使用统一命名，使 Android Alias 和 iOS Key 保持一致：

注意事项

1. 必须使用自定义基座或云打包：原生配置在标准基座中不生效
2. Android 切换后会重启：这是系统机制，无法避免
3. iOS 图标放在 Resources 目录：必须放在 nativeResources/ios/Resources/ 目录下
4. Info.plist 放在项目根目录：不是 nativeResources/ios/ 目录