Flutter iOS后台用WorkManager调用Firebase Storage putFile时抛异常

问题概况 #

• Flutter版本：3.22.0
• 项目依赖配置：

  #firebase
  firebase_core: ^3.1.0
  firebase_analytics: any
  firebase_crashlytics: ^4.0.1
  firebase_storage: ^12.0.1
  firebase_app_check: ^0.3.0+1
  #run in background
  workmanager:
    git:
      url: https://github.com/absar/flutter_workmanager.git
      ref: ios-bg-tasks-enh-final
  

• 异常现象：前台调用putFile方法完全正常，iOS后台环境下无法执行，异常触发在代码第67行（附图：[异常位置示意图]）；Android平台该功能运行无问题。

可行解决方案 #

1. 配置iOS后台权限 #

iOS对后台任务有严格的权限限制，需确保项目正确配置：

• 打开Xcode，进入项目Signing & Capabilities标签，添加Background Modes权限
• 勾选Background fetch和Remote notifications（若任务由推送触发）
• 在Info.plist中添加对应权限描述：

  <key>UIBackgroundModes</key>
  <array>
    <string>fetch</string>
    <string>remote-notification</string>
  </array>
  

2. 适配Firebase Storage后台会话 #

putFile在iOS后台需要使用后台URL会话，需自定义Storage配置：

final storage = FirebaseStorage.instance;
storage.setConfig(StorageConfig(
  sessionConfiguration: URLSessionConfiguration.background(withIdentifier: "com.your.app.storage.bg.session"),
));

注意：会话标识符需唯一，且与Xcode后台配置匹配。

3. 检查Workmanager iOS适配 #

针对使用的ios-bg-tasks-enh-final分支，需确认：

• 在AppDelegate.swift中完成任务注册：

  import Workmanager
  
  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
      WorkmanagerPlugin.registerTask(withIdentifier: "your-task-id")
      return true
  }
  

• 控制后台任务执行时长在iOS限制内（单次不超过30秒），避免被系统强制终止。

4. 捕获详细异常信息 #

在putFile调用处添加错误捕获，获取具体异常原因：

try {
  await FirebaseStorage.instance.ref().child("target/path").putFile(localFile);
} catch (e, stackTrace) {
  FirebaseCrashlytics.instance.recordError(e, stackTrace);
  print("后台上传失败：$e，栈信息：$stackTrace");
}

通过Crashlytics或日志排查是否为权限不足、会话失效等具体问题。

5. 验证iOS版本兼容性 #

确保测试设备iOS版本在13及以上，旧版本iOS对后台任务的限制更严格，可能导致功能无法正常运行。

内容的提问来源于stack exchange，提问作者Kiều Phong