如何让Socket.io在CapacitorJS原生应用中正常运行？

前置准备 #

• 版本对齐：Socket.io 客户端选用 4.x 稳定版，CapacitorJS 版本不低于 4.0，确保与后端 Socket.io 服务主版本一致，避免协议不兼容。
• 依赖安装：执行命令安装核心依赖

npm install socket.io-client @capacitor/network

通用适配配置 #

客户端初始化 #

优先使用 WebSocket 传输，保留 polling 作为降级方案，避免部分设备 WebView 对 WebSocket 的限制，初始化代码参考：

import { io } from "socket.io-client";
import { Network } from '@capacitor/network';

const socket = io('你的服务端完整地址', {
  transports: ['websocket', 'polling'],
  withCredentials: true,
  reconnection: true,
  reconnectionDelay: 1000,
  reconnectionDelayMax: 5000,
  reconnectionAttempts: 10
});

注意：禁止使用相对路径连接服务端，必须填写完整的可访问地址；本地测试时 Android 模拟器需将 127.0.0.1 替换为 10.0.2.2，iOS 模拟器可直接使用 localhost。

网络状态监听 #

监听设备网络切换事件，网络恢复后主动触发重连，避免 WebView 网络切换后出现连接假死：

Network.addListener('networkStatusChange', status => {
  if (status.connected && !socket.connected) {
    socket.connect();
  }
});

服务端CORS配置 #

需要允许 Capacitor 双端 WebView 的默认源跨域访问，参考配置：

// Node.js 服务端示例
const io = require('socket.io')(server, {
  cors: {
    origin: ['capacitor://localhost', 'http://localhost'],
    credentials: true
  }
});

平台专属配置 #

iOS 端配置 #

1. 打开 iOS 项目 Info.plist 文件，测试环境若使用 HTTP 协议，需添加 ATS 放行规则：

<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsArbitraryLoads</key>
  <true/>
</dict>

2. 若需要后台保持 Socket 连接，在 Xcode 的 Signing & Capabilities 中添加 Background Modes 能力，勾选 Background fetch 与 Remote notifications。
3. 生产环境建议使用 WSS 协议，避免系统安全策略拦截 WebSocket 连接。

Android 端配置 #

1. 打开 AndroidManifest.xml 添加必要权限：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

2. Android 9 及以上版本测试环境若使用 HTTP 协议，需添加网络安全配置：

• 新建 res/xml/network_security_config.xml 文件：

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
  <domain-config cleartextTrafficPermitted="true">
    <domain includeSubdomains="true">你的服务端域名或IP</domain>
  </domain-config>
</network-security-config>

• 在 AndroidManifest.xml 的 application 标签中添加属性：

android:networkSecurityConfig="@xml/network_security_config"

3. 真机测试时关闭设备代理，避免代理拦截导致 WebSocket 握手失败。

兼容性验证 #

模拟器测试 #

• iOS 模拟器：直接使用本地服务端地址测试，验证断网重连、前后台切换、锁屏唤醒场景的连接稳定性。
• Android 模拟器：本地服务端地址替换为 10.0.2.2，分别测试 WebSocket、polling 两种传输模式的连接表现。

真机测试 #

• 确保手机与服务端在同一局域网，使用服务端局域网 IP 测试，验证 4G/WiFi 网络切换、后台切前台场景的连接状态。
• 生产环境使用 WSS/HTTPS 协议，验证公网环境下的连接稳定性。

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