最近在做一个跨端数据同步项目服务端用 Node.js 的 ws 库做 WebSocket 网关浏览器端和多个 Node.js 客户端同时接入。需求本身不复杂但真正跑起来之后我发现所有麻烦都集中在同一个点上二进制数据到底什么时候是 ArrayBuffer什么时候是 Buffer。浏览器端原生 WebSocket 收二进制默认给 ArrayBufferNode.js 端 ws 库默认给 Buffer两个客户端一混服务端处理逻辑就变成了“先判断类型再手动转换”代码写得很丑排查还费劲。后来我把这块彻底理顺了总结出 5 个高效技巧基本可以告别二进制数据处理的那些别扭时刻。这篇指南就是基于这些实战经验写的适合正在用 ws 做实时通信、文件传输、音视频流的开发者无论你卡在类型转换、内存暴涨还是大数据分块都应该能在这里找到答案。1. 先看清 ws 库里的二进制“双轨制”很多人一上来就想着怎么把 ArrayBuffer 转成 Buffer、把 Buffer 转回 ArrayBuffer这其实是没抓到重点。要真正处理好这两个类型得先理解它们为什么同时存在以及 ws 库到底在什么环节使用它们。1.1 浏览器端和 Node.js 端的数据表示天然割裂ArrayBuffer 是 ECMAScript 标准里的通用二进制缓冲区浏览器端所有二进制能力都建立在它之上比如 TypedArray、DataView、Blob底层都是 ArrayBuffer 的视图或者引用。而 Buffer 是 Node.js 为了高性能处理二进制数据做的扩展它继承自 Uint8Array但额外提供了很多方便的方法比如 readUInt32BE、writeInt16LE、subarray、toString 等等同时还配合 Node.js 的内存池机制让频繁小数据分配更高效。问题在于同一份二进制数据在浏览器端和 Node.js 端天然会以不同的形态出现。浏览器端的 WebSocket API 里binaryType 可以设置成arraybuffer或者blob没有 Buffer 这个选项。而 ws 库跑在 Node.js 环境里默认会把收到的二进制数据处理成 Buffer。所以同一个 WebSocket 服务面对浏览器客户端和 Node.js 客户端时消息回调中的 data 类型是不一样的。1.2 ws 怎么决定你收到的是什么类型ws 库接收端的类型控制其实藏在实例的一个属性里binaryType。默认值是nodebuffer你可以改成arraybuffer还可以设置成fragments。这个属性在 WebSocketServer 的连接对象上也可以单独设置意味着同一个服务端可以让某些连接收 Buffer让另一些连接收 ArrayBuffer。发送端反而没那么讲究ws 的 send 方法接受字符串、Buffer、TypedArray、DataView、ArrayBuffer 这些类型。发送前 ws 会统一做内部处理对于 ArrayBuffer它会构造一个数据帧来承载而在接收端根据对端实例的 binaryType你看到的类型可能完全不同。这里我整理了一个比对表方便你快速理解发送端传入类型接收端 binaryType nodebuffer接收端 binaryType arraybufferBufferBuffer 原样收到会转成 ArrayBufferArrayBufferws 用其底层数据生成 BufferArrayBuffer 原样收到Uint8Array会生成 Buffer 视图转成 ArrayBufferstring 普通字符串如果是文本帧回调里拿到字符串同左字符串不走 binaryType我实测下来的结论是binaryType 只在接收方向生效而且只针对二进制帧文本帧永远是字符串。很多人纠结的“为什么我明明发的是 ArrayBuffer对端却收到 Buffer”本质就是对端 binaryType 默认是 nodebuffer。1.3 最容易被忽略的 isBinary 参数ws 的消息回调是socket.on(message, (data, isBinary) {})第二个参数 isBinary 表面上看只是告诉你当前帧是不是二进制帧但实际排查时特别有用。当你收到一段数据不确定它是文本还是二进制并且需要区分“空字符串”和“0 字节 Buffer”时isBinary 能帮你做第一层判断。空字符串和 0 字节 Buffer 在逻辑上完全不同但只看 data 类型和 length 容易混淆。有了 isBinary就可以干脆地把空文本帧和空二进制帧区分开。这一点在我做心跳和空消息处理时踩过坑后面你会看到具体案例。2. 技巧一接收数据前先明确目标类型而不是事后转换这是我认为最值得养成的习惯。你能在 ws 实例上直接设置 binaryType那就不要让二进制数据以“错误类型”送到业务层然后再来回转换。转一次就是一次拷贝拷贝多了性能自然差。2.1 在连接建立时就把类型定好服务端每来一个连接可以根据客户端协商结果设置 binaryTypeconst WebSocket require(ws); const wss new WebSocket.Server({ port: 8080 }); wss.on(connection, (socket, req) { // 假设某个子协议表明这个客户端需要 ArrayBuffer // 这里在连接阶段就明确后面不用每次消息都处理类型差异 socket.binaryType arraybuffer; socket.on(message, (data, isBinary) { if (!isBinary) { // 处理文本... return; } // 此时 data 必然是 ArrayBuffer const uint8 new Uint8Array(data); // 直接交给只接受 ArrayBuffer 的解码库 decode(uint8); }); });客户端同样可以在建立连接后立刻设置const WebSocketClient require(ws); const client new WebSocketClient(ws://localhost:8080); client.binaryType arraybuffer; client.on(message, (data, isBinary) { if (isBinary) { // 这里拿到的就是 ArrayBuffer不需要再自己转了 } });2.2 为什么说这样是零成本关键在于 ws 内部在接收数据时receiver 已经持有底层 Buffer 了。当 binaryType 是nodebuffer时它直接把 Buffer 交给你当 binaryType 是arraybuffer时它相当于基于底层 Buffer 构造一个 ArrayBuffer 返回。这个构造过程在部分场景下只是视图层面的转换并不是一份新的完整拷贝。而如果你保持默认的 nodebuffer等消息到了业务层再调用new Uint8Array(data)或者Buffer.from(data)可能就绕了远路。尤其是基于 Buffer 的丰富方法比如 subarray、readUInt32BE等你需要这些功能时正确做法是不要把你的数据转成 Buffer而是直接在连接上设置binaryType nodebuffer让它一开始就是 Buffer。反之如果你接了一个只认 ArrayBuffer 的加解密库就把 binaryType 设成arraybuffer避免每次消息都要额外转一次。2.3 自定义混合协议怎么处理“文本头 二进制体”真实业务里经常遇到这种情况一条消息里既要有 JSON 元信息又要有大段的二进制负载。最省事的方案是发两个消息一个文本元信息一个二进制数据。但这样会引入关联性问题接收端很难保证两条消息的先后顺序也没法原子地处理。我用的方案是自描述二进制协议一条消息头部固定是 4 字节的长度字段表示 JSON 元数据的字节长度随后紧跟 JSON 字符串再往后才是真正的二进制数据。把元信息和负载放进同一个二进制帧里。发送端可以这样构造function buildBinaryMessage(meta, payloadBuffer) { const metaBuf Buffer.from(JSON.stringify(meta), utf8); // 使用 Buffer.alloc copy 来拼装避免多段分散 const totalLen 4 metaBuf.length payloadBuffer.length; const messageBuf Buffer.allocUnsafe(totalLen); messageBuf.writeUInt32BE(metaBuf.length, 0); metaBuf.copy(messageBuf, 4); payloadBuffer.copy(messageBuf, 4 metaBuf.length); return messageBuf; }接收端如果统一用 nodebuffer处理起来很顺socket.on(message, (data, isBinary) { if (!isBinary) return; // data 此时一定是 Buffer const metaLen data.readUInt32BE(0); const meta JSON.parse(data.subarray(4, 4 metaLen).toString(utf8)); const payload data.subarray(4 metaLen); handleMetaAndPayload(meta, payload); });注意一个关键细节如果你的 binaryType 设成了arraybuffer那 data 是 ArrayBuffer没有readUInt32BE方法。这时候需要先用Buffer.from(data)拿到 Buffer 视图再走同样的解析流程。所以我的建议是在代码里统一约定一种接收类型不要一会儿 nodebuffer 一会儿 arraybuffer否则很容易出现“这个连接能跑那个连接报错”的诡异问题。3. 技巧二大文件传输时别等整个消息拼完用流式处理很多人用 ws 传输大文件时习惯一次性把文件读进内存再一次性 send 出去。对十几兆的文件问题不大但到了几百 MB 或者 GB 级别内存和速度都会出问题。ws 库本身就提供了流式方案但平时看到得太少。3.1 为什么不能默认“收到完整消息再处理”ws 的消息事件语义是等一个完整的 WebSocket 消息接收完成才会触发 message 回调。也就是说哪怕一个消息被拆成了很多个底层数据帧ws 内部也会先把它们拼装成一个完整的 Buffer然后才交给你。面对超大文件时这个“完整 Buffer”会占掉与文件同等大小的内存。比如一次推 800MB 的日志文件服务端光接收就得预留 800MB 以上的堆内存做拼装这还没算文件写入时的额外开销。除非你的业务本身就需要完整数据才能解析否则对大二进制文件来说流式处理是更合理的方案。3.2 用 createWebSocketStream 把连接的收发变成流ws 里有个高层封装叫做createWebSocketStream。它能把一个 WebSocket 连接包装成标准的 Duplex 流从此你可以直接 pipe 到文件流或者与任意 Transform 流串联。const { createWebSocketStream } require(ws); const fs require(fs); wss.on(connection, (socket) { // 接收大文件时直接把数据流写入本地文件 const duplex createWebSocketStream(socket); const output fs.createWriteStream(./received.bin); duplex.pipe(output); duplex.on(error, (err) { console.error(stream error:, err.message); }); });发送端也可以把文件流通过 WebSocket 发出去const { createWebSocketStream } require(ws); const fs require(fs); const client new WebSocketClient(ws://localhost:8080); client.on(open, () { const duplex createWebSocketStream(client); const input fs.createReadStream(./huge-file.bin); input.pipe(duplex); });这样处理之后内存占用基本是恒定的因为 Node.js 的流机制自带背压读快写慢时会自动暂停读取不会一股脑把整个文件塞进内存。3.3 用 fragments 模式手动分块如果你不想引入流式封装还想保留 message 事件的结构ws 还有一种折中方案把 binaryType 设置成fragments。在这种模式下回调里的 data 不再是拼装好的完整 Buffer而是一个由多个分片 Buffer 组成的数组。socket.binaryType fragments; socket.on(message, (fragments, isBinary) { if (!isBinary) return; // fragments 是一个数组按帧顺序排列 for (const frag of fragments) { // 这里可以逐个写盘避免一次大拼装 } });这种方式适合那种“需要流式落盘但又不希望引入完整 stream 抽象”的场景。需要注意ws 仍然会在内部缓存这些 fragments 直到整个消息接收完毕它不会让你在消息还没结束前逐帧处理。所以它节省的不是总的缓存量而是省去了把多个帧合并成一个大 Buffer 时额外分配的那份连续内存以及由此引发的内存碎片。我实际体验下来现代 Node.js 流已经足够顺手如果确实要从零处理大文件优先用 createWebSocketStreamfragments 模式更适合那些想自己控制帧级逻辑的场景。4. 技巧三ArrayBuffer 与 Buffer 互转必须分清零拷贝和深拷贝尽管我前面一直强调尽量在接收端一次到位但总会有需要兼容老代码、第三方库或者浏览器端旧逻辑的时候。ArrayBuffer 和 Buffer 之间的转换可以说是这类问题里踩坑最多的地方。4.1 Buffer.from(arrayBuffer)不是深拷贝而是共享内存一个很棒的技巧是当你在 Node.js 端收到 ArrayBuffer 时直接调用Buffer.from(arrayBuffer)得到的 Buffer 实际上是对同一块底层内存的视图。它不会复制数据。你修改这个 Buffer 的内容原 ArrayBuffer 也会跟着变反之亦然。这个行为与Buffer.from(字符串)完全不同后者是会分配新内存的。所以当 API 需要 Buffer而手里只有 ArrayBuffer 时放心使用const arrayBuffer new ArrayBuffer(1024); const view new Uint8Array(arrayBuffer); view[0] 42; const buf Buffer.from(arrayBuffer); // 共享内存 buf[0] 100; console.log(view[0]); // 100确实是同一块内存注意这里的 Buffer.from 并不复制字节但也不代表零开销。用来创建视图的基础对象分配仍然存在只是它没有移动数据。4.2 真正的坑Buffer.from(Buffer) 是深拷贝与上面不同Buffer.from(existingBuffer)会创建一份全新的拷贝。接受已有的 Buffer 时如果你不小心写出了类似Buffer.from(rawData)的代码实际上等于重新复制了一整块数据。在大消息高频场景下这会造成不必要的内存和 CPU 开销。正确复用已有 Buffer 的方式是直接使用原变量或者用rawData.subarray()生成一个视图后者同样不复制底层数据。const raw Buffer.alloc(1024); // 错误额外复制了一份 const copy1 Buffer.from(raw); // 正确直接使用 const same raw; // 正确需要切片时用 subarray 视图 const sliceView raw.subarray(0, 512);4.3 Buffer 转 ArrayBuffer 的 byteOffset 陷阱Buffer 转 ArrayBuffer 时最容易犯错的是直接取buf.buffer属性。由于 Node.js 内部存在 Buffer 池小 Buffer 很可能是某个大 ArrayBuffer 的一个切片视图。如果直接取 buffer 属性你拿到的可能是整块内存池而不是这个 Buffer 对应的数据区域。安全的方式是手动切片function toArrayBuffer(buffer) { // 如果当前 Buffer 就是完整独立的内存块直接复用底层 buffer if (buffer.byteOffset 0 buffer.byteLength buffer.buffer.byteLength) { return buffer.buffer; } // 否则需要切片slice 会返回一个新的 ArrayBuffer return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset buffer.byteLength); }这里的 slice 语义是 ArrayBuffer.prototype.slice它返回新的 ArrayBuffer并复制数据。也就是说Buffer 转 ArrayBuffer 很难做到完全没有拷贝除非当前 Buffer 恰好是整个底层内存块的完整视图。4.4 正确选择视图还是拷贝我把常见操作整理成了一张速查表你直接按需求选操作方法是否拷贝建议ArrayBuffer 当 Buffer 用Buffer.from(arrayBuffer)否首选零拷贝Buffer 复制一份独立数据Buffer.from(buffer)是确认需要独立快照时用Buffer 获取切片buffer.subarray(start, end)否比 slice 好不复制Buffer 转 ArrayBuffer 安全版buffer.buffer.slice(byteOffset, byteOffset byteLength)是通用安全避免池污染Buffer 恰好独立直接返回 buffer.buffer否大 Buffer 场景常见Buffer 转 Uint8Array 视图new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength)否类型化访问我自己在项目里就遇到过一个大坑某次把收到的消息 Buffer 直接当作 ArrayBuffer 传给一个加解密接口因为那个 Buffer 恰好是 Buffer 池的切片导致加解密库不仅读到了当前消息的数据还把池子里其他无关数据也一并处理了排查了很久才定位到 byteOffset 上。从那以后所有 Buffer 转 ArrayBuffer 的代码我都走统一的 toArrayBuffer 函数。5. 技巧四发送端优化让大消息飞得更稳接收端处理方式理顺之后发送端同样藏着一些值得注意的细节。很多人只管调 send忽略了 ws 发送数据时在内存和时序上的行为导致数据错乱或者内存峰值过高。5.1 send 之后不要再修改原 Bufferws 的 send 是异步操作。你把一个 Buffer 传给 sendws 并不会立刻深拷贝一份再排队而是先把引用放入发送队列之后才会编码成 WebSocket 帧写入内核。因此在 send 回调触发之前不要修改原来的 Buffer。const payload Buffer.alloc(1024 * 1024); const client new WebSocketClient(ws://localhost:8080); client.send(payload, (err) { // 走到这里表示 payload 已经被序列化并交给底层发送之后才可以安全复用 if (err) return; // 可以在这里对 payload 做后续处理 });这个规则看起来很简单但在并发发送或循环发送时容易被忽略。我见过有同事在循环体内复用同一个 Buffer然后连续调用多次 send第二个 send 的时候第一个还没发完结果不仅数据被覆盖报错还极其难查。解决方法是每轮发送都用一个独立的 subarray 视图并且在上一次回调后再发起下一次发送。5.2 用 bufferedAmount 感知背压避免无限堆积当发送速度远大于底层 TCP 的消费速度时ws 内部发送队列会不断膨胀。bufferedAmount属性表示当前等待发送但尚未写入内核的字节数。你可以利用它来实现一个简单的流控const HIGH_WATER_MARK 16 * 1024 * 1024; // 16MB function safeSend(socket, data, callback) { if (socket.readyState socket.OPEN socket.bufferedAmount HIGH_WATER_MARK) { socket.send(data, callback); } else { // 缓冲太多暂时不要发送等队列消化后再继续 setTimeout(() safeSend(socket, data, callback), 100); } }这种方案在后台批量推送文件数据时很有用。如果没有背压控制客户端网络慢的时候Node.js 进程内存会随着发送队列一起长大。虽然 TCP 层也有缓冲区但业务层配合 bufferedAmount 做限速能有效避免发送方把自己打爆。5.3 大 Buffer 分块发送降低内存峰值一次把整个 100MB 文件发给对端ws 内部也会把这么大一块连续内存挂在发送队列里。更优雅的做法是分块发送每块用 subarray 视图引用原始文件内存不产生额外拷贝。const CHUNK_SIZE 1024 * 1024; // 1MB function sendLargeBuffer(socket, fileBuffer, onDone) { const totalChunks Math.ceil(fileBuffer.length / CHUNK_SIZE); let index 0; function sendNext() { if (index totalChunks) { onDone(); return; } const start index * CHUNK_SIZE; const end Math.min(start CHUNK_SIZE, fileBuffer.length); const chunk fileBuffer.subarray(start, end); index 1; socket.send(chunk, sendNext); } sendNext(); }这段代码有两个要点第一subarray 生成的是视图不会复制大文件内存第二使用 callback 串行发送保证前一个数据帧已经交给 ws 内部后才开始下一个避免同时有太多块挤压在队列里。我在实际项目里用这个方法传输过接近 1GB 的压缩包进程的 RSS 峰值基本稳定在文件本身的占用加少量缓冲完全可控。6. 技巧五内存治理让长时间运行的服务不偷偷膨胀二进制数据处理还有一个隐藏问题垃圾回收压力。Buffer 和 ArrayBuffer 都属于堆外内存或者可直接追踪的二进制对象一旦被引用链错误地保留内存上涨往往不是缓慢增长而是突然跳一个很大的台阶。6.1 闭包持有大 Buffer 是最常见的泄漏源很多消息回调里都会做异步操作比如把收到的二进制数据放进队列等后续任务消费。如果这个队列的容量没有上限或者没有及时清理已完成任务引用的 Buffer那么这些二进制对象会一直停留在内存里。典型场景const pendingMap new Map(); socket.on(message, (data) { const id data.readUInt32BE(0); const payload data.subarray(4); // 如果不加容量控制这个 Map 会无限增长 pendingMap.set(id, payload); });正确的做法是给队列或 Map 加上最大容量超过之后主动拒绝或者丢弃最老数据const MAX_PENDING 1000; if (pendingMap.size MAX_PENDING) { socket.close(1008, server overloaded); return; }6.2 用 process.memoryUsage 识别二进制内存占比Node.js 从某个版本开始支持在process.memoryUsage()中返回arrayBuffers字段它专门记录 ArrayBuffer 的占用。你可以写一个简单的定时监控把它和 rss、heapUsed 拉到一起看setInterval(() { const { rss, heapUsed, arrayBuffers } process.memoryUsage(); const arrayBufferMB (arrayBuffers / 1024 / 1024).toFixed(1); const rssMB (rss / 1024 / 1024).toFixed(1); const heapMB (heapUsed / 1024 / 1024).toFixed(1); console.log(rss${rssMB}MB heap${heapMB}MB arrayBuffers${arrayBufferMB}MB); }, 30000);如果 arrayBuffers 持续增长而 heap 保持稳定那大概率是某些 ArrayBuffer 被长期引用如果 heap 也在涨则要看具体是哪些对象。这个监控在定位线上问题时非常有用比等 OOM 被 kill 再复盘要主动得多。6.3 善用对象复用频繁创建大 Buffer 或 ArrayBuffer 会带来频繁的底层内存分配与释放。Node.js 对超过 Buffer 池大小的数据采用独立内存块分配开销与 GC 成本都不低。如果业务模式是固定的“消息进来处理发出去”可以考虑复用发送缓冲区用一个池子来维护可重用的 Buffer。当然这个技巧不要滥用只有在大消息、高频率的场景下收益才明显小消息直接让 Buffer 池管理反而更简单。我在一个图像服务里做过实验高频转发图片数据每张图 2MB-8MB总共每天转接近几十万张。一开始每秒新建 Buffer 后发给客户端GC 压力极大后来改成固定大小的 Buffer 池浪费率控制在 10% 以内整体 GC 次数下降了一半以上。实现思路不复杂本质上就是维护一个数组发送完毕后把 Buffer 放回池子取用时优先从池里拿。7. 高频踩坑与排查速查表处理 ArrayBuffer 和 Buffer 时有一些报错和现象出现的频率特别高。我把它们汇总成速查表方便你直接对照定位。现象或报错可能原因解决方式消息回调里 data 是 ArrayBuffer但代码用了 readUInt32BE报 TypeErrorbinaryType 被设置成 arraybuffer统一改为 nodebuffer或在代码里先 Buffer.from(data)收到的数据和想象中不一致长度多了很多Buffer 转 ArrayBuffer 时直接取 buffer.buffer 碰到池切片用 toArrayBuffer 安全切片函数发送大文件后进程内存暴涨一次性发送整个 Buffer分块发送配合回调或 bufferedAmount 流控同样一个服务浏览器端正常Node.js 客户端报错两端 binaryType 默认值不一致双方统一设置 binaryType对端收到空数据但自己确实调用了 send可能 send 了 0 字节 Buffer而业务把它当空数据处理用 isBinary 区分文本空串和二进制空帧长时间运行后内存持续增长消息回调里的 Buffer/ArrayBuffer 被异步队列持有检查无界队列增加容量限制websocket.send({foo: 1}) 报参数类型错误send 不接受普通对象先 JSON.stringify或自己构造二进制协议排查时我建议遵循三个步骤第一步打印data.constructor.name和isBinary确认类型与预期是否一致第二步打印byteLength或者length确认数据规模是否符合预期第三步如果怀疑数据内容错乱用 Buffer 的 subarray 截取头几十个字节转 hex 打印看是不是混入了池内其他数据。有一个小技巧很实用在服务端 message 回调里加一行类型日志只在环境变量 DEBUG_BINARY_TYPE 打开时输出方便线上排查。日志格式类似if (process.env.DEBUG_BINARY_TYPE isBinary) { console.log([ws] received ${data.constructor.name}, length${data.byteLength}); }这样平时不产生多余日志出问题时立刻打开很快就能定位是类型问题还是数据问题。8. 结尾我现在的实操习惯把这五个技巧用了大半年之后我发现最值钱的不是某个具体 API而是形成了一套“在错误发生之前就避免它”的习惯。我现在接手任何 ws 项目第一件事就是在连接建立时统一 binaryType并且全项目只允许一种接收类型。除非有硬性理由需要 ArrayBuffer否则默认就是 nodebuffer这是最省心、转换损耗最小的路径。第二步是给所有大消息传输设计流式或分块方案绝不让完整大文件在内存里滞留。第三步是在内存监控里盯住 arrayBuffers 字段像看体温一样看它的趋势。最后分享一个亲测有效的小扩展如果要把 ws 接进来的二进制数据流直接转给下游 HTTP 服务可以用createWebSocketStream再接一个自定义 Transform 流在流里做类型转换、帧解析甚至加密比在 message 回调里手工糊逻辑干净得多。二进制数据在 ws 里从来不难难的是让自己养成主动设计数据形态的思维。 
长河君 · 2026/10/10 17:10:10 · 阅读 1.2k Node.js ws库二进制数据处理：5个技巧告别ArrayBuffer与Buffer混乱
最近在做一个跨端数据同步项目服务端用 Node.js 的 ws 库做 WebSocket 网关浏览器端和多个 Node.js 客户端同时接入。需求本身不复杂但真正跑起来之后我发现所有麻烦都集中在同一个点上二进制数据到底什么时候是 ArrayBuffer什么时候是 Buffer。浏览器端原生 WebSocket 收二进制默认给 ArrayBufferNode.js 端 ws 库默认给 Buffer两个客户端一混服务端处理逻辑就变成了“先判断类型再手动转换”代码写得很丑排查还费劲。后来我把这块彻底理顺了总结出 5 个高效技巧基本可以告别二进制数据处理的那些别扭时刻。这篇指南就是基于这些实战经验写的适合正在用 ws 做实时通信、文件传输、音视频流的开发者无论你卡在类型转换、内存暴涨还是大数据分块都应该能在这里找到答案。1. 先看清 ws 库里的二进制“双轨制”很多人一上来就想着怎么把 ArrayBuffer 转成 Buffer、把 Buffer 转回 ArrayBuffer这其实是没抓到重点。要真正处理好这两个类型得先理解它们为什么同时存在以及 ws 库到底在什么环节使用它们。1.1 浏览器端和 Node.js 端的数据表示天然割裂ArrayBuffer 是 ECMAScript 标准里的通用二进制缓冲区浏览器端所有二进制能力都建立在它之上比如 TypedArray、DataView、Blob底层都是 ArrayBuffer 的视图或者引用。而 Buffer 是 Node.js 为了高性能处理二进制数据做的扩展它继承自 Uint8Array但额外提供了很多方便的方法比如 readUInt32BE、writeInt16LE、subarray、toString 等等同时还配合 Node.js 的内存池机制让频繁小数据分配更高效。问题在于同一份二进制数据在浏览器端和 Node.js 端天然会以不同的形态出现。浏览器端的 WebSocket API 里binaryType 可以设置成arraybuffer或者blob没有 Buffer 这个选项。而 ws 库跑在 Node.js 环境里默认会把收到的二进制数据处理成 Buffer。所以同一个 WebSocket 服务面对浏览器客户端和 Node.js 客户端时消息回调中的 data 类型是不一样的。1.2 ws 怎么决定你收到的是什么类型ws 库接收端的类型控制其实藏在实例的一个属性里binaryType。默认值是nodebuffer你可以改成arraybuffer还可以设置成fragments。这个属性在 WebSocketServer 的连接对象上也可以单独设置意味着同一个服务端可以让某些连接收 Buffer让另一些连接收 ArrayBuffer。发送端反而没那么讲究ws 的 send 方法接受字符串、Buffer、TypedArray、DataView、ArrayBuffer 这些类型。发送前 ws 会统一做内部处理对于 ArrayBuffer它会构造一个数据帧来承载而在接收端根据对端实例的 binaryType你看到的类型可能完全不同。这里我整理了一个比对表方便你快速理解发送端传入类型接收端 binaryType nodebuffer接收端 binaryType arraybufferBufferBuffer 原样收到会转成 ArrayBufferArrayBufferws 用其底层数据生成 BufferArrayBuffer 原样收到Uint8Array会生成 Buffer 视图转成 ArrayBufferstring 普通字符串如果是文本帧回调里拿到字符串同左字符串不走 binaryType我实测下来的结论是binaryType 只在接收方向生效而且只针对二进制帧文本帧永远是字符串。很多人纠结的“为什么我明明发的是 ArrayBuffer对端却收到 Buffer”本质就是对端 binaryType 默认是 nodebuffer。1.3 最容易被忽略的 isBinary 参数ws 的消息回调是socket.on(message, (data, isBinary) {})第二个参数 isBinary 表面上看只是告诉你当前帧是不是二进制帧但实际排查时特别有用。当你收到一段数据不确定它是文本还是二进制并且需要区分“空字符串”和“0 字节 Buffer”时isBinary 能帮你做第一层判断。空字符串和 0 字节 Buffer 在逻辑上完全不同但只看 data 类型和 length 容易混淆。有了 isBinary就可以干脆地把空文本帧和空二进制帧区分开。这一点在我做心跳和空消息处理时踩过坑后面你会看到具体案例。2. 技巧一接收数据前先明确目标类型而不是事后转换这是我认为最值得养成的习惯。你能在 ws 实例上直接设置 binaryType那就不要让二进制数据以“错误类型”送到业务层然后再来回转换。转一次就是一次拷贝拷贝多了性能自然差。2.1 在连接建立时就把类型定好服务端每来一个连接可以根据客户端协商结果设置 binaryTypeconst WebSocket require(ws); const wss new WebSocket.Server({ port: 8080 }); wss.on(connection, (socket, req) { // 假设某个子协议表明这个客户端需要 ArrayBuffer // 这里在连接阶段就明确后面不用每次消息都处理类型差异 socket.binaryType arraybuffer; socket.on(message, (data, isBinary) { if (!isBinary) { // 处理文本... return; } // 此时 data 必然是 ArrayBuffer const uint8 new Uint8Array(data); // 直接交给只接受 ArrayBuffer 的解码库 decode(uint8); }); });客户端同样可以在建立连接后立刻设置const WebSocketClient require(ws); const client new WebSocketClient(ws://localhost:8080); client.binaryType arraybuffer; client.on(message, (data, isBinary) { if (isBinary) { // 这里拿到的就是 ArrayBuffer不需要再自己转了 } });2.2 为什么说这样是零成本关键在于 ws 内部在接收数据时receiver 已经持有底层 Buffer 了。当 binaryType 是nodebuffer时它直接把 Buffer 交给你当 binaryType 是arraybuffer时它相当于基于底层 Buffer 构造一个 ArrayBuffer 返回。这个构造过程在部分场景下只是视图层面的转换并不是一份新的完整拷贝。而如果你保持默认的 nodebuffer等消息到了业务层再调用new Uint8Array(data)或者Buffer.from(data)可能就绕了远路。尤其是基于 Buffer 的丰富方法比如 subarray、readUInt32BE等你需要这些功能时正确做法是不要把你的数据转成 Buffer而是直接在连接上设置binaryType nodebuffer让它一开始就是 Buffer。反之如果你接了一个只认 ArrayBuffer 的加解密库就把 binaryType 设成arraybuffer避免每次消息都要额外转一次。2.3 自定义混合协议怎么处理“文本头 二进制体”真实业务里经常遇到这种情况一条消息里既要有 JSON 元信息又要有大段的二进制负载。最省事的方案是发两个消息一个文本元信息一个二进制数据。但这样会引入关联性问题接收端很难保证两条消息的先后顺序也没法原子地处理。我用的方案是自描述二进制协议一条消息头部固定是 4 字节的长度字段表示 JSON 元数据的字节长度随后紧跟 JSON 字符串再往后才是真正的二进制数据。把元信息和负载放进同一个二进制帧里。发送端可以这样构造function buildBinaryMessage(meta, payloadBuffer) { const metaBuf Buffer.from(JSON.stringify(meta), utf8); // 使用 Buffer.alloc copy 来拼装避免多段分散 const totalLen 4 metaBuf.length payloadBuffer.length; const messageBuf Buffer.allocUnsafe(totalLen); messageBuf.writeUInt32BE(metaBuf.length, 0); metaBuf.copy(messageBuf, 4); payloadBuffer.copy(messageBuf, 4 metaBuf.length); return messageBuf; }接收端如果统一用 nodebuffer处理起来很顺socket.on(message, (data, isBinary) { if (!isBinary) return; // data 此时一定是 Buffer const metaLen data.readUInt32BE(0); const meta JSON.parse(data.subarray(4, 4 metaLen).toString(utf8)); const payload data.subarray(4 metaLen); handleMetaAndPayload(meta, payload); });注意一个关键细节如果你的 binaryType 设成了arraybuffer那 data 是 ArrayBuffer没有readUInt32BE方法。这时候需要先用Buffer.from(data)拿到 Buffer 视图再走同样的解析流程。所以我的建议是在代码里统一约定一种接收类型不要一会儿 nodebuffer 一会儿 arraybuffer否则很容易出现“这个连接能跑那个连接报错”的诡异问题。3. 技巧二大文件传输时别等整个消息拼完用流式处理很多人用 ws 传输大文件时习惯一次性把文件读进内存再一次性 send 出去。对十几兆的文件问题不大但到了几百 MB 或者 GB 级别内存和速度都会出问题。ws 库本身就提供了流式方案但平时看到得太少。3.1 为什么不能默认“收到完整消息再处理”ws 的消息事件语义是等一个完整的 WebSocket 消息接收完成才会触发 message 回调。也就是说哪怕一个消息被拆成了很多个底层数据帧ws 内部也会先把它们拼装成一个完整的 Buffer然后才交给你。面对超大文件时这个“完整 Buffer”会占掉与文件同等大小的内存。比如一次推 800MB 的日志文件服务端光接收就得预留 800MB 以上的堆内存做拼装这还没算文件写入时的额外开销。除非你的业务本身就需要完整数据才能解析否则对大二进制文件来说流式处理是更合理的方案。3.2 用 createWebSocketStream 把连接的收发变成流ws 里有个高层封装叫做createWebSocketStream。它能把一个 WebSocket 连接包装成标准的 Duplex 流从此你可以直接 pipe 到文件流或者与任意 Transform 流串联。const { createWebSocketStream } require(ws); const fs require(fs); wss.on(connection, (socket) { // 接收大文件时直接把数据流写入本地文件 const duplex createWebSocketStream(socket); const output fs.createWriteStream(./received.bin); duplex.pipe(output); duplex.on(error, (err) { console.error(stream error:, err.message); }); });发送端也可以把文件流通过 WebSocket 发出去const { createWebSocketStream } require(ws); const fs require(fs); const client new WebSocketClient(ws://localhost:8080); client.on(open, () { const duplex createWebSocketStream(client); const input fs.createReadStream(./huge-file.bin); input.pipe(duplex); });这样处理之后内存占用基本是恒定的因为 Node.js 的流机制自带背压读快写慢时会自动暂停读取不会一股脑把整个文件塞进内存。3.3 用 fragments 模式手动分块如果你不想引入流式封装还想保留 message 事件的结构ws 还有一种折中方案把 binaryType 设置成fragments。在这种模式下回调里的 data 不再是拼装好的完整 Buffer而是一个由多个分片 Buffer 组成的数组。socket.binaryType fragments; socket.on(message, (fragments, isBinary) { if (!isBinary) return; // fragments 是一个数组按帧顺序排列 for (const frag of fragments) { // 这里可以逐个写盘避免一次大拼装 } });这种方式适合那种“需要流式落盘但又不希望引入完整 stream 抽象”的场景。需要注意ws 仍然会在内部缓存这些 fragments 直到整个消息接收完毕它不会让你在消息还没结束前逐帧处理。所以它节省的不是总的缓存量而是省去了把多个帧合并成一个大 Buffer 时额外分配的那份连续内存以及由此引发的内存碎片。我实际体验下来现代 Node.js 流已经足够顺手如果确实要从零处理大文件优先用 createWebSocketStreamfragments 模式更适合那些想自己控制帧级逻辑的场景。4. 技巧三ArrayBuffer 与 Buffer 互转必须分清零拷贝和深拷贝尽管我前面一直强调尽量在接收端一次到位但总会有需要兼容老代码、第三方库或者浏览器端旧逻辑的时候。ArrayBuffer 和 Buffer 之间的转换可以说是这类问题里踩坑最多的地方。4.1 Buffer.from(arrayBuffer)不是深拷贝而是共享内存一个很棒的技巧是当你在 Node.js 端收到 ArrayBuffer 时直接调用Buffer.from(arrayBuffer)得到的 Buffer 实际上是对同一块底层内存的视图。它不会复制数据。你修改这个 Buffer 的内容原 ArrayBuffer 也会跟着变反之亦然。这个行为与Buffer.from(字符串)完全不同后者是会分配新内存的。所以当 API 需要 Buffer而手里只有 ArrayBuffer 时放心使用const arrayBuffer new ArrayBuffer(1024); const view new Uint8Array(arrayBuffer); view[0] 42; const buf Buffer.from(arrayBuffer); // 共享内存 buf[0] 100; console.log(view[0]); // 100确实是同一块内存注意这里的 Buffer.from 并不复制字节但也不代表零开销。用来创建视图的基础对象分配仍然存在只是它没有移动数据。4.2 真正的坑Buffer.from(Buffer) 是深拷贝与上面不同Buffer.from(existingBuffer)会创建一份全新的拷贝。接受已有的 Buffer 时如果你不小心写出了类似Buffer.from(rawData)的代码实际上等于重新复制了一整块数据。在大消息高频场景下这会造成不必要的内存和 CPU 开销。正确复用已有 Buffer 的方式是直接使用原变量或者用rawData.subarray()生成一个视图后者同样不复制底层数据。const raw Buffer.alloc(1024); // 错误额外复制了一份 const copy1 Buffer.from(raw); // 正确直接使用 const same raw; // 正确需要切片时用 subarray 视图 const sliceView raw.subarray(0, 512);4.3 Buffer 转 ArrayBuffer 的 byteOffset 陷阱Buffer 转 ArrayBuffer 时最容易犯错的是直接取buf.buffer属性。由于 Node.js 内部存在 Buffer 池小 Buffer 很可能是某个大 ArrayBuffer 的一个切片视图。如果直接取 buffer 属性你拿到的可能是整块内存池而不是这个 Buffer 对应的数据区域。安全的方式是手动切片function toArrayBuffer(buffer) { // 如果当前 Buffer 就是完整独立的内存块直接复用底层 buffer if (buffer.byteOffset 0 buffer.byteLength buffer.buffer.byteLength) { return buffer.buffer; } // 否则需要切片slice 会返回一个新的 ArrayBuffer return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset buffer.byteLength); }这里的 slice 语义是 ArrayBuffer.prototype.slice它返回新的 ArrayBuffer并复制数据。也就是说Buffer 转 ArrayBuffer 很难做到完全没有拷贝除非当前 Buffer 恰好是整个底层内存块的完整视图。4.4 正确选择视图还是拷贝我把常见操作整理成了一张速查表你直接按需求选操作方法是否拷贝建议ArrayBuffer 当 Buffer 用Buffer.from(arrayBuffer)否首选零拷贝Buffer 复制一份独立数据Buffer.from(buffer)是确认需要独立快照时用Buffer 获取切片buffer.subarray(start, end)否比 slice 好不复制Buffer 转 ArrayBuffer 安全版buffer.buffer.slice(byteOffset, byteOffset byteLength)是通用安全避免池污染Buffer 恰好独立直接返回 buffer.buffer否大 Buffer 场景常见Buffer 转 Uint8Array 视图new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength)否类型化访问我自己在项目里就遇到过一个大坑某次把收到的消息 Buffer 直接当作 ArrayBuffer 传给一个加解密接口因为那个 Buffer 恰好是 Buffer 池的切片导致加解密库不仅读到了当前消息的数据还把池子里其他无关数据也一并处理了排查了很久才定位到 byteOffset 上。从那以后所有 Buffer 转 ArrayBuffer 的代码我都走统一的 toArrayBuffer 函数。5. 技巧四发送端优化让大消息飞得更稳接收端处理方式理顺之后发送端同样藏着一些值得注意的细节。很多人只管调 send忽略了 ws 发送数据时在内存和时序上的行为导致数据错乱或者内存峰值过高。5.1 send 之后不要再修改原 Bufferws 的 send 是异步操作。你把一个 Buffer 传给 sendws 并不会立刻深拷贝一份再排队而是先把引用放入发送队列之后才会编码成 WebSocket 帧写入内核。因此在 send 回调触发之前不要修改原来的 Buffer。const payload Buffer.alloc(1024 * 1024); const client new WebSocketClient(ws://localhost:8080); client.send(payload, (err) { // 走到这里表示 payload 已经被序列化并交给底层发送之后才可以安全复用 if (err) return; // 可以在这里对 payload 做后续处理 });这个规则看起来很简单但在并发发送或循环发送时容易被忽略。我见过有同事在循环体内复用同一个 Buffer然后连续调用多次 send第二个 send 的时候第一个还没发完结果不仅数据被覆盖报错还极其难查。解决方法是每轮发送都用一个独立的 subarray 视图并且在上一次回调后再发起下一次发送。5.2 用 bufferedAmount 感知背压避免无限堆积当发送速度远大于底层 TCP 的消费速度时ws 内部发送队列会不断膨胀。bufferedAmount属性表示当前等待发送但尚未写入内核的字节数。你可以利用它来实现一个简单的流控const HIGH_WATER_MARK 16 * 1024 * 1024; // 16MB function safeSend(socket, data, callback) { if (socket.readyState socket.OPEN socket.bufferedAmount HIGH_WATER_MARK) { socket.send(data, callback); } else { // 缓冲太多暂时不要发送等队列消化后再继续 setTimeout(() safeSend(socket, data, callback), 100); } }这种方案在后台批量推送文件数据时很有用。如果没有背压控制客户端网络慢的时候Node.js 进程内存会随着发送队列一起长大。虽然 TCP 层也有缓冲区但业务层配合 bufferedAmount 做限速能有效避免发送方把自己打爆。5.3 大 Buffer 分块发送降低内存峰值一次把整个 100MB 文件发给对端ws 内部也会把这么大一块连续内存挂在发送队列里。更优雅的做法是分块发送每块用 subarray 视图引用原始文件内存不产生额外拷贝。const CHUNK_SIZE 1024 * 1024; // 1MB function sendLargeBuffer(socket, fileBuffer, onDone) { const totalChunks Math.ceil(fileBuffer.length / CHUNK_SIZE); let index 0; function sendNext() { if (index totalChunks) { onDone(); return; } const start index * CHUNK_SIZE; const end Math.min(start CHUNK_SIZE, fileBuffer.length); const chunk fileBuffer.subarray(start, end); index 1; socket.send(chunk, sendNext); } sendNext(); }这段代码有两个要点第一subarray 生成的是视图不会复制大文件内存第二使用 callback 串行发送保证前一个数据帧已经交给 ws 内部后才开始下一个避免同时有太多块挤压在队列里。我在实际项目里用这个方法传输过接近 1GB 的压缩包进程的 RSS 峰值基本稳定在文件本身的占用加少量缓冲完全可控。6. 技巧五内存治理让长时间运行的服务不偷偷膨胀二进制数据处理还有一个隐藏问题垃圾回收压力。Buffer 和 ArrayBuffer 都属于堆外内存或者可直接追踪的二进制对象一旦被引用链错误地保留内存上涨往往不是缓慢增长而是突然跳一个很大的台阶。6.1 闭包持有大 Buffer 是最常见的泄漏源很多消息回调里都会做异步操作比如把收到的二进制数据放进队列等后续任务消费。如果这个队列的容量没有上限或者没有及时清理已完成任务引用的 Buffer那么这些二进制对象会一直停留在内存里。典型场景const pendingMap new Map(); socket.on(message, (data) { const id data.readUInt32BE(0); const payload data.subarray(4); // 如果不加容量控制这个 Map 会无限增长 pendingMap.set(id, payload); });正确的做法是给队列或 Map 加上最大容量超过之后主动拒绝或者丢弃最老数据const MAX_PENDING 1000; if (pendingMap.size MAX_PENDING) { socket.close(1008, server overloaded); return; }6.2 用 process.memoryUsage 识别二进制内存占比Node.js 从某个版本开始支持在process.memoryUsage()中返回arrayBuffers字段它专门记录 ArrayBuffer 的占用。你可以写一个简单的定时监控把它和 rss、heapUsed 拉到一起看setInterval(() { const { rss, heapUsed, arrayBuffers } process.memoryUsage(); const arrayBufferMB (arrayBuffers / 1024 / 1024).toFixed(1); const rssMB (rss / 1024 / 1024).toFixed(1); const heapMB (heapUsed / 1024 / 1024).toFixed(1); console.log(rss${rssMB}MB heap${heapMB}MB arrayBuffers${arrayBufferMB}MB); }, 30000);如果 arrayBuffers 持续增长而 heap 保持稳定那大概率是某些 ArrayBuffer 被长期引用如果 heap 也在涨则要看具体是哪些对象。这个监控在定位线上问题时非常有用比等 OOM 被 kill 再复盘要主动得多。6.3 善用对象复用频繁创建大 Buffer 或 ArrayBuffer 会带来频繁的底层内存分配与释放。Node.js 对超过 Buffer 池大小的数据采用独立内存块分配开销与 GC 成本都不低。如果业务模式是固定的“消息进来处理发出去”可以考虑复用发送缓冲区用一个池子来维护可重用的 Buffer。当然这个技巧不要滥用只有在大消息、高频率的场景下收益才明显小消息直接让 Buffer 池管理反而更简单。我在一个图像服务里做过实验高频转发图片数据每张图 2MB-8MB总共每天转接近几十万张。一开始每秒新建 Buffer 后发给客户端GC 压力极大后来改成固定大小的 Buffer 池浪费率控制在 10% 以内整体 GC 次数下降了一半以上。实现思路不复杂本质上就是维护一个数组发送完毕后把 Buffer 放回池子取用时优先从池里拿。7. 高频踩坑与排查速查表处理 ArrayBuffer 和 Buffer 时有一些报错和现象出现的频率特别高。我把它们汇总成速查表方便你直接对照定位。现象或报错可能原因解决方式消息回调里 data 是 ArrayBuffer但代码用了 readUInt32BE报 TypeErrorbinaryType 被设置成 arraybuffer统一改为 nodebuffer或在代码里先 Buffer.from(data)收到的数据和想象中不一致长度多了很多Buffer 转 ArrayBuffer 时直接取 buffer.buffer 碰到池切片用 toArrayBuffer 安全切片函数发送大文件后进程内存暴涨一次性发送整个 Buffer分块发送配合回调或 bufferedAmount 流控同样一个服务浏览器端正常Node.js 客户端报错两端 binaryType 默认值不一致双方统一设置 binaryType对端收到空数据但自己确实调用了 send可能 send 了 0 字节 Buffer而业务把它当空数据处理用 isBinary 区分文本空串和二进制空帧长时间运行后内存持续增长消息回调里的 Buffer/ArrayBuffer 被异步队列持有检查无界队列增加容量限制websocket.send({foo: 1}) 报参数类型错误send 不接受普通对象先 JSON.stringify或自己构造二进制协议排查时我建议遵循三个步骤第一步打印data.constructor.name和isBinary确认类型与预期是否一致第二步打印byteLength或者length确认数据规模是否符合预期第三步如果怀疑数据内容错乱用 Buffer 的 subarray 截取头几十个字节转 hex 打印看是不是混入了池内其他数据。有一个小技巧很实用在服务端 message 回调里加一行类型日志只在环境变量 DEBUG_BINARY_TYPE 打开时输出方便线上排查。日志格式类似if (process.env.DEBUG_BINARY_TYPE isBinary) { console.log([ws] received ${data.constructor.name}, length${data.byteLength}); }这样平时不产生多余日志出问题时立刻打开很快就能定位是类型问题还是数据问题。8. 结尾我现在的实操习惯把这五个技巧用了大半年之后我发现最值钱的不是某个具体 API而是形成了一套“在错误发生之前就避免它”的习惯。我现在接手任何 ws 项目第一件事就是在连接建立时统一 binaryType并且全项目只允许一种接收类型。除非有硬性理由需要 ArrayBuffer否则默认就是 nodebuffer这是最省心、转换损耗最小的路径。第二步是给所有大消息传输设计流式或分块方案绝不让完整大文件在内存里滞留。第三步是在内存监控里盯住 arrayBuffers 字段像看体温一样看它的趋势。最后分享一个亲测有效的小扩展如果要把 ws 接进来的二进制数据流直接转给下游 HTTP 服务可以用createWebSocketStream再接一个自定义 Transform 流在流里做类型转换、帧解析甚至加密比在 message 回调里手工糊逻辑干净得多。二进制数据在 ws 里从来不难难的是让自己养成主动设计数据形态的思维。