Flutter Workmanager在iOS报BGTaskSchedulerErrorDomain Code=3错误求助

这个错误代码BGTaskSchedulerErrorDomain Code=3对应BGTaskSchedulerErrorNotPermitted，表示后台任务调度被系统拒绝，核心原因集中在配置不完整、权限缺失或参数不匹配，以下是逐一排查步骤：

1. 验证Info.plist配置完整性 #

必须确保两个关键配置项正确添加：

• 后台模式权限：添加UIBackgroundModes数组，包含后台任务所需的模式：

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

• 允许的任务ID：添加BGTaskSchedulerPermittedIdentifiers数组，里面必须包含你在代码中注册的任务ID（大小写完全一致）：

  <key>BGTaskSchedulerPermittedIdentifiers</key>
  <array>
      <string>com.your.app.background.task</string>
  </array>
  

2. 检查AppDelegate任务注册逻辑 #

确保在App启动时正确注册了对应ID的后台任务，示例代码：

Objective-C #

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [BGTaskScheduler sharedScheduler];
    GeneratedPluginRegistrant *registrant = [GeneratedPluginRegistrant new];
    [registrant registerWithRegistry:self];

    // 注册与plist中一致的任务ID
    NSError *error;
    BOOL success = [[BGTaskScheduler sharedScheduler] registerForTaskWithIdentifier:@"com.your.app.background.task" usingQueue:nil launchHandler:^(BGAppRefreshTask *task) {
        // 任务执行完成后必须标记结束
        [task setTaskCompletedWithSuccess:YES];
    }];
    if (!success) {
        NSLog(@"任务注册失败: %@", error);
    }

    return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

Swift #

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    BGTaskScheduler.shared.register(forTaskWithIdentifier: "com.your.app.background.task", using: nil) { task in
        guard let refreshTask = task as? BGAppRefreshTask else { return }
        // 处理任务逻辑
        refreshTask.setTaskCompleted(success: true)
    }
    GeneratedPluginRegistrant.register(with: self)
    return true
}

3. 核对Flutter端任务ID一致性 #

Flutter侧注册任务时，ID必须与Info.plist、AppDelegate中的完全一致：

void callbackDispatcher() {
  Workmanager().executeTask((task, inputData) {
    // 后台业务逻辑
    return Future.value(true);
  });
}

void main() {
  Workmanager().initialize(
    callbackDispatcher,
    isInDebugMode: false, // 发布版本需设为false，Debug模式iOS后台任务会被系统限制
  );
  // 注册任务的ID必须和配置文件完全匹配
  Workmanager().registerOneOffTask(
    "com.your.app.background.task",
    "backgroundTask",
    initialDelay: Duration(minutes: 1),
  );
  runApp(MyApp());
}

4. 检查系统权限与限制 #

• 确认应用的后台App刷新未被禁用：进入设备「设置」→「通用」→「后台App刷新」，找到你的应用并开启开关。
• 关闭设备的低电量模式，该模式会强制禁用所有后台任务。
• 建议用Release模式测试，Debug模式下iOS系统会严格限制后台任务触发。

5. 验证插件版本兼容性 #

确保使用的workmanager插件版本与当前Flutter SDK版本兼容，优先使用最新稳定版，旧版本可能存在BGTaskScheduler适配漏洞。

内容的提问来源于stack exchange，提问作者Mr. Developer