iOS基于网络请求的后台通知任务完全不触发问题排查

问题背景 #

开发iOS应用时，需通过后台任务在每日不同时段发送通知，每个通知需先调用API判断是否发送。API已验证可用，但应用安装到设备后，后台任务完全未调度/触发（无API请求日志，也未收到通知）。已遵循WWDC2022视频及Apple官方文档配置，Info.plist中已设置Permitted background task scheduler identifiers，但.backgroundTask场景修饰器内代码从未执行（断点无触发），多数辅助函数测试正常。

一、可能导致任务未触发的原因 #

• 任务标识符不匹配：BGAppRefreshTaskRequest使用的标识符（如SCHEDULE_DAILY_NOTIFICATIONS、shouldSend）必须与Info.plist中Permitted background task scheduler identifiers的条目完全一致，大小写、拼写不能有任何差异。
• 首次任务未提交：scheduleAppRefresh()仅在后台任务回调中调用会导致首次启动无任务提交，系统无法触发后续任务。需在应用启动流程（如App.init或主视图onAppear）中主动调用一次，初始化第一个任务。
• 时间逻辑错误：getNextNotifIndex()可能未正确返回下一个有效小时（如当前时间晚于当日所有通知时间时，是否返回次日最早小时）；earliestBeginDate设置为desiredTime减1分钟，需确认desiredTime是否为未来时间。
• 后台任务代码崩溃：checkValue中使用try!强制解包，一旦请求失败或解析错误会直接崩溃，导致任务终止。建议替换为do-catch处理异常，避免任务意外结束。
• 重复任务冲突：代码中注册了两个逻辑完全重复的.appRefresh任务，但仅提交了其中一个，可能导致系统调度逻辑混乱，建议合并为单一任务标识符。
• 系统限制触发：iOS对后台任务调度有严格限制，应用被强制关闭、设备开启低功耗模式、后台挂起过久、电池电量过低等情况，都会导致系统拒绝调度任务。

二、调试后台任务的方法 #

• Xcode模拟触发：在Xcode的Debug Navigator中，选择Debug > Simulate Background Task，选择对应任务标识符，可直接触发后台任务执行，快速验证代码逻辑。
• 添加结构化日志：在backgroundTask回调、scheduleAppRefresh()、checkValue等关键位置使用os_log（而非print，后台环境print可能无输出）记录详细日志，通过Xcode Console查看任务调度及执行流程。
• 检查Pending任务：调用BGTaskScheduler.shared.getPendingTaskRequests(completionHandler:)获取当前待执行的任务列表，打印确认任务是否成功提交、earliestBeginDate是否正确。
• 真机真实场景调试：后台任务在模拟器上的行为与真机差异较大，建议使用真机调试，且断开电源（连接电源时系统会放宽后台调度限制），模拟用户真实使用场景。
• 查看崩溃日志：若任务因崩溃终止，可在Xcode的Window > Devices and Simulators中查看设备崩溃日志，排查未处理的异常（如强制解包导致的崩溃）。

三、设备端额外设置要求 #

• 开启后台App刷新：在设备设置 > 通用 > 后台App刷新中，确保应用的后台刷新权限已开启，且全局后台App刷新未关闭。
• 关闭低功耗模式：低功耗模式会禁用后台任务调度，需在设置 > 电池中关闭该模式。
• 不要强制关闭应用：用户从App Switcher强制关闭应用后，系统不会调度任何后台任务，直到用户再次手动打开应用。
• 确认通知权限：在设置 > 通知 > 你的应用中，确保已开启通知权限，否则即使任务触发也无法显示通知。

相关代码（优化修正版） #

网络请求代码 #

func checkValue(value: String, hours: Int) async -> Bool {
    // Build url
    var urlString = MY_URL + "/Notification"
    urlString += "?value="+value+"&hours="+String(hours)
    
    guard let url = URL(string: urlString) else {
        print("Error: Invalid URL format.")
        return false
    }

    // Build request
    let urlRequest: URLRequest = {
        var request = URLRequest(url: url, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10)
        request.allHTTPHeaderFields = [
            "Token": API_KEY
        ]
        return request
    }()
    
    // Make request with error handling
    let config = URLSessionConfiguration.background(withIdentifier: SHOULD_SEND)
    config.sessionSendsLaunchEvents = true
    let session = URLSession(configuration: config)
    
    do {
        let (data, response) = try await withTaskCancellationHandler {
            try await session.data(for: urlRequest)
        } onCancel: {
            let task = session.downloadTask(with: urlRequest)
            task.resume()
        }
    
        // Validate response status
        guard let httpResponse = response as? HTTPURLResponse, httpResponse.statusCode == 200 else {
            print("Notification API response status not 200")
            return false
        }

        // Decode response
        return try JSONDecoder().decode(Bool.self, from: data)
    } catch {
        print("Check value failed: \(error.localizedDescription)")
        return false
    }
}

后台任务相关代码 #

struct NotificationConfig: Equatable {
    var id: String
    var type: NotificationType // Custom string-based enum
    var times: [Int]
    var hours: Int
    var title: String
    var body: String
}

var notifications: [NotificationConfig] = [ // Your notification configurations ]

var body: some Scene {
    WindowGroup {
        LandingView()
            .onAppear {
                // Submit first task on app launch
                Task {
                    await scheduleAppRefresh()
                }
            }
    }.backgroundTask(.appRefresh(SCHEDULE_DAILY_NOTIFICATIONS)) {
        let nextHour = await scheduleAppRefresh()
        guard nextHour != -1, let hourNotifications = buildMap()[nextHour] else {
            return
        }
        
        for notif in hourNotifications {
            if await makeCheck(notification: notif)() {
                sendNotification(notif: notif)
            }
        }
    }
}

func scheduleAppRefresh() async -> Int {
    let nextHour = getNextNotifIndex()
    guard nextHour != -1 else {
        print("No valid next notification hour found")
        return -1
    }
    
    let calendar = Calendar.current
    let timeZone = TimeZone.current
    
    var dateComponents = calendar.dateComponents(in: timeZone, from: Date())
    dateComponents.hour = nextHour
    dateComponents.minute = 0
    dateComponents.second = 0
    
    guard var desiredTime = calendar.date(from: dateComponents) else {
        print("Failed to create desired time from components")
        return -1
    }

    // Adjust to next day if desired time is in the past
    if desiredTime <= Date() {
        guard let nextDayTime = calendar.date(byAdding: .day, value: 1, to: desiredTime) else {
            print("Failed to calculate next day time")
            return -1
        }
        desiredTime = nextDayTime
    }
    
    let request = BGAppRefreshTaskRequest(identifier: SCHEDULE_DAILY_NOTIFICATIONS)
    request.earliestBeginDate = calendar.date(byAdding: .minute, value: -1, to: desiredTime)
    
    do {
        try BGTaskScheduler.shared.submit(request)
        print("Scheduled app refresh for: \(desiredTime)")
    } catch {
        print("Failed to schedule app refresh: \(error.localizedDescription)")
    }
    
    return nextHour
}

func buildMap() -> [Int: [NotificationConfig]] {
    var times = [Int: [NotificationConfig]]()
    for notif in notifications {
        for time in notif.times {
            times[time, default: []].append(notif)
        }
    }
    return times
}
    
func getNextNotifIndex() -> Int {
    let timers = buildMap()
    let now = Date()
    let calendar = Calendar.current
    let timeZone = TimeZone.current
    let sortedHours = timers.keys.sorted()
    
    // Find first future hour
    for hour in sortedHours {
        var dateComponents = calendar.dateComponents(in: timeZone, from: now)
        dateComponents.hour = hour
        guard let thisTime = calendar.date(from: dateComponents) else {
            continue
        }
        if thisTime >= now {
            return hour
        }
    }
    
    // Return earliest hour for next day if all today's hours are passed
    return sortedHours.first ?? -1
}
    
func makeCheck(notification: NotificationConfig) -> () async -> Bool {
    return {
        await checkValue(value: notification.type.rawValue, hours: notification.hours)
    }
}
        
func sendNotification(notif: NotificationConfig) {
    UNUserNotificationCenter.current().getNotificationSettings { settings in
        guard settings.authorizationStatus == .authorized else {
            // Request permission if not granted
            UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .sound, .badge]) { granted, _ in
                if granted {
                    self.sendNotificationContent(notif: notif)
                }
            }
            return
        }
        self.sendNotificationContent(notif: notif)
    }
}

private func sendNotificationContent(notif: NotificationConfig) {
    let content = UNMutableNotificationContent()
    content.title = notif.title
    content.body = notif.body
    content.sound = UNNotificationSound.default
    
    let trigger = UNTimeIntervalNotificationTrigger(timeInterval: 1, repeats: false)
    let identifier = "notification_\(notif.times[0])_\(notif.id)"
    let request = UNNotificationRequest(identifier: identifier, content: content, trigger: trigger)
    
    UNUserNotificationCenter.current().add(request) { error in
        if let error = error {
            print("Failed to schedule notification: \(error.localizedDescription)")
        } else {
            print("Notification scheduled successfully for hour \(notif.times[0])")
        }
    }
}

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