Android端react-native-background-fetch回调函数始终未执行问题求助

问题概述 #

在Android环境下使用react-native-background-fetch v4.2.1启动后台任务时，仅输出try ok，配置的回调函数始终未执行，关联的locationAndNotificationTask也未运行。相关环境与代码如下：

• React Native 0.73.2
• minSdkVersion=21, compileSdkVersion=34, targetSdkVersion=34

启动任务代码：

const startStask = async () => {
  try {
    console.log('try ok');
    await BackgroundFetch.configure(
      {
        minimumFetchInterval: 15, 
        stopOnTerminate: true, 
        startOnBoot: true, 
      },
      async taskId => {
        console.log('[BackgroundFetch] taskId: ', taskId);
        await locationAndNotificationTask();
        BackgroundFetch.finish(taskId);
      },
      error => {
        console.log('[BackgroundFetch] failed to start');
      },
    );
  } catch (error) {
    console.log('start BG stask err', error);
  }
};

触发开关代码：

const toggleSwitch = async () => {
    const newValue = !isEnabled;
    try {
      console.log('okay ! ', newValue)
      if (newValue) {
        setIsEnabled(newValue); // true
        await AsyncStorage.setItem('notifications_status', `${newValue}`);
        backgroundTaskIsRunning() ? null : await startStask();
      } else {
        setIsEnabled(newValue); // false
        await AsyncStorage.setItem('notifications_status', `${newValue}`);
        await stopStask();
      }
    } catch (error) {
      console.log('menuScreen err', error);
    }
  };

排查与解决步骤 #

1. 补全AndroidManifest配置 #

确保AndroidManifest.xml添加必要的权限与组件声明：

<!-- 后台任务核心权限 -->
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

<!-- 注册Boot广播接收器与无头任务服务 -->
<receiver
    android:name="com.transistorsoft.rnbackgroundfetch.RNBackgroundFetchBootReceiver"
    android:enabled="true"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.BOOT_COMPLETED" />
        <action android:name="android.intent.action.QUICKBOOT_POWERON" />
        <action android:name="com.htc.intent.action.QUICKBOOT_POWERON" />
    </intent-filter>
</receiver>
<service
    android:name="com.transistorsoft.rnbackgroundfetch.RNBackgroundFetchHeadlessTask"
    android:enabled="true"
    android:exported="true"
    android:permission="android.permission.BIND_JOB_SERVICE" />

2. 处理Android 12+权限限制 #

Android 12（API 31）及以上对后台任务和通知权限有严格限制，需动态申请：

import { PermissionsAndroid, Platform } from 'react-native';

const requestRequiredPermissions = async () => {
  if (Platform.OS !== 'android') return true;
  
  const [bgLocationPerm, notificationPerm] = await Promise.all([
    PermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.ACCESS_BACKGROUND_LOCATION),
    PermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS)
  ]);
  
  return bgLocationPerm === 'granted' && notificationPerm === 'granted';
};

在startStask开头添加权限校验：

const startStask = async () => {
  const hasPermissions = await requestRequiredPermissions();
  if (!hasPermissions) {
    console.log('缺少后台任务必要权限');
    return;
  }
  // 原配置代码...
};

3. 修正配置参数逻辑 #

• stopOnTerminate: true会导致应用被杀死后任务终止，若需后台持续运行需改为false，且startOnBoot: true仅在stopOnTerminate: false时生效
• 开启无头任务支持，确保应用退出后仍能执行任务
  调整配置：

{
  minimumFetchInterval: 15, 
  stopOnTerminate: false,
  startOnBoot: true, 
  enableHeadless: true
}

4. 用ADB命令测试后台任务 #

Android后台Fetch任务不会立刻触发，需手动触发验证：

# 替换为你的应用包名，触发后台任务
adb shell cmd jobscheduler run -f com.your.package.name 999

# 查看RNBackgroundFetch相关日志
adb logcat -s RNBackgroundFetch

5. 修正任务运行状态判断逻辑 #

确保backgroundTaskIsRunning的实现正确，使用库自带的状态判断：

const backgroundTaskIsRunning = async () => {
  const status = await BackgroundFetch.status();
  return status === BackgroundFetch.STATUS_AVAILABLE;
};

6. 注册无头任务（可选） #

若需应用完全退出后仍执行任务，在index.js中注册无头任务：

import { AppRegistry } from 'react-native';
import BackgroundFetch from 'react-native-background-fetch';
import App from './App';
import { name as appName } from './app.json';

BackgroundFetch.registerHeadlessTask(async (taskId) => {
  console.log('[Headless] taskId: ', taskId);
  await locationAndNotificationTask();
  BackgroundFetch.finish(taskId);
});

AppRegistry.registerComponent(appName, () => App);

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