在Node.js中，Buffer是处理TCP流、文件系统操作等二进制数据的基础对象。当我们需要把一个Buffer中的数据复制到另一个Buffer时，很多人会想到先转成字符串再用Buffer.from创建，这种做法不仅性能差，还可能因为编码问题导致数据损坏。Node.js在Buffer原型上提供了专门的copy方法，能够在两个缓冲区之间直接进行字节级别的拷贝，全程不涉及字符串编解码，是处理二进制数据拷贝的首选方案。本文将从方法签名、参数细节、实际代码和常见陷阱几个方面，完整讲解Buffer.copy的用法。
一、buf.copy方法的语法与参数详解
buf.copy(target[, targetStart[, sourceStart[, sourceEnd]]])是Buffer实例上的方法，它的作用是把源缓冲区buf中从sourceStart到sourceEnd（不包含end位置）的字节，拷贝到目标缓冲区target以targetStart为起点的位置上。该方法返回实际拷贝的字节数，这个返回值非常重要，后面会讲到为什么。
四个参数的默认值需要牢记：targetStart默认为0，sourceStart默认为0，sourceEnd默认为buf.length。也就是说，如果只传一个目标缓冲区，就等价于把源缓冲区从头到尾拷贝到目标缓冲区的开头。还需要注意，参数可以是负数，负数会按照相对于末尾的偏移来计算，这一点和JavaScript中数组的slice方法行为一致。
看一个最基础的例子，把一个Buffer完整拷贝到另一个Buffer：
const src = Buffer.from('hello nodejs');
const dest = Buffer.alloc(20);
// 把src的全部内容拷贝到dest的起始位置
const copied = src.copy(dest);
console.log(copied); // 12，实际拷贝的字节数
console.log(dest.toString()); // "hello nodejs"上面的代码中，dest是20字节，源数据只有12字节，拷贝后dest后面8个字节仍然是0，copy只覆盖目标缓冲区中对应区间的数据，不会影响其他部分。
二、区间拷贝与缓冲区重叠的处理
实际开发中更常见的需求是拷贝某一段数据，比如从一个大的数据帧中提取某个字段。这时就要用到sourceStart和sourceEnd参数。例如一个网络协议帧，前4个字节是长度头，后面是消息体，我们想把消息体单独拷贝出来：
const frame = Buffer.from([0x00, 0x0a, 0x48, 0x65, 0x6c, 0x6c, 0x6f]); // 假设前4字节是头部，跳过头部拷贝消息体到另一个缓冲区 const body = Buffer.alloc(frame.length - 4); const n = frame.copy(body, 0, 4); console.log(n, body.toString()); // 3 "llo"
上面的例子中frame.copy(body, 0, 4)表示从源的第4字节开始，一直拷贝到末尾，写入body的第0个位置。如果只想拷贝中间一段，把第四个参数sourceEnd也传上即可，注意它是开区间，不包含该位置的字节。
缓冲区重叠是copy方法一个容易被忽略但很实用的特性。当源和目标是同一个Buffer实例，或者它们底层共享同一段内存时，copy的表现类似C语言中的memmove而不是memcpy，也就是说它能正确处理重叠区域的拷贝，不会出现数据被意外覆盖的问题。这在实现数据左移、删除缓冲区中某段数据等操作时非常有用：
const buf = Buffer.from('abcdef');
// 删除索引1到3的字节：把后面的数据往前挪
buf.copy(buf, 1, 3);
// 手动截断逻辑长度需要额外处理，这里演示重叠拷贝本身
console.log(buf.toString()); // "adefef"可以看到copy正确地把第3字节之后的数据搬到了第1字节开始的位置，即使读写区间在同一块内存上也保证了正确性。不过要注意copy本身不会改变Buffer的长度，需要缩短逻辑长度时通常要配合buf.subarray(0, newLength)使用。
三、常见坑点与替代方案对比
使用copy最大的坑在于越界时的静默截断行为。当源数据长度超过目标缓冲区从targetStart开始剩余的空间时，copy不会抛出异常，而是只拷贝放得下的那部分，多余的直接丢弃。如果代码依赖返回值检查还好，如果不检查返回值，就会出现数据悄悄丢失的诡异问题：
const src = Buffer.from('0123456789');
const dest = Buffer.alloc(5);
const n = src.copy(dest, 2);
console.log(n); // 3，只能放下3个字节
console.log(dest.toString()); // "�01"，乱码说明数据被截断因此强烈建议在生产代码中始终检查copy的返回值，或者提前用sourceEnd - sourceStart与target.length - targetStart做比较，确保空间充足。另外，如果targetStart超出了目标缓冲区长度，拷贝的字节数会是0，同样不会报错。
除了copy，还有几个相关的替代方案需要区分清楚。Buffer.from是创建新缓冲区，如果传入的参数是Buffer，实际上是复制一份数据到新内存，适合整体复制的场景；target.set(source, offset)是TypedArray的标准方法，功能上和copy类似，但它要求源数据必须完整放得下，否则直接抛出RangeError，行为上更严格；buf.subarray则完全不拷贝数据，只是创建一个共享底层内存的视图，适合只需要读取某个区间的场景，性能最好但要警惕原缓冲区变化带来的影响。
总结一下选择思路：需要在已有缓冲区上原地写入或覆盖数据，用copy；需要复制出一个全新的独立缓冲区，用Buffer.from；只需要视图不修改数据，用subarray；希望越界时报错而不是静默截断，可以考虑set。理解这几种方式的内存行为差异，在处理文件流、网络协议解析等场景时才能写出既高效又可靠的代码。
Node.jsBuffer.copy缓冲区拷贝修改时间：2026-09-02 01:26:29