更新记录

1.0.0（2026-11-04）

• Android：前台服务（dataSync 类型）+ Partial WakeLock（可选）+ 电池优化白名单授权，targetSdk ≥ 33 时自动申请通知权限
• iOS：后台音频模式静音保活，附 beginBackgroundTask 兜底；电池优化相关接口降级处理（系统不支持）
• 接口语义：startKeepAlive 的 success 在 Android 侧代表前台服务真正进入前台；requestIgnoreBatteryOptimization 的 success 仅代表授权页拉起，结果需用 isIgnoringBatteryOptimizations 查询
• 启动失败（含服务 3 秒内未进入前台）通过 fail 回调返回具体原因
• 诊断接口：startKeepAliveMonitor / stopKeepAliveMonitor（Android），实时推送网络变化、深度 Doze 进入/退出、省电模式切换事件，并附带当前状态快照
• 集成要求：服务组件须在项目根目录 AndroidManifest.xml 中声明，详见 README

平台兼容性

uni-app(4.75)

ll-keepalive

uni-app App 端后台保活插件（UTS）。保障 App 退后台后 进程存活、CPU 可运行、网络可访问，适用于需要长期保持 UDP/TCP 连接的场景（如局域网设备监听、心跳上报）。

原理：三重威胁与三层防御

后台断网靠的不是杀进程，而是三套独立机制，本插件分别对应处理：

iOS 没有"系统禁网"机制，只有"App 被挂起"。防挂起（后台音频模式）基本等价于保住网络能力。

平台支持

集成步骤（重要，缺一不可）

1. 项目根目录声明服务（Android 必须）

UTS 插件目录下的 AndroidManifest.xml 只会合并权限，<application> 子节点会被忽略。必须在项目根目录创建 AndroidManifest.xml（HBuilderX 3.6.0+ 支持，云端打包时合并）：

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="你的Android包名">
    <application>
        <service
            android:name="uts.sdk.modules.llKeepalive.KeepAliveService"
            android:exported="false"
            android:foregroundServiceType="dataSync" />
    </application>
</manifest>

• package 填应用的 Android 包名（打包时配置的那个）
• 漏掉此步的典型症状：startForegroundService 调用成功但 3 秒后报「保活服务未能在 3 秒内进入前台」，且 adb shell am start-foreground-service -n 包名/uts.sdk.modules.llKeepalive.KeepAliveService 报 Not found

2. manifest.json 配置

"app-plus" : {
    "distribute" : {
        "android" : {
            "targetSdkVersion" : 33,
            "permissions" : [
                "<uses-permission android:name=\"android.permission.FOREGROUND_SERVICE\"/>",
                "<uses-permission android:name=\"android.permission.FOREGROUND_SERVICE_DATA_SYNC\"/>",
                "<uses-permission android:name=\"android.permission.POST_NOTIFICATIONS\"/>",
                "<uses-permission android:name=\"android.permission.WAKE_LOCK\"/>",
                "<uses-permission android:name=\"android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS\"/>"
            ]
        },
        "ios" : {
            "UIBackgroundModes" : [ "audio" ]
        }
    }
}

targetSdkVersion 建议 ≥ 33：低于 33 时通知权限随安装自动授予（不影响功能），但不符合新规范。

3. 重新制作自定义调试基座

UTS 插件的原生代码与清单都打进基座 APK，修改插件后必须：HBuilderX → 运行 → 运行到手机 → 制作自定义调试基座，然后重新安装。页面热更新不生效于原生代码。

4. 国产 ROM 手动设置（无法纯代码解决）

• 小米/Redmi（HyperOS/MIUI）：设置 → 应用管理 → 本应用 → 开启自启动，省电策略改为无限制。否则服务可能被静默拦截（表现为 startService 成功但服务不运行）
• 华为/OPPO/vivo：类似，需在启动管理/电池设置中放行

快速上手

import { startKeepAlive, stopKeepAlive, isKeepAliveRunning,
    isIgnoringBatteryOptimizations, requestIgnoreBatteryOptimization } from '@/uni_modules/ll-keepalive'

// 启动保活（App 启动时或进入需要保活的页面前调用）
startKeepAlive({
    title: '设备监控运行中',
    content: '保持网络连接',
    wakelock: true,
    success: (res) => {
        // Android：前台服务已真正进入前台；iOS：静音音频已开始
        console.log(res.errMsg)
    },
    fail: (res) => {
        // res.errCode: 1920001(Android) / 1930001(iOS)
        console.error(res.errMsg)
    }
})

// 电池优化白名单（强烈建议，是 Doze 下保住网络的关键）
if (!isIgnoringBatteryOptimizations()) {
    requestIgnoreBatteryOptimization({
        success: () => {
            // 仅代表系统授权页已拉起，用户是否同意需再查询
            console.log('当前白名单状态:', isIgnoringBatteryOptimizations())
        }
    })
}

// 停止保活
stopKeepAlive()

// 查询状态
console.log(isKeepAliveRunning())

API

startKeepAlive(options)

启动保活。Android 启动前台服务（通知 + dataSync 类型），内部附带尽力申请通知权限（申请失败不阻塞启动）；iOS 播放后台静音音频。

stopKeepAlive(options?)

停止保活：移除 WakeLock 并停止前台服务（Android）/ 停止静音音频（iOS）。未运行时调用返回成功（幂等）。

isKeepAliveRunning(): boolean

插件内部运行状态标记。注意：用户手动在系统设置里杀了应用后此状态自然消失；它不做系统级校验。

requestIgnoreBatteryOptimization(options?)

拉起「忽略电池优化」系统授权页。success 仅代表页面拉起成功，用户是否同意需用 isIgnoringBatteryOptimizations() 查询。iOS 固定 fail（errCode 1930001）。

isIgnoringBatteryOptimizations(): boolean

当前是否已在电池优化白名单中。iOS 固定返回 false。

startKeepAliveMonitor(options)

开启诊断监听（仅 Android；iOS 返回 fail），把系统事件实时推送到 onEvent，用于回答"后台到底发生了什么"：

light Doze 无公开广播，不做监听也不做猜测；发送失败时请对照事件流的时间线定位。

stopKeepAliveMonitor()

停止诊断监听并注销系统回调。

验证指南

验证必须区分三层，只验证"进程没死"是不够的：

1. 进程/服务层（没死）：

adb shell dumpsys activity services | findstr KeepAlive

2. 组件注册层（服务真的进了 APK 清单）：

adb shell am start-foreground-service -n 包名/uts.sdk.modules.llKeepalive.KeepAliveService

出现常驻通知 = 注册成功；报 Not found = 根清单漏配或基座未重打。

3. 端到端网络验证（发送式，最硬的证据）

原理：由调用方在 App 内以固定间隔（如每 10 秒）主动发送心跳——UDP 包或 HTTP GET 均可，内容带上序号与时间戳；由任意接收方（HTTP 服务、UDP 监听脚本、IoT 设备等）记录每次到达的间隔。接收方持续按设定间隔收到 = 进程存活 + CPU 可运行 + 网络可用三者同时成立，缺一就会观察到中断。

发送式验证比"被动收包"更宽松：主动流量会持续唤醒 CPU 并刷新 NAT 表项，因此发送侧正常不能直接推出被动接收场景也正常，结论外推时需注意。

对照矩阵：

强制进入 Doze 做实验：

adb shell dumpsys deviceidle whitelist +包名   :: 或 -包名 做对照组
adb shell dumpsys battery unplug
adb shell dumpsys deviceidle force-idle
adb shell dumpsys deviceidle get deep          :: 确认进入 IDLE
:: 此期间调用方的心跳发送保持运行，由接收方记录到达间隔
adb shell dumpsys deviceidle exit              :: 恢复
adb shell dumpsys battery reset

判定标准：看接收方记录的心跳间隔——稳定等于设定间隔 = 全链路存活；出现成倍间隔或彻底中断 = 当前配置组缺失对应防御层。

故障排查

已知限制

• Android 15+ 对 dataSync 类型前台服务有每日约 6 小时的运行限制，超长保活场景可考虑改用 specialUse 类型
• 电池优化白名单在部分深度定制 ROM 上不保证完全生效（如 MIUI 神隐模式），必须配合系统设置放行
• 用户在最近任务里主动划掉应用：部分 ROM 会连带杀死前台服务，无法防御
• iOS 静音音频方案在 App Store 审核中可能被质疑（需说明用途）；测试无影响
• 插件不防御用户主动强制停止（设置 → 强制停止后服务与白名单授权仍在但应用不会自启）

更新日志

见 changelog.md