如何在Capacitor项目中使用cordova-plugin-advanced-websocket插件？

1. 修复全局类型缺失问题 #

在项目src目录下新建global.d.ts文件（如果已有则直接追加内容），添加以下类型声明扩展Window接口：

import type { CordovaWebsocketPluginStatic } from 'cordova-plugin-advanced-websocket-types';

declare global {
  interface Window {
    CordovaWebsocketPlugin: CordovaWebsocketPluginStatic;
  }
}

export {};

配置完成后重启TypeScript服务，类型报错即可消失。

2. 完成Capacitor插件同步 #

Cordova插件安装后需要同步到原生工程，执行以下命令：

npx cap sync

3. 正确的调用逻辑 #

注意：必须在平台就绪后再调用插件，Cordova插件仅在原生App环境（iOS/Android）会被注入到window对象，Web端需要做兼容降级。
示例代码：

import { Platform } from '@ionic/angular';
import { CordovaWebsocketOptions } from 'cordova-plugin-advanced-websocket-types';

constructor(private platform: Platform) {
  this.initWebSocket();
}

async initWebSocket() {
  // 等待平台就绪
  await this.platform.ready();
  
  const wsOptions: CordovaWebsocketOptions = {
    url: 'wss://你的自签名服务地址',
    acceptSelfSignedCertificates: true, // 允许自签名证书核心配置
    acceptAnyCa: true,
    // 其他配置按需补充
  };

  if (window.CordovaWebsocketPlugin) {
    // 原生端走插件
    window.CordovaWebsocketPlugin.wsConnect(
      wsOptions,
      (ev) => { /* 收到消息回调 */ },
      (code, reason, wasClean) => { /* 连接关闭回调 */ },
      (wsId) => { /* 连接成功回调 */ },
      (error) => { /* 连接错误回调 */ }
    );
  } else {
    // Web端走原生WebSocket，自签名证书需要用户手动在浏览器信任证书
    const ws = new WebSocket(wsOptions.url);
    ws.onmessage = (ev) => { /* 收到消息回调 */ };
    ws.onclose = (ev) => { /* 连接关闭回调 */ };
    ws.onopen = (ev) => { /* 连接成功回调 */ };
    ws.onerror = (ev) => { /* 连接错误回调 */ };
  }
}

4. 原生端额外配置 #

iOS端 #

在ios/App/App/Info.plist中添加NSAppTransportSecurity配置，允许自签名HTTPS请求：

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

Android端 #

在android/app/src/main/AndroidManifest.xml的application标签添加android:usesCleartextTraffic="true"属性，如有自定义网络安全配置，需确保允许对应域名的自签名证书。

常见问题说明 #

之前直接导入插件源码报错是因为cordova/exec是Cordova运行时专属API，仅在原生App加载cordova.js后才会存在，开发阶段直接导入源码找不到该依赖属于正常情况，无需尝试直接导入插件源码。

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