iOS端使用Workmanager.registerOneOffTask时callbackDispatcher无响应

Android端Workmanager运行正常，但iPhone 14测试时iOS端callbackDispatcher完全无响应，已按官方配置文档完成设置，以下是关键代码与配置，以及对应的排查解决步骤：

关键代码与配置 #

任务密钥 #

const simpleTaskKey = "be.tramckrijte.workmanagerExample.simpleTask";

CallbackDispatcher函数 #

void callbackDispatcher() {
  Workmanager().executeTask((task, inputData) async {
    switch (task) {
      case simpleTaskKey:
        print("$simpleTaskKey was executed. inputData = $inputData");

        final prefs = await SharedPreferences.getInstance();
        prefs.setBool("test", true);
        print("Bool from prefs: ${prefs.getBool("test")}");
        break;
 
      case Workmanager.iOSBackgroundTask:
        print("The iOS background fetch was triggered");
        Directory? tempDir = await getTemporaryDirectory();
        String? tempPath = tempDir.path;
        print("You can access other plugins in the background, for example Directory.getTemporaryDirectory(): $tempPath");
        break;
    }

    return Future.value(true);
  });
}

Workmanager初始化代码 #

ElevatedButton(
  child: Text("Start the Flutter background service"),
  onPressed: () {
    Workmanager().initialize(
      callbackDispatcher,
      isInDebugMode: true,
    );
  },
),

触发一次性任务代码 #

ElevatedButton(
  child: const Text("Register OneOff Task"),
  onPressed: () {
    Workmanager().registerOneOffTask(
      simpleTaskKey,
      simpleTaskKey,
      inputData: <String, dynamic>{
        'int': 1,
        'bool': true,
        'double': 1.0,
        'string': 'string',
        'array': [1, 2, 3],
      },
    );
  },
),

Info.plist配置 #

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>be.tramckrijte.workmanagerExample.simpleTask</string>
</array>

AppDelegate.swift代码 #

import UIKit
import Flutter
import workmanager

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
override func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
GeneratedPluginRegistrant.register(with: self)
WorkmanagerPlugin.registerTask(withIdentifier: "be.tramckrijte.workmanagerExample.simpleTask")

UIApplication.shared.setMinimumBackgroundFetchInterval(TimeInterval(/* Your Desired Interval for Background Tasks */)) 
return super.application(application, didFinishLaunchingWithOptions: launchOptions)
}
}

排查与解决步骤 #

1. 补全后台模式权限
   打开Info.plist，添加UIBackgroundModes配置，确保包含后台获取和处理权限：

   <key>UIBackgroundModes</key>
   <array>
       <string>fetch</string>
       <string>processing</string>
   </array>
   

2. 修正后台间隔配置
   把AppDelegate中注释占位的间隔值换成具体数值，比如30分钟（1800秒）：

   UIApplication.shared.setMinimumBackgroundFetchInterval(TimeInterval(1800))
   

   注意：iOS系统会根据设备状态调整实际触发频率，无法强制精确间隔。

3. Debug模式手动触发任务
   连接真机到Xcode，通过Debug -> Simulate Background Fetch手动触发后台任务，验证callbackDispatcher是否执行。模拟器的后台调度逻辑和真机差异大，优先用真机测试。

4. 校验任务ID一致性
   确保以下三处的任务ID完全一致：

   • Dart代码中的simpleTaskKey
   • Info.plist中的BGTaskSchedulerPermittedIdentifiers
   • AppDelegate中registerTask的标识符

5. 添加异常捕获
   在callbackDispatcher中增加异常捕获，避免异步操作异常导致任务静默失败：

   void callbackDispatcher() {
     Workmanager().executeTask((task, inputData) async {
       try {
         switch (task) {
           // 原有任务逻辑
         }
         return Future.value(true);
       } catch (e) {
         print("Task failed: $e");
         return Future.value(false);
       }
     });
   }
   

6. 更新插件版本
   检查flutter_workmanager依赖版本，确保使用最新稳定版，避免版本兼容性问题。

7. 真机测试注意事项

   • iOS后台任务受系统严格限制，低电量、后台App过多时可能不会触发
   • 测试时需将App切换到后台，等待系统调度，或通过Xcode工具手动触发

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