Flutter注册WorkManager一次性任务时UI无响应问题排查

这里所说的“崩溃”指UI失去响应，但应用并未关闭，且VSCode调试控制台无任何有效错误信息。当前仅在iOS环境测试，未验证Android端。

初始化代码 #

main函数中初始化Workmanager：

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  Workmanager().initialize(callbackDispatcher, isInDebugMode: true);
  runApp(MyApp());
}

CallbackDispatcher代码 #

单独文件中的回调分发器：

void callbackDispatcher(){
  print('callbackDispatcher called');
  Workmanager().executeTask((task, inputData) async {
    switch(task){
      case "process_barcode":
        await getBarcodeDetails(inputData?['barcode']);
    }
    return Future.value(true);
  });
}

注：getBarcodeDetails的代码暂时未提供，因为callbackDispatcher中的print从未执行，推测该函数根本没被调用。

触发任务的按钮代码 #

UI中触发WorkManager任务的按钮逻辑：

ElevatedButton.icon(
  icon: const FaIcon(FontAwesomeIcons.barcode),
  onPressed: () async {
    TaskMonitor tm = TaskMonitor();
    bool isBcPending = await tm.isTaskPending('bc_lookup');
    if(!isBcPending){
      // 获取扫描的条码
      var result = await BarcodeScanner.scan();
      print('Barcode: ${result.rawContent}');

      // 保存条码数据到数据库
      await dataProvider.setBarcode(result.rawContent);
      print('Barcode set!');

      // 设置事件监听器，在条码扫描完成后执行操作
      dataProvider.waitForEvent('bc_lookup_completed');
      print("Start event listener");

      // 发起HTTP请求获取条码详情
      Workmanager().registerOneOffTask(
        'process_barcode', 
        'process_barcode', 
        inputData: {'barcode': result.rawContent}
      );
      print('Running the task..');
    }
  }, 
  label: const Text('Scan Barcode')
)

异常现象 #

• onPress中的最后一条print(Running the task..)在UI冻结前已执行
• 注释掉Workmanager().registerOneOffTask()调用后，UI不会冻结
• callbackDispatcher中的print('callbackDispatcher called')从未输出，说明任务未被触发
• VSCode调试控制台无任何有用错误信息

排查建议 #

• 检查iOS平台配置：
  • 确认Info.plist中已开启后台模式（Background Modes）的App processing tasks选项
  • 执行pod install确保Workmanager的iOS依赖正确安装
• 调整任务注册参数：
  • 给任务设置唯一ID，避免重复任务冲突，比如：

    Workmanager().registerOneOffTask(
      'process_barcode_${DateTime.now().millisecondsSinceEpoch}', 
      'process_barcode', 
      inputData: {'barcode': result.rawContent}
    );
    

  • 添加网络约束，确保有网时才执行任务：

    constraints: Constraints(networkType: NetworkType.connected)
    

• 简化任务逻辑做最小测试：
  暂时替换getBarcodeDetails为简单逻辑，验证任务是否能触发：

  case "process_barcode":
    await Future.delayed(Duration(seconds: 2));
    print('Task executed successfully');
  

• 检查主线程阻塞：
  确认dataProvider.waitForEvent是否是同步阻塞方法，如果是，会卡住UI线程，建议改成异步监听（比如用Stream或Future回调）
• 查看iOS系统日志：
  用Xcode的Console工具查看设备日志，搜索WorkManager相关条目，系统层面的错误（比如权限不足、任务被拒绝）不会输出到VSCode控制台
• 开启详细日志：
  确保初始化时isInDebugMode: true，同时可以在iOS原生项目中调整Workmanager的日志级别，获取更详细的运行信息

内容的提问来源于stack exchange，提问作者I wrestled a bear once.