欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net
前言
虽然 dart:io 提供了 WebSocket 类，dart:html 也提供了 WebSocket 类，但这种"分裂"的 API 设计让编写跨平台（同时支持 Mobile/Web/Desktop）的代码变得异常痛苦。你需要使用条件导入 (if (dart.library.io) ...) 来分别处理。
web_socket 库就是为了解决这个问题而诞生的。它提供了一个统一的、平台无关的 WebSocket 接口。
无论你的代码运行在 Android、iOS、Web 还是 OpenHarmony 上，它都会自动选择最底层的实现（在鸿蒙上通常是 dart:io），而从上层看代码完全一致。
对于 OpenHarmony 开发者，这意味着你可以直接复用现有 Flutter 项目中的 WebSocket 逻辑，无需为鸿蒙单独写条件编译分支。
一、核心原理
web_socket 本质上是一个 Facade（外观模式）。
调用
自动检测
Native/OpenHarmony
Web
你的业务代码
web_socket 统一接口
平台分发
dart:io WebSocket
HTML5 WebSocket API
二、OpenHarmony 适配说明
在 OpenHarmony 上，Dart 运行时完全支持 dart:io。
因此，web_socket 库会透明地回退到基于 dart:io 的实现。
权限配置 ：
同样，别忘了在 module.json5 中申请 ohos.permission.INTERNET。
HTTPS/WSS 证书问题 ：
鸿蒙系统对 SSL 证书校验较为严格。如果连接开发环境的自签名 WSS 服务，可能会抛出 HandshakeException。在开发阶段，你可能需要重写 SecurityContext 来信任所有证书（仅限 Debug 模式）。
三、基础用例
3.1 建立连接
dart
import 'package:web_socket/web_socket.dart';
void connect() async {
final uri = Uri.parse('wss://echo.websocket.org');
// 💡 统一接口：会自动根据 Platform 选择最底层的端侧实现
final socket = await WebSocket.connect(uri);
print('✅ 握手成功');
// 💡 监听消息：基于 Stream 的响应式处理
socket.events.listen((event) {
if (event is TextDataReceived) {
print('收到文本: ${event.text}');
} else if (event is BinaryDataReceived) {
print('收到二进制: ${event.data.length} 字节');
}
});
}
3.2 发送数据
dart
void sendData(WebSocket socket) {
// 发送文本
socket.sendText('Hello OpenHarmony!');
// 发送二进制
socket.sendBytes([0x01, 0x02, 0x03]);
}
3.3 关闭连接
dart
void close(WebSocket socket) async {
await socket.close(1000, 'Normal Closure');
print('连接已关闭');
}
四、完整实战示例：鸿蒙实时消息接收器
本示例演示了一个健壮的消息客户端，包含连接初始化、消息分类处理以及关闭资源释放生命周期。
dart
import 'package:web_socket/web_socket.dart';
class OhosChatClient {
WebSocket? _socket;
bool _isConnected = false;
/// 启动连接
Future<void> init() async {
try {
_socket = await WebSocket.connect(
Uri.parse('wss://api.ohos-chat.com/v1'),
timeout: Duration(seconds: 10),
);
_isConnected = true;
_listen();
} catch (e) {
print('❌ 连接失败: $e');
}
}
void _listen() {
_socket?.events.listen((event) {
if (event is TextDataReceived) {
_handleText(event.text);
} else if (event is CloseReceived) {
_isConnected = false;
print('🔌 服务器断开连接');
}
});
}
void _handleText(String message) {
// 业务逻辑处理...
}
/// 资源回收
void dispose() {
_socket?.close();
}
}
五、总结
web_socket 是 Dart 官方为了抹平平台差异而推出的标准化库。
建议所有新开发的 Flutter 项目，如果不需要使用 Socket.io 或 STOMP 等上层协议，而是直接使用原始 WebSocket，首选使用 package:web_socket 而不是直接用 dart:io。
对于 OpenHarmony 开发，它保证了你的网络层代码是未来兼容的（Future-proof），无论未来鸿蒙底层的网络栈如何演进，标准接口层都将保持稳定。