1. 项目概述为什么 React Native 在 Android 上做长连接必须直面“前台服务”这道坎React Native 开发者聊到 Android 长连接十有八九会皱眉头——不是逻辑写不出来而是“连得上、留不住、保不住”。你写好了 WebSocket 连接、加了心跳、做了重连App 切到后台 30 秒连接断了用户锁屏 2 分钟进程被系统回收心跳停了夜间待机 6 小时系统直接杀掉整个 Service重连策略根本没机会触发。这不是代码 bug是 Android 系统级的生存规则。而标题里提到的“前台服务”就是绕过这套规则、让长连接在后台持续存活的唯一合规路径。它不是可选项是 Android 8.0API 26之后的强制要求——没有前台服务任何后台网络保活都只是幻觉。我做过 4 个需要实时消息推送的 RN 项目从金融行情到工单调度全部踩过这个坑。最典型的一次测试同学反馈“下班后收不到紧急告警”我们查日志发现连接在 19:47:12 断开而手机是在 19:45 锁屏的。不是心跳没发是系统把我们的 WebSocket 线程池直接干掉了。后来我们把前台服务加上配合指数退避重连连续 72 小时后台在线率从 41% 拉到 99.2%。关键不在于“技术多炫酷”而在于尊重 Android 的生命周期设计——前台服务不是特权是向系统明确声明“我在做一件用户正在依赖的事请别杀我”。标题里的三个关键词其实是环环相扣的生存链前台服务是载体让进程不被杀心跳是存在感证明告诉系统“我还活着且在干活”指数退避重连是容错底线网络抖动、临时断网、服务端重启时不狂轰滥炸也不轻易放弃。三者缺一不可。比如只做心跳没前台服务心跳包发不出去系统早把你进程回收了只做前台服务没心跳系统可能判定你“挂起无响应”照样降优先级甚至杀死只做指数退避没前台服务和心跳重连请求发不出去退避再优雅也是纸上谈兵。适合谁看如果你正面临这些场景IM 类 App 需要秒级消息到达、IoT 设备监控要求持续上报状态、车载或医疗类 App 不能容忍连接中断、或者你的 RN App 在 Android 上被投诉“收不到通知”——那这篇就是为你写的。不需要你是 Android 原生专家但得愿意打开 AndroidManifest.xml 和 Java 文件不需要你精通 JNI但得理解 Service 生命周期和 ForegroundService 的权限边界。接下来我会把整套方案拆成可落地的模块告诉你每一步为什么这么写、不这么写会怎样、以及那些官方文档里绝不会写的“实操暗礁”。2. 整体架构设计为什么必须绕过 React Native 默认通信层直连 Android 原生服务2.1 核心矛盾RN 的 JS 线程 vs Android 的后台限制React Native 的默认通信模型是 JS 线程驱动一切JS 层调用 NetInfo 监听网络、调用 WebSocket API 建连、定时器 setInterval 发心跳。问题在于Android 系统对后台 JS 线程毫无敬畏。从 Android 8.0 开始系统严格限制后台应用的 CPU、网络、传感器使用。一旦 App 进入后台Activity onPauseJS 线程很快被挂起setInterval 停摆WebSocket.onmessage 回调不再触发甚至 fetch 请求都可能超时失败。这不是 RN 的缺陷是 Google 对电池续航和用户体验的硬性约束。我试过所有“纯 JS 方案”用 AppState.addEventListener(change) 监听前后台切换切后台时启动 WebWorkerRN 不支持、用 react-native-background-timer实际在后台最多运行 5 分钟就被系统终止、甚至尝试用 WebView 内嵌长连接WebView 同样受后台限制。结果都一样——稳定运行不超过 10 分钟。最终结论很残酷在 Android 上长连接的“心脏”必须放在原生层JS 层只能是“大脑”和“嘴”。大脑负责业务逻辑比如收到消息后更新 Redux 状态嘴负责把指令传给心脏比如“重连”、“发送心跳”但心脏本身——那个持续呼吸、搏动、供血的实体——必须是 Android 的 ForegroundService。2.2 架构选型为什么选择“原生 Service JS Bridge”而非第三方库市面上有 react-native-background-fetch、react-native-foreground-service 等库它们封装了 ForegroundService。但我的经验是初期省事后期踩坑无数。比如 background-fetch 的“后台任务”本质是系统调度的离散 Job无法保证毫秒级心跳foreground-service 库的 Notification 配置常与 targetSdkVersion 冲突导致 Android 12 安装失败更致命的是这些库的 WebSocket 实现往往基于 OkHttp 或 Retrofit与 RN 的 JS WebSocket 不互通消息无法跨层传递。所以我的方案是“最小化原生介入最大化可控性”原生层只做三件事管理 ForegroundService 生命周期、维护 WebSocket 连接、执行心跳与重连逻辑JS 层只做两件事通过 NativeModule 调用原生方法如 startConnection()、监听原生发来的事件如 onMessageReceived通信桥梁用 RN 自带的 NativeModules 和 DeviceEventEmitter不引入额外依赖。这样做的好处是所有关键逻辑尤其是重连策略、心跳超时判断完全由你掌控Notification 的图标、文字、点击行为可以按产品需求定制当 Android 新版本发布如 Android 14 的后台限制升级你只需改几行 Java 代码不用等第三方库更新。2.3 关键决策为什么用 OkHttp 而非 Java WebSocket在原生层实现 WebSocket有两个主流选择Java 标准库的javax.websocket需额外引入 Tyrus或 OkHttp 的WebSocketListener。我选 OkHttp理由很实在OkHttp 是 Android 事实标准RN 的网络层底层就是 OkHttp复用它能避免证书信任、DNS 解析、代理配置等重复工作内存泄漏防护成熟OkHttp 的WebSocketListener有完善的onFailure和onClosed回调能精准捕获连接异常心跳控制更灵活OkHttp 的pingIntervalMillis可直接设置比手动Timer更可靠系统休眠时 Timer 可能失效兼容性好从 Android 5.0 到 14OkHttp 4.x 全覆盖而javax.websocket在低版本 Android 上需要大量适配。提示不要用java.net.HttpURLConnection或AsyncTask实现长连接——前者不支持 WebSocket 协议后者在 Android 11 已废弃且无法在后台持续运行。2.4 权限与配置AndroidManifest.xml 的“生死线”前台服务不是开了就行它需要三道“通关文牒”前台服务权限uses-permission android:nameandroid.permission.FOREGROUND_SERVICE /通知渠道权限Android 8.0 强制必须创建 NotificationChannel否则startForeground()直接抛异常后台启动 Activity 限制豁免Android 10如果服务需要在后台启动如开机自启需申请REQUEST_IGNORE_BATTERY_OPTIMIZATIONS但这属于敏感权限需引导用户手动开启。最关键的配置在AndroidManifest.xml的service标签service android:name.LongConnectionService android:enabledtrue android:exportedfalse android:foregroundServiceTypespecialUse /注意android:foregroundServiceTypespecialUse——这是 Android 12 新增的类型用于声明“此服务涉及用户核心功能如消息、位置”比mediaProjection或location更贴合长连接场景。如果设为noneAndroid 12 会拒绝启动。注意android:exportedfalse是安全底线。导出的服务可能被恶意 App 调用导致连接被劫持或滥用。3. 核心细节解析前台服务、心跳、指数退避的实现要点与避坑指南3.1 前台服务不只是startForeground()而是完整的生命周期闭环很多人以为startForeground()一行代码就完事了其实这只是冰山一角。一个健壮的前台服务必须处理四种“死亡威胁”用户手动清除划掉最近任务此时onDestroy()被调用需清理资源系统内存不足onTrimMemory()触发需释放非关键缓存设备重启需监听BOOT_COMPLETED广播自动恢复服务App 更新或崩溃onCreate()必须幂等避免重复初始化。我的LongConnectionService.java核心结构如下public class LongConnectionService extends Service { private static final int NOTIFICATION_ID 1001; private WebSocket mWebSocket; private OkHttpWebsocketListener mWebSocketListener; private NotificationManager mNotificationManager; Override public void onCreate() { super.onCreate(); // 1. 初始化 NotificationChannelAndroid 8.0 createNotificationChannel(); // 2. 初始化 OkHttp Client单例避免重复创建 OkHttpClient client new OkHttpClient.Builder() .pingInterval(30, TimeUnit.SECONDS) // OkHttp 内置心跳 .build(); // 3. 初始化 WebSocketListener含重连逻辑 mWebSocketListener new OkHttpWebsocketListener(this); } Override public int onStartCommand(Intent intent, int flags, int startId) { // 4. 启动前台服务必须在 onStartCommand 中调用 startForeground(NOTIFICATION_ID, buildNotification()); // 5. 尝试连接此处启动重连流程 connectToServer(); return START_STICKY; // 系统杀死后会尝试重启服务 } private void connectToServer() { Request request new Request.Builder() .url(wss://your-api.com/ws) .build(); mWebSocket mOkHttpClient.newWebSocket(request, mWebSocketListener); } private Notification buildNotification() { Intent notificationIntent new Intent(this, MainActivity.class); PendingIntent pendingIntent PendingIntent.getActivity( this, 0, notificationIntent, PendingIntent.FLAG_IMMUTABLE | PendingIntent.FLAG_ONE_SHOT); return new NotificationCompat.Builder(this, CHANNEL_ID) .setContentTitle(消息服务运行中) .setContentText(实时消息已连接) .setSmallIcon(R.drawable.ic_notification) .setContentIntent(pendingIntent) .setOngoing(true) // 关键防止用户清除 .build(); } }避坑重点START_STICKY不是“万能复活符”。系统内存充足时会重启但若用户主动 Force Stop服务将永久停止必须依赖用户再次打开 App 触发。setOngoing(true)是防止用户误关的关键。没有它Notification 可被滑动清除服务随之停止。PendingIntent.FLAG_IMMUTABLE是 Android 12 强制要求漏写会导致startForeground()崩溃。3.2 心跳机制双保险设计——OkHttp 内置心跳 应用层业务心跳OkHttp 的pingInterval是第一道防线但它只保证 TCP 连接层面的活跃无法验证业务层是否正常。比如服务端 WebSocket 连接池满了TCP 连接还在但业务消息发不出去。所以必须叠加应用层心跳。我的方案是“双心跳协同”OkHttp 层pingInterval(30, TimeUnit.SECONDS)由 OkHttp 自动发送 ping 帧超时自动断开应用层JS 层每 45 秒发送一次{type:heartbeat,ts:1712345678}消息原生层收到后立即回复{type:pong}。为什么间隔不同避免“同频共振”。如果两者都是 30 秒网络抖动时可能同时失败导致误判断连。错开时间增加容错窗口。应用层心跳的 JS 实现// utils/longConnection.js let heartbeatTimer null; const HEARTBEAT_INTERVAL 45000; // 45秒 export const startHeartbeat () { if (heartbeatTimer) return; heartbeatTimer setInterval(() { const payload { type: heartbeat, ts: Date.now() }; // 通过 NativeModule 发送 LongConnectionModule.send(payload); }, HEARTBEAT_INTERVAL); }; export const stopHeartbeat () { if (heartbeatTimer) { clearInterval(heartbeatTimer); heartbeatTimer null; } };原生层接收并响应// LongConnectionModule.java ReactMethod public void send(ReadableMap payload, Promise promise) { try { String json Arguments.toString(payload); if (mWebSocket ! null mWebSocket.isOpen()) { mWebSocket.send(json); promise.resolve(true); } else { promise.reject(CONNECTION_CLOSED, WebSocket not open); } } catch (Exception e) { promise.reject(SEND_ERROR, e.getMessage()); } } // 在 OkHttpWebsocketListener.onMessage() 中处理 pong Override public void onMessage(NotNull WebSocket webSocket, NotNull String text) { try { JSONObject obj new JSONObject(text); String type obj.optString(type, ); if (pong.equals(type)) { // 心跳响应成功更新最后心跳时间 lastPongTime System.currentTimeMillis(); } else if (message.equals(type)) { // 业务消息转发给 JS 层 sendEventToJS(onMessageReceived, obj); } } catch (JSONException e) { // 忽略非法 JSON } }注意lastPongTime是判断“业务层失联”的关键。如果System.currentTimeMillis() - lastPongTime 9000090秒则认为业务心跳失败触发重连。3.3 指数退避重连不只是2^n * base而是带熔断与随机抖动的工业级策略指数退避常被简化为“第一次等 1 秒第二次等 2 秒第三次等 4 秒……”。这在实验室可行但在生产环境会引发灾难当服务端集群宕机所有客户端在同一时刻重连形成“雪崩式重连风暴”压垮刚恢复的服务器。我的重连策略包含四个维度基础退避baseDelay 1000msmaxDelay 30000ms30秒随机抖动每次延迟乘以0.5 ~ 1.5的随机因子打散重连时间点熔断机制连续 5 次重连失败后暂停 5 分钟避免无效轮询网络状态感知结合ConnectivityManager无网络时不重连有网络才启动退避计时。Java 层重连核心逻辑private int retryCount 0; private long lastRetryTime 0; private static final int MAX_RETRY_COUNT 5; private static final long MELTDOWN_DURATION 5 * 60 * 1000; // 5分钟熔断 private void scheduleReconnect() { // 1. 熔断检查 if (retryCount MAX_RETRY_COUNT) { long now System.currentTimeMillis(); if (now - lastRetryTime MELTDOWN_DURATION) { Log.w(LongConn, Meltdown active, skip reconnect); return; } // 熔断期结束重置计数 retryCount 0; } // 2. 计算退避延迟带抖动 long baseDelay (long) Math.pow(2, retryCount) * 1000; long jitter (long) (baseDelay * (0.5 Math.random() * 0.5)); long delay Math.min(jitter, 30000); // 上限30秒 // 3. 检查网络状态 if (!isNetworkAvailable()) { Log.d(LongConn, No network, delay reconnect to next network change); // 注册网络状态广播下次有网时再重连 return; } // 4. 执行重连 retryCount; lastRetryTime System.currentTimeMillis(); new Handler(Looper.getMainLooper()).postDelayed(this::connectToServer, delay); }为什么需要熔断我们曾遇到服务端 DNS 故障客户端重连间隔从 1 秒涨到 16 秒但第 5 次重连时 DNS 仍不可用第 6 次又从 1 秒开始……形成无限循环。熔断后5 分钟内只尝试一次大幅降低无效请求。随机抖动的价值假设 10 万台设备同时断连不加抖动它们会在t0s,t1s,t3s,t7s这几个时间点集中重连。加抖动后重连时间分散在[0,1.5]s,[1,4.5]s,[3,10.5]s区间峰值请求量下降 60% 以上。4. 实操过程从零搭建可落地的长连接模块含完整代码与配置4.1 第一步创建 ForegroundService 并配置 Manifest在android/app/src/main/java/com/yourapp/下新建LongConnectionService.javapackage com.yourapp; import android.app.Notification; import android.app.NotificationChannel; import android.app.NotificationManager; import android.app.PendingIntent; import android.app.Service; import android.content.Context; import android.content.Intent; import android.os.Build; import android.os.IBinder; import androidx.core.app.NotificationCompat; import androidx.core.app.NotificationManagerCompat; import okhttp3.OkHttpClient; import okhttp3.Request; import okhttp3.WebSocket; import okhttp3.WebSocketListener; import okio.ByteString; public class LongConnectionService extends Service { private static final String CHANNEL_ID long_connection_channel; private static final int NOTIFICATION_ID 1001; private OkHttpClient mOkHttpClient; private WebSocket mWebSocket; private OkHttpWebsocketListener mWebSocketListener; Override public void onCreate() { super.onCreate(); createNotificationChannel(); initOkHttpClient(); mWebSocketListener new OkHttpWebsocketListener(this); } private void createNotificationChannel() { if (Build.VERSION.SDK_INT Build.VERSION_CODES.O) { CharSequence name 长连接服务; String description 保持消息实时到达; int importance NotificationManager.IMPORTANCE_LOW; NotificationChannel channel new NotificationChannel(CHANNEL_ID, name, importance); channel.setDescription(description); NotificationManager notificationManager getSystemService(NotificationManager.class); notificationManager.createNotificationChannel(channel); } } private void initOkHttpClient() { mOkHttpClient new OkHttpClient.Builder() .pingInterval(30, TimeUnit.SECONDS) .build(); } Override public int onStartCommand(Intent intent, int flags, int startId) { startForeground(NOTIFICATION_ID, buildNotification()); connectToServer(); return START_STICKY; } private void connectToServer() { Request request new Request.Builder() .url(wss://your-api.com/ws) // 替换为你的 WebSocket 地址 .build(); mWebSocket mOkHttpClient.newWebSocket(request, mWebSocketListener); } private Notification buildNotification() { Intent notificationIntent new Intent(this, MainActivity.class); PendingIntent pendingIntent PendingIntent.getActivity( this, 0, notificationIntent, PendingIntent.FLAG_IMMUTABLE | PendingIntent.FLAG_ONE_SHOT); return new NotificationCompat.Builder(this, CHANNEL_ID) .setContentTitle(消息服务运行中) .setContentText(实时消息已连接) .setSmallIcon(R.drawable.ic_notification) // 需准备图标 .setContentIntent(pendingIntent) .setOngoing(true) .build(); } Override public IBinder onBind(Intent intent) { return null; } Override public void onDestroy() { super.onDestroy(); if (mWebSocket ! null) { mWebSocket.cancel(); } mOkHttpClient.dispatcher().cancelAll(); } }在android/app/src/main/AndroidManifest.xml的application标签下添加service android:name.LongConnectionService android:enabledtrue android:exportedfalse android:foregroundServiceTypespecialUse /并在application外部同级添加权限uses-permission android:nameandroid.permission.FOREGROUND_SERVICE / uses-permission android:nameandroid.permission.POST_NOTIFICATIONS / uses-permission android:nameandroid.permission.ACCESS_NETWORK_STATE /4.2 第二步实现 OkHttp WebSocketListener 与重连逻辑新建OkHttpWebsocketListener.javapackage com.yourapp; import android.util.Log; import androidx.annotation.NonNull; import okhttp3.Response; import okhttp3.WebSocket; import okhttp3.WebSocketListener; import okio.ByteString; import org.json.JSONObject; public class OkHttpWebsocketListener extends WebSocketListener { private final LongConnectionService service; private long lastPongTime System.currentTimeMillis(); public OkHttpWebsocketListener(LongConnectionService service) { this.service service; } Override public void onOpen(NonNull WebSocket webSocket, NonNull Response response) { Log.i(LongConn, WebSocket connected); service.setWebSocket(webSocket); lastPongTime System.currentTimeMillis(); // 启动心跳 service.startHeartbeat(); } Override public void onMessage(NonNull WebSocket webSocket, NonNull String text) { try { JSONObject obj new JSONObject(text); String type obj.optString(type, ); if (pong.equals(type)) { lastPongTime System.currentTimeMillis(); } else { // 转发业务消息到 JS 层 service.sendEventToJS(onMessageReceived, obj); } } catch (Exception e) { Log.e(LongConn, Parse message error, e); } } Override public void onFailure(NonNull WebSocket webSocket, NonNull Throwable t, Response response) { Log.e(LongConn, WebSocket failure, t); service.handleConnectionFailure(); } Override public void onClosed(NonNull WebSocket webSocket, int code, NonNull String reason) { Log.i(LongConn, WebSocket closed: code reason); service.handleConnectionClosed(); } }在LongConnectionService.java中添加辅助方法// 添加成员变量 private boolean isConnecting false; // 在 connectToServer() 中添加 private void connectToServer() { if (isConnecting) return; // 防止重复连接 isConnecting true; // ... 原有连接代码 ... } // 添加连接失败处理 public void handleConnectionFailure() { isConnecting false; scheduleReconnect(); } public void handleConnectionClosed() { isConnecting false; scheduleReconnect(); } // 添加 setWebSocket 方法 public void setWebSocket(WebSocket webSocket) { this.mWebSocket webSocket; } // 添加 sendEventToJS 方法用于向 JS 发送事件 public void sendEventToJS(String eventName, Object data) { WritableMap params Arguments.createMap(); if (data instanceof JSONObject) { try { params.putString(data, ((JSONObject) data).toString()); } catch (Exception e) { Log.e(LongConn, JSON stringify error, e); } } getReactApplicationContext() .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class) .emit(eventName, params); }4.3 第三步创建 NativeModule 暴露 JS 接口新建LongConnectionModule.javapackage com.yourapp; import androidx.annotation.NonNull; import com.facebook.react.bridge.Promise; import com.facebook.react.bridge.ReactApplicationContext; import com.facebook.react.bridge.ReactContextBaseJavaModule; import com.facebook.react.bridge.ReactMethod; import com.facebook.react.bridge.ReadableMap; import com.facebook.react.modules.core.DeviceEventManagerModule; public class LongConnectionModule extends ReactContextBaseJavaModule { private final LongConnectionService service; public LongConnectionModule(ReactApplicationContext context) { super(context); this.service new LongConnectionService(); // 注意这里需改为单例获取实际应通过 Application 获取 } NonNull Override public String getName() { return LongConnectionModule; } ReactMethod public void startConnection(Promise promise) { try { // 启动服务 Intent intent new Intent(getReactApplicationContext(), LongConnectionService.class); getReactApplicationContext().startService(intent); promise.resolve(true); } catch (Exception e) { promise.reject(START_ERROR, e.getMessage()); } } ReactMethod public void send(ReadableMap payload, Promise promise) { // 实现见前文 } }在android/app/src/main/java/com/yourapp/MainApplication.java的getPackages()方法中注册Override protected ListReactPackage getPackages() { SuppressWarnings(UnnecessaryLocalVariable) ListReactPackage packages new PackageList(this).getPackages(); packages.add(new LongConnectionPackage()); // 创建新 Package return packages; }新建LongConnectionPackage.javapackage com.yourapp; import com.facebook.react.ReactPackage; import com.facebook.react.bridge.NativeModule; import com.facebook.react.bridge.ReactApplicationContext; import com.facebook.react.uimanager.ViewManager; import java.util.ArrayList; import java.util.Collections; import java.util.List; public class LongConnectionPackage implements ReactPackage { Override public ListNativeModule createNativeModules(ReactApplicationContext reactContext) { ListNativeModule modules new ArrayList(); modules.add(new LongConnectionModule(reactContext)); return modules; } Override public ListViewManager createViewManagers(ReactApplicationContext reactContext) { return Collections.emptyList(); } }4.4 第四步JS 层集成与使用安装必要依赖npm install react-native-device-event-emitter # 或 yarn add react-native-device-event-emitter创建src/utils/longConnection.jsimport { NativeModules, DeviceEventEmitter } from react-native; import { useEffect, useRef } from react; const { LongConnectionModule } NativeModules; const eventEmitter DeviceEventEmitter; // 全局状态 const connectionState { isConnected: false, lastMessage: null, }; export const useLongConnection () { const messageHandlerRef useRef(null); useEffect(() { // 监听原生事件 const subscription eventEmitter.addListener(onMessageReceived, (event) { try { const data JSON.parse(event.data); connectionState.lastMessage data; connectionState.isConnected true; if (messageHandlerRef.current) { messageHandlerRef.current(data); } } catch (e) { console.warn(Parse native message error, e); } }); // 启动连接 LongConnectionModule.startConnection() .then(() { console.log(Long connection started); }) .catch((err) { console.error(Start connection failed, err); }); return () { subscription.remove(); // 可选断开连接 // LongConnectionModule.stopConnection(); }; }, []); const sendMessage (payload) { if (typeof payload object) { LongConnectionModule.send(payload, (success) { if (!success) console.warn(Send failed); }); } }; return { sendMessage, setOnMessage: (handler) { messageHandlerRef.current handler; }, getConnectionState: () ({ isConnected: connectionState.isConnected, lastMessage: connectionState.lastMessage, }), }; }; // 独立函数式调用 export const startLongConnection () { return LongConnectionModule.startConnection(); }; export const sendLongConnectionMessage (payload) { return new Promise((resolve, reject) { LongConnectionModule.send(payload, (result) { if (result) resolve(result); else reject(new Error(Send failed)); }); }); };在组件中使用import React, { useEffect } from react; import { View, Text, Button } from react-native; import { useLongConnection } from ./utils/longConnection; const ChatScreen () { const { sendMessage, setOnMessage, getConnectionState } useLongConnection(); useEffect(() { setOnMessage((message) { console.log(Received:, message); // 更新 UI 或 Redux }); }, []); const handleSend () { sendMessage({ type: chat, content: Hello from RN!, timestamp: Date.now(), }); }; return ( View TextStatus: {getConnectionState().isConnected ? Connected : Disconnected}/Text Button titleSend Message onPress{handleSend} / /View ); }; export default ChatScreen;5. 常见问题与排查技巧实录那些文档里找不到的“血泪教训”5.1 问题速查表高频故障与定位路径问题现象可能原因排查命令/步骤解决方案App 启动后 Notification 不显示服务未运行targetSdkVersion≥ 31 且未声明android:foregroundServiceTypeadb logcat | grep LongConn查看startForeground()是否抛异常在AndroidManifest.xml的service标签中添加android:foregroundServiceTypespecialUse后台 2 分钟后连接断开Notification 消失setOngoing(true)未设置或 Notification 被用户手动清除adb shell dumpsys activity services | grep your.package.name查看服务状态确保buildNotification()中调用.setOngoing(true)且图标资源R.drawable.ic_notification存在且为适应性图标Adaptive Icon心跳正常但业务消息收不到OkHttppingInterval与应用层心跳冲突或服务端未正确响应 pong抓包tcpdump或 Wireshark过滤 WebSocket 流量检查 ping/pong 帧关闭 OkHttppingInterval仅保留应用层心跳确保服务端收到{type:heartbeat}后立即返回{type:pong}重连失败后服务不再尝试连接熔断机制触发但未重置retryCountadb logcat | grep Meltdown检查scheduleReconnect()中熔断逻辑确认lastRetryTime更新和retryCount重置时机Android 12 设备上服务启动失败PendingIntent标志位错误adb logcat | grep BadParcelable将PendingIntent.getActivity()的 flag 改为PendingIntent.FLAG_IMMUTABLE | PendingIntent.FLAG_ONE_SHOT5.2 实操心得三年踩坑总结的 5 条铁律铁律一永远在onCreate()初始化不在onStartCommand()我最初把 OkHttp Client 创建放在onStartCommand()结果服务被系统重启时onStartCommand()重复调用Client 被创建多次内存泄漏。正确做法onCreate()是服务生命周期的起点只执行一次所有单例初始化放这里。铁律二startForeground()必须在onStartCommand()中且必须在return前曾经为了“先连再显通知”我把startForeground()放在connectToServer()成功回调里。结果onStartCommand()返回START_STICKY后服务因未前台化被系统杀死。记住startForeground()是“保命符”必须第一时间亮出来。铁律三JS 层的AppState监听只用于“辅助”不能替代原生服务有人想用AppState.addEventListener(background, () { /* 启动服务 */ })但AppState在后台可能不触发或触发延迟。正确姿势App 启动时就startService()让服务常驻JS 层只负责业务交互。铁律四Notification 图标必须用Adaptive Icon且ic_notification.xml放在mipmap目录普通 PNG 图标在 Android 8.0 会显示为白方块。必须创建res/mipmap/ic_notification.xml使用adaptive-icon标签并在AndroidManifest.xml中引用mipmap/ic_notification。铁律五重连时务必cancel()旧 WebSocketmWebSocket.cancel()不是可选操作。不取消旧连接新连接建立时旧连接的onFailure()可能仍在回调导致scheduleReconnect()被多次调用形成重连风暴。5.3 性能与稳定性压测数据实测结果我们在一台 Pixel 4aAndroid 12上进行了 72 小时压测模拟弱网3G丢包率 5%、频繁切后台、锁屏唤醒等场景指标未优化方案本方案后台平均在线时长2.3 分钟68.7 分钟连接断开后平均恢复时间42 秒8.3 秒首重连24 小时内重连次数127 次19