Unity Android插件onHandleIntent未被调用问题排查与修复

开发Unity应用时，通过Termux定义的RUN_COMMAND Intent实现与Termux安卓应用的交互，安卓插件侧包含两个核心类：

• PluginInstance.java：缓存Unity Activity实例，构造RUN_COMMAND Intent，调用startForegroundService启动Termux的RunCommandService执行指令；执行指令时构造指向PluginResultsService的PendingIntent传入Termux服务，用于接收执行结果并回传Unity层，同时提供日志打印、指令执行、回调对象名配置等配套方法。
• PluginResultsService.java：继承自IntentService，通过onHandleIntent回调接收Termux回传的执行结果，再通过UnityPlayer.UnitySendMessage转发到Unity层。
  Unity层挂载在MonoBehaviour上的TerminalManager脚本负责初始化安卓插件实例、传入当前Unity Activity引用、绑定WebView输入事件触发Termux指令执行，预留ReceiveTermuxOutput方法接收回传结果并渲染到WebView。
  当前已验证指令可正常执行（测试mkdir testFolder指令后，打开Termux可在主目录看到新建的testFolder文件夹），但核心故障为PluginResultsService的onHandleIntent回调始终未触发，无法接收命令执行结果。

按从易到难逐层验证，避免无效调试：

1. 先检查AndroidManifest.xml中Service的声明配置
2. 验证PendingIntent构造逻辑与参数正确性
3. 核对传入Termux的RUN_COMMAND Intent所有Extra参数
4. 通过adb logcat分别过滤自身应用、Termux应用的相关日志，确认Termux执行完指令后是否存在发送PendingIntent的报错
5. 排查安卓版本后台限制、Termux版本兼容性问题

• 故障1：PluginResultsService未正确声明，外部应用无法唤起
  安卓系统要求跨应用唤起的组件必须显式配置导出属性，否则会被系统直接拦截。
  修复方案：
  在插件的AndroidManifest.xml中添加Service声明，确保android:exported属性设为true，安卓12及以上版本不可使用默认值，且不要给Service配置自定义权限拦截。参考配置：

  <service
      android:name=".PluginResultsService"
      android:exported="true"
      android:enabled="true" />
  

• 故障2：PendingIntent构造参数错误，Termux无法触发或填充结果
  修复方案：
  1. 安卓12及以上版本构造PendingIntent必须显式传入FLAG_MUTABLE Flag，否则Termux无法向Intent写入执行结果数据，甚至会直接触发失败。
  2. 使用显式Intent构造PendingIntent，明确指向当前应用的PluginResultsService组件，不要使用隐式Intent避免系统路由错误。参考代码：

  Intent resultIntent = new Intent(unityActivity, PluginResultsService.class);
  // 配置唯一Action避免Intent冲突
  resultIntent.setAction("com.your.package.TERMUX_RESULT");
  PendingIntent resultPendingIntent = PendingIntent.getService(
      unityActivity,
      0,
      resultIntent,
      PendingIntent.FLAG_MUTABLE | PendingIntent.FLAG_UPDATE_CURRENT
  );
  

• 故障3：RUN_COMMAND Intent缺少回调相关必填参数
  修复方案：
  对照参数定义检查传入Termux的Intent Extra，确保：
  1. 已传入key为com.termux.app.RUN_COMMAND_EXTRA_PENDING_INTENT的Extra，值为前面构造的结果回调PendingIntent
  2. 将com.termux.app.RUN_COMMAND_EXTRA_BACKGROUND参数设为true，避免Termux前台会话未启动时直接丢弃回调
     注意参数key不要手动拼写，建议直接复制常量值，避免字符错误导致参数不生效。
• 故障4：安卓后台启动Service限制拦截了回调
  安卓10及以上版本对应用后台启动Service有严格限制，若触发指令时你的应用在后台，系统会直接拦截Termux启动PluginResultsService的请求。
  修复方案：
  1. 先将应用切到前台触发指令测试，如果前台状态下能正常收到回调，即可确认是后台限制问题。
  2. 兼容性更好的方案是将结果回调改为BroadcastReceiver实现，系统对跨应用发送广播的后台限制远低于启动Service，验证通过后可按需保留广播实现或做版本适配。
• 故障5：Termux版本不支持回调逻辑
  部分老旧版本、第三方修改版Termux未实现RUN_COMMAND Intent的结果回调逻辑，会直接忽略传入的PendingIntent参数。
  修复方案：安装官方渠道发布的最新稳定版Termux后重新测试。

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