为何将解码后的缓冲区数据块视为文本会导致文件上传失败

解释了为何将二进制缓冲区数据视为UTF-8文本会悄悄损坏上传的文件，并展示了正确的字节级处理方法以避免这一问题。

1375 词

一个文件上传接口或许能通过你设计的所有手动测试——小图片、PDF文件、纯文本文件，一切都能顺利处理。然而突然之间，有客户上传的文件会出现损坏，比如图片中出现大量异常像素，或者原本在客户端时格式正确的数据在上传后无法被解析为JSON。在整个传输过程中并没有人修改过该文件，问题却悄然出现在那些乍看之下完全正常的代码中，而其根本原因正是Node.js中最常见的错误之一：将二进制数据当作文本来处理。

Buffer究竟是什么

Buffer不过是Node.js用来在内存中存储一系列原始字节的工具。它本身不携带任何内置含义或字符编码，只是连续存储的0到255之间的数值而已：

const buf = Buffer.from([72, 101, 108, 108, 111]);
console.log(buf); // <Buffer 48 65 6c 6c 6f>
console.log(buf.toString("utf8")); // "Hello"

只有当你刻意使用特定编码（本例中为UTF-8）来解析这些五个字节值时，它们才会变成可读的字符串 "Hello"。单独来看，这些字节并非文本，仅仅是字节而已。而 Buffer 的存在正是为了让你在决定将这些二进制数据视为字符之前，或完全不进行此类判断的情况下就能对其进行处理。正是“原始字节”与“选定编码下的文本”之间的这种差异，导致了这类故障的产生。

错误：将二进制数据解码为文本

引发此问题的模式看似十分普通：

app.post("/upload", (req, res) => {
  let body = "";
  req.on("data", (chunk) => {
    body += chunk.toString("utf8"); // corrupting the file, one chunk at a time
  });
  req.on("end", () => {
    fs.writeFileSync("upload.png", body, "utf8"); // and corrupting it again here
  });
});

图像字节并非文本，而是一种用于编码像素值、压缩表及元数据的任意二进制流，这些内容从一开始就不是为以UTF-8字符形式读取而设计的。对这类二进制数据调用.toString("utf8")会迫使运行时去解析那些往往并不对应任何有效UTF-8序列的字节。解码器不会抛出错误，而是会在遇到无法解析的字节模式时悄悄替换为Unicode替代字符（，U+FFFD）。那些原始字节将永久消失，被一个无法恢复原值的占位符取代。这正是导致数据损坏看起来零散且随机的原因：只有那些并非有效UTF-8格式的字节序列才会被破坏，而对于图像这类二进制格式而言，这种情况随时都可能发生。

app.post("/upload", (req, res) => {
  const chunks = [];
  req.on("data", (chunk) => chunks.push(chunk)); // keep raw bytes, don't decode anything
  req.on("end", () => {
    const fileBuffer = Buffer.concat(chunks);
    fs.writeFileSync("upload.png", fileBuffer); // write raw bytes, no string conversion involved
  });
});

假设请求体直接携带原始文件字节，而非 multipart/form-data 格式的数据，这种处理方式能够完整保留上传时的文件内容。如果需要处理多部分上传的数据，应先使用合适的 multipart 解析器提取出文件部分。根本的解决方法很简单：绝不要将二进制数据转换为字符串。相反，应原样收集传入的 Buffer 数据块，在字节层面将它们拼接起来，然后直接将这些字节写入磁盘或存储介质中。

同样的错误，更为隐蔽：多字节字符在数据块间被拆分

即便实际处理的是文本，若逐块解码而非一次性解码，也会引发另一种类似但更为微妙的错误，尤其是在逐步处理流式数据时尤为常见：

readStream.on("data", (chunk) => {
  process.stdout.write(chunk.toString("utf8")); // can corrupt multi-byte characters
});

在UTF-8编码下，一个表情符号或带重音的字母可能占用多个字节，而来自网络连接或文件流的数据块边界并不知道这些多字节字符的起始位置。如果某个数据块恰好在字符中间结束，单独解码该数据块就会得到一个损坏的字符，它会被悄悄替换为替代字符，尽管完整的正确字节序列其实一直都存在，只是被分在了两次独立的.toString()调用中，每次调用只看到了其中的一半。

const decoder = new (require("string_decoder").StringDecoder)("utf8");

readStream.on("data", (chunk) => {
  process.stdout.write(decoder.write(chunk)); // holds incomplete multi-byte sequences until the rest arrives
});

readStream.on("end", () => {
  process.stdout.write(decoder.end());
});

Node 内置的 StringDecoder 正是为这种情况设计的：它会保留数据块末尾任何不完整的多字节序列，而不会过早对其进行解码，而是等待剩余字节在下一个数据块中出现后再完成该字符的解码。这与使用 Buffer.concat 连接缓冲区的方式截然不同，前者专门用于在数据流式输入时安全地解码文本，而非先缓存整个二进制文件再进行处理。

编码不匹配：写入一种编码，读取另一种编码

还有一种同样容易忽视的故障：在操作的写入端与读取端选择了不匹配的编码。

const token = crypto.randomBytes(32); // raw binary
const encoded = token.toString("base64"); // encode once, deliberately, for safe transport

// later, elsewhere in the codebase
const decoded = Buffer.from(encoded, "hex"); // wrong encoding — does not recover the original bytes

Buffer.from会根据你传入的编码参数来读取字符串。如果该编码并非最初生成字符串时所使用的编码，就无法以可靠的方式获取到原始字节。根据所用的编码以及输入内容的不同，Node 可能会解码出完全不同的字节值，或者默默忽略那些不符合该编码规则的字符串部分，而不会立即抛出让你能察觉到的错误。

`Buffer.alloc` 与 `Buffer.allocUnsafe`：不仅是性能差异，更是安全问题

还有另一个值得牢记的区别，在这里尤为重要，因为搞错它不仅会导致漏洞，还可能引发敏感数据泄露：

const safeBuf = Buffer.alloc(16);       // zero-filled, always
const fastBuf = Buffer.allocUnsafe(16); // NOT zero-filled — may contain old memory contents

Buffer.allocUnsafe会跳过将分配到的内存清零的步骤，这样确实更快，但这也意味着该缓冲区仍可能保留之前存储在该内存区域中的任意字节数据，可能是之前请求的残留部分、其他用户会话令牌的片段，或是此前存储在那里的任何其他内容。如果你以这种方式分配缓冲区，却在发送之前只写入其中部分数据，无论是通过网络传输还是写入磁盘文件，都可能存在泄露与当前操作无关的数据的风险。Buffer.alloc会预先花些少量且可预测的成本来清零内存，这应当是你的默认选择。只有在确定在有其他代码触碰之前自己会完全覆盖整个缓冲区的情况下，才应使用allocUnsafe。

真正的课程内容

所有这些故障都源于同一个根本性的误解：将原始的字节序列当作天然文本来处理，而实际上“文本”这一概念只有在明确决定使用何种编码来解析这些字节之后才会出现，而且这个决策可能会被错误地应用、过早地执行，或出现在处理流程的错误环节。更安全的方法是尽可能让二进制数据保持其二进制状态，以原始字节的形式进行拼接和转换，只有在确实需要将其作为文本使用的特定时刻，才使用事先明确选定的正确编码将其转换为字符串。如果没有这样的规范，数据损坏就不会以明显的错误形式显现出来，它只会悄悄地用自己无法解析的字节替代原有内容，导致问题在之后才被发现，通常是因为有用户反馈某些功能无法正常工作。

。