digital-pilates/docs/BACKGROUND_TASK_TESTING.md

iOS 后台任务测试指南

修复内容

1. 主要问题

• 缺少应用生命周期监听：之前没有在应用进入后台时主动调度任务
• 任务类型不匹配：使用了 BGProcessingTaskRequest 而不是更适合的 BGAppRefreshTaskRequest
• 调度时机不当：只在初始化时调度一次，没有持续调度
• 延迟时间过长：30分钟的延迟导致测试困难

2. 修复方案

AppDelegate.swift

• 添加 applicationDidEnterBackground 方法，在应用进入后台时自动调度任务
• 使用 BGAppRefreshTaskRequest 替代 BGProcessingTaskRequest
• 设置15分钟的最早开始时间

BackgroundTaskBridge.swift

• 改进任务处理逻辑，在任务完成或失败时自动重新调度
• 添加 rescheduleTask 方法确保任务持续执行
• 取消旧任务请求，避免重复调度
• 添加更详细的日志输出

backgroundTaskManagerV2.ts

• 将默认延迟从30分钟减少到15分钟
• 在初始化完成后立即调度第一次任务
• 使用 refresh 类型而不是 processing 类型

测试步骤

在真机上测试（推荐）

1. 准备工作

   # 构建并安装到真机
   npx expo run:ios --device
   

2. 启用后台应用刷新

   • 打开 iOS 设置 > 通用 > 后台应用刷新
   • 确保总开关已打开
   • 找到 "Out Live" 并启用

3. 检查后台任务状态

   • 在应用的统计页面，点击"测试后台任务"按钮
   • 查看后台任务状态是否为"可用"

4. 触发后台任务

   方法一：使用 Xcode 模拟

   # 在 Xcode 中，选择 Debug > Simulate Background Fetch
   # 或者使用命令行
   e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.anonymous.digitalpilates.task"]
   

   方法二：自然触发

   • 将应用切换到后台
   • 等待15-30分钟
   • 系统会在合适的时机自动执行后台任务

5. 验证任务执行

   • 检查是否收到通知（喝水提醒、挑战鼓励等）
   • 查看 Xcode 控制台日志
   • 检查应用内的最后后台检查时间

使用 Xcode 调试

1. 连接设备并运行应用

   # 在 Xcode 中打开项目
   open ios/OutLive.xcworkspace
   

2. 设置断点

   • 在 BackgroundTaskBridge.swift 的 handle(task:) 方法设置断点
   • 在 AppDelegate.swift 的 handleBackgroundTask 方法设置断点

3. 模拟后台任务

   • 运行应用
   • 在 Xcode 菜单中选择 Debug > Simulate Background Fetch
   • 观察断点是否被触发

4. 查看日志

   [AppDelegate] 后台任务已调度，将在15分钟后执行
   [BackgroundTaskBridge] 收到来自 AppDelegate 的后台任务
   [BackgroundTaskBridge] 发送后台任务执行事件到JS
   [BackgroundTaskManagerV2] 收到后台任务事件
   

在模拟器上测试（有限支持）

⚠️ 注意：iOS 模拟器对后台任务的支持有限，某些功能可能无法正常工作。

1. 运行应用

   npx expo run:ios
   

2. 手动触发测试

   • 在应用的统计页面，点击"测试后台任务"按钮
   • 这会模拟后台任务执行，但不会真正测试系统调度

常见问题

1. 后台任务状态显示"受限制"或"被拒绝"

• 检查 iOS 设置中的后台应用刷新是否已启用
• 检查设备的低电量模式是否已关闭
• 重启设备后重试

2. 后台任务从不执行

• 确保应用已完全进入后台（不是挂起状态）
• 等待足够长的时间（至少15-30分钟）
• 检查设备是否有足够的电量和网络连接
• 使用 Xcode 的模拟功能进行测试

3. 日志显示"BGTaskSchedulerErrorDomain 错误1"

• 这在模拟器上是正常的
• 在真机上测试以验证功能

4. 任务执行但没有发送通知

• 检查通知权限是否已授予
• 检查通知设置是否正确
• 查看应用日志确认任务逻辑是否正确执行

调试技巧

1. 启用详细日志

在开发环境中，后台任务调试工具会自动启用，提供详细的日志输出。

2. 检查待处理的任务

在应用中调用 getPendingRequests() 查看已调度的后台任务：

const requests = await BackgroundTaskManager.getInstance().getPendingRequests();
console.log('待处理的后台任务:', requests);

3. 查看最后执行时间

const lastCheck = await BackgroundTaskManager.getInstance().getLastBackgroundCheckTime();
console.log('最后后台检查时间:', new Date(lastCheck));

4. 使用系统日志

# 在终端中查看设备日志
xcrun simctl spawn booted log stream --predicate 'subsystem contains "com.anonymous.digitalpilates"'

最佳实践

1. 在真机上测试：模拟器的后台任务支持有限
2. 耐心等待：系统调度后台任务需要时间，不要期望立即执行
3. 监控电量：低电量模式会限制后台任务
4. 检查设置：确保后台应用刷新已启用
5. 使用 Xcode 模拟：在开发阶段使用 Xcode 的模拟功能快速测试

参考资料

• Apple 官方文档：Background Tasks
• WWDC 2019: Advances in App Background Execution