使用react-native-change-icon返回true但图标未生效如何解决

适用环境 #

• React Native 版本：0.67.4
• react-native-change-icon 版本：v3.1.1
• 已完成官方文档标注的基础配置

iOS端诱因及修复 #

• 备用图标存放路径错误：v3.1.1版本iOS端不识别放在Images.xcassets里的备用图标，所有备用图标资源（含2x、3x分辨率文件）必须直接拖入Xcode项目主目录，勾选Copy items if needed并选中主app target，不要放入xcassets资源目录，否则系统找不到对应资源，方法会直接返回true无任何报错。
• Info.plist配置层级或字段错误：CFBundleIcons下的CFBundleAlternateIcons键名必须和调用changeIcon()时传入的字符串完全一致（区分大小写），每个图标配置项除UIPrerenderedIcon、CFBundleIconFiles外不要加多余字段，v3.1.1对冗余字段容错为0，会直接静默失败。正确配置参考：

<key>CFBundleIcons</key>
<dict>
  <key>CFBundleAlternateIcons</key>
  <dict>
    <!-- 这里的key就是调用changeIcon时传入的图标名 -->
    <key>red_icon</key>
    <dict>
      <key>UIPrerenderedIcon</key>
      <false/>
      <key>CFBundleIconFiles</key>
      <array>
        <string>red_icon</string>
      </array>
    </dict>
  </dict>
  <key>CFBundlePrimaryIcon</key>
  <dict>
    <key>CFBundleIconFiles</key>
    <array>
      <string>AppIcon</string>
    </array>
  </dict>
</dict>

• 调用时机过早：不要在应用启动的componentDidMount或首屏useEffect里同步调用切换方法，此时iOS端的图标切换服务尚未完成初始化，会直接触发假成功返回true，至少等首屏渲染完成1s后再调用，或绑定到用户点击事件上触发。

Android端诱因及修复 #

• 安卓12+适配遗漏：RN 0.67默认targetSdkVersion为31及以上，v3.1.1版本未自动给activity-alias配置android:exported="true"属性，没有该属性时系统会拦截图标切换请求，库层无法捕获该错误就会默认返回true。所有在AndroidManifest.xml中声明的备用图标别名都需要补上该属性，参考配置：

<activity-alias
  android:name=".MainActivity_red_icon"
  android:enabled="false"
  android:exported="true"
  android:icon="@mipmap/red_icon"
  android:targetActivity=".MainActivity">
  <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
  </intent-filter>
</activity-alias>

• 资源路径错误：备用图标必须放入android/app/src/main/res/mipmap-各分辨率目录下，不能放在drawable目录，且备用图标资源名不能和主图标重名，否则会触发系统launcher缓存导致切换无感知。
• 国产ROM权限拦截：小米、华为、OPPO等定制安卓系统需要应用持有com.android.launcher.permission.INSTALL_SHORTCUT权限，在AndroidManifest.xml中补充该权限声明即可，否则切换操作会被系统静默拦截。

通用兼容问题修复 #

• v3.1.1版本存在返回值逻辑bug：该版本方法不会等待系统端切换结果，只要方法被调用就会立刻resolve(true)，不会抛出系统层错误。可以直接在原生层打日志排查：iOS端在node_modules/react-native-change-icon/ios/ChangeIcon.m的changeIcon方法入口加断点/NSLog，确认传入的图标名和配置键名完全匹配；Android端在ChangeIconModule.java的对应方法中打日志，确认别名activity的name和传入参数匹配。
• 自动链接失效：RN 0.67的自动链接存在偶发漏链情况，iOS端重新执行pod install并清理build缓存；Android端检查MainApplication.java的getPackages列表，若不存在ChangeIconPackage则手动添加，不要在多进程模式下初始化该模块，否则会因拿不到launcher上下文导致切换失效。
• 系统缓存干扰：测试阶段反复切换无效果时，直接卸载应用重装即可清掉iOS和安卓launcher的图标缓存，不要用覆盖安装的方式测试图标切换功能。

内容的提问来源于stack exchange，提问作者neo