WatchOS后台刷新任务未触发问题排查求助

问题描述 #

我开发了一款Apple Watch应用，需要执行后台任务获取数据并存入KeyChain，供Complications使用。已配置WKApplicationDelegate并使用SwiftUI的.appRefresh后台任务，但任务始终未触发，仅调度器在应用启动时能正常执行。

现有代码 #

App结构体与Delegate实现

import SwiftUI
import WatchKit

@main
struct WatchApp: App {
    
    @WKApplicationDelegateAdaptor(ExtensionDelegate.self) var delegate
    @ObservedObject var hostingModel = HostingModel.shared

    var body: some Scene {
        WindowGroup {
            ContentView()
                
        }
        .backgroundTask(.appRefresh) { context in
            print("background task")
            await hostingModel.fetchAll()
        }

    }
    
 
}


class ExtensionDelegate: NSObject, WKApplicationDelegate {
    @ObservedObject var hostingModel = HostingModel.shared

    func applicationDidFinishLaunching() {
        
    }

    func applicationDidBecomeActive() {
         hostingModel.scheduleBackgroundRefresh()
    }
    
    func applicationDidEnterBackground() {
        print("in background")
    }

// 我认为这个方法不需要，只是用来调试
    private func handle(_ backgroundTasks: Set<WKRefreshBackgroundTask>) async {
        print("handle")
        await hostingModel.fetchAll()
    }
}

调度方法实现

func scheduleBackgroundRefresh() {
    WKApplication.shared()
        .scheduleBackgroundRefresh(
            withPreferredDate: Date.init(timeIntervalSinceNow: 15 * 60.0),
            userInfo: nil) { error in
                if error != nil {
                    // 处理调度错误
                    fatalError("*** 调度后台刷新任务时出错 ***")
                }

                print("*** 调度成功！ ***")
            }
}

问题排查与解决要点 #

• 必须配置后台模式权限
  打开Watch Extension的Info.plist，添加WKBackgroundModes数组，其中包含app-refresh字符串项。没有这个配置，系统不会允许应用执行后台刷新任务。

• 避免两种后台任务方式混用
  你同时使用了SwiftUI的.appRefresh和WatchKit的scheduleBackgroundRefreshAPI，这两种方式不能同时生效：

  • 若选SwiftUI方式：保留.backgroundTask(.appRefresh)，但需要在任务结束时调用context.setTaskCompleted()告知系统任务完成，否则后续调度会被限制；调度仍需通过scheduleBackgroundRefresh请求系统触发。
  • 若选WatchKit Delegate方式：移除SwiftUI的.backgroundTask，并将handle(_ backgroundTasks: Set<WKRefreshBackgroundTask>)方法的private修饰符去掉——系统需要调用这个方法来触发任务处理，私有方法无法被系统访问。

• 注意系统后台调度限制
  Apple Watch的后台刷新不是严格按你设置的时间触发：

  • 仅当设备充电、连接WiFi且处于空闲状态时，系统才会调度任务；
  • 短时间内频繁请求会被系统限流，测试时建议设置30分钟以上的间隔；
  • 测试不要依赖自然等待，可使用Xcode调试菜单中的「Simulate Background Refresh」功能直接触发任务，或在真机上等待系统调度。

• 任务完成必须标记
  无论用哪种方式，处理完任务后必须调用setTaskCompleted()：

  • SwiftUI方式：在await hostingModel.fetchAll()后调用context.setTaskCompleted()；
  • WatchKit方式：在处理完WKApplicationRefreshBackgroundTask实例后调用refreshTask.setTaskCompleted()，并且处理完后要重新调度下一次刷新。

• 修正Delegate中的任务处理方法
  如果用WatchKit方式，handle方法必须是公开的，并且要正确遍历任务集合：

  func handle(_ backgroundTasks: Set<WKRefreshBackgroundTask>) {
      for task in backgroundTasks {
          if let refreshTask = task as? WKApplicationRefreshBackgroundTask {
              print("处理后台刷新任务")
              Task {
                  await hostingModel.fetchAll()
                  refreshTask.setTaskCompleted()
                  // 重新调度下一次刷新
                  hostingModel.scheduleBackgroundRefresh()
              }
          } else {
              // 其他类型任务直接标记完成
              task.setTaskCompleted()
          }
      }
  }
  

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