如何让WebSocket代码同时兼容Node.js与浏览器环境？

以下是几种实用的方案，能让同一段代码无缝兼容Node.js（依赖ws库）和浏览器（原生WebSocket）环境：

1. 基于环境判断的动态导入 #

直接在代码里检测当前运行环境，分别加载对应的WebSocket实现：

ESM 语法版本 #

let WebSocket;
// 判断是否为Node.js环境
if (typeof process !== 'undefined' && process.versions?.node) {
  // 动态导入ws库（避免浏览器解析时报错）
  WebSocket = (await import('ws')).default;
} else {
  // 浏览器环境使用原生WebSocket
  WebSocket = window.WebSocket;
}

// 后续统一使用WebSocket变量即可
const socket = new WebSocket('ws://your-server-url');

CommonJS 语法版本 #

let WebSocket;
if (typeof process !== 'undefined' && process.versions?.node) {
  WebSocket = require('ws');
} else {
  WebSocket = window.WebSocket;
}

这种方案无需额外配置，适合快速实现兼容。

2. 利用打包工具配置模块别名 #

如果你的项目使用Webpack、Vite等打包工具，可以通过别名把ws模块替换为浏览器端的原生WebSocket封装：

Webpack 配置示例 #

// webpack.config.js
const path = require('path');

module.exports = {
  // ...其他配置
  resolve: {
    alias: {
      // 把ws指向自定义的浏览器端封装文件
      'ws': path.resolve(__dirname, './src/utils/browser-websocket.js')
    }
  }
}

然后在browser-websocket.js中导出原生WebSocket：

// src/utils/browser-websocket.js
export default window.WebSocket;

Vite 配置示例 #

// vite.config.js
import { defineConfig } from 'vite';

export default defineConfig({
  resolve: {
    alias: {
      'ws': './src/utils/browser-websocket.js'
    }
  }
});

配置完成后，代码里直接写import WebSocket from 'ws';即可，打包工具会自动在浏览器环境替换为原生实现。

3. 封装统一的WebSocket工具类 #

把环境差异封装到工具类内部，上层业务代码无需关心环境细节：

class WebSocketClient {
  constructor(url) {
    // 根据环境初始化WebSocket实例
    if (typeof process !== 'undefined' && process.versions?.node) {
      const WS = require('ws');
      this.socket = new WS(url);
    } else {
      this.socket = new window.WebSocket(url);
    }
    
    // 统一绑定基础事件（可根据需求扩展）
    this._bindEvents();
  }

  _bindEvents() {
    // 抹平ws库与原生WebSocket的事件参数差异
    this.socket.onmessage = (event) => {
      const data = event.data || event; // ws库的message事件直接传data，原生是event.data
      this.onMessage?.(data);
    };

    this.socket.onopen = () => {
      this.onOpen?.();
    };

    this.socket.onerror = (error) => {
      this.onError?.(error);
    };
  }

  // 统一的发送方法
  send(data) {
    this.socket.send(data);
  }

  // 统一的关闭方法
  close(code, reason) {
    this.socket.close(code, reason);
  }

  // 提供回调接口让上层业务处理事件
  onMessage(callback) {
    this.onMessage = callback;
  }

  onOpen(callback) {
    this.onOpen = callback;
  }

  onError(callback) {
    this.onError = callback;
  }
}

export default WebSocketClient;

使用时直接实例化工具类即可：

const client = new WebSocketClient('ws://your-server-url');
client.onMessage((data) => {
  console.log('收到消息:', data);
});
client.send('Hello Server!');

注意事项 #

• ws库与原生WebSocket的API几乎一致，但存在细微差异（比如message事件的参数），封装时需要注意抹平这些差异；
• 如果使用动态导入，确保你的Node.js版本支持await在顶层作用域（或用IIFE包裹）；
• 打包工具方案需要确保仅在浏览器打包时生效，Node.js环境下仍然使用ws库。

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