TextDecoderStream 处理 SSE 为什么不乱码：UTF-8 分块解码与结束边界

前端页面用SSE接收实时通知时，服务端发出的中文内容，并不一定能按完整字符的边界抵达浏览器。一个汉字的UTF-8编码占多个字节，很可能被拆分到两个不同的网络块里；如果每收到一块就单独调用 TextDecoder.decode()，文本里就可能出现乱码替换符。浏览器自带的 TextDecoderStream 正是为这种连续字节流场景准备的。

先复现：中文为什么会在SSE页面变成 �

假设服务端连续发送两段UTF-8字节，恰好把“告”字拆成两半。下面的代码故意每次都新建解码器，刚好还原很多手写SSE客户端的常见错误写法：

const decoder = new TextDecoder();
const bytes = new Uint8Array([0xe5, 0x91, 0x8a]); // “告”

const left = decoder.decode(bytes.slice(0, 2));
const right = decoder.decode(bytes.slice(2));
console.log(left + right);

如果两个字节块分别被独立解码，解码器没有机会知道前一块还缺后续的字节，自然就输出乱码。实际的SSE数据还会混合换行、字段标识和对应值，这类问题最终表现出来往往是偶发乱码，而不是能稳定复现的接口报错。

TextDecoderStream 的最小接法：字节流先转成文本流

把响应体直接接入 TextDecoderStream，再用异步迭代的方式读取字符串chunk：

const response = await fetch('/events');
if (!response.ok || !response.body) {
  throw new Error(`SSE response unavailable: ${response.status}`);
}

const textStream = response.body.pipeThrough(new TextDecoderStream());

for await (const chunk of textStream) {
  console.log('text chunk:', chunk);
}

这里的核心是全局只有一个解码器，并且贯穿整个流的生命周期。它会自动记住尚未处理完的UTF-8序列，等下一块字节到达后再输出完整字符。输出的 chunk 仍然只是当前已可用的一段文本，绝对不是完整的SSE事件。

为什么不能直接 JSON.parse(chunk)

SSE的传输边界和业务消息边界完全是两回事。一次收到的chunk可能只包含半行内容，也可能包含三条完整事件；因此要先把文本追加到缓冲区，按换行符切出完整行，再用空行判断单条事件是否结束。

把字符串 chunk 组装成可用的 SSE 事件

下面的解析器只处理最常用的 data:、event: 和空行边界。代码刻意保留简单结构，方便大家根据服务端实际字段逐项扩展：

function createSseParser(onEvent) {
  let buffer = '';
  let eventName = 'message';
  let dataLines = [];

  function dispatch() {
    if (dataLines.length === 0) return;
    onEvent({
      type: eventName,
      data: dataLines.join('\n')
    });
    eventName = 'message';
    dataLines = [];
  }

  return {
    push(text) {
      buffer += text;
      const lines = buffer.split('\n');
      buffer = lines.pop() ?? '';

      for (const raw of lines) {
        const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
        if (line === '') {
          dispatch();
        } else if (line.startsWith('data:')) {
          dataLines.push(line.slice(5).trimStart());
        } else if (line.startsWith('event:')) {
          eventName = line.slice(6).trimStart();
        }
      }
    },
    end() {
      if (buffer !== '') this.push('\n');
      dispatch();
    }
  };
}

const parser = createSseParser((event) => {
  console.log(event.type, event.data);
});

for await (const chunk of textStream) {
  parser.push(chunk);
}
parser.end();

缓冲区的最后一行可能没有末尾的换行符，所以 end() 不能空着。服务端断开时，如果残留内容确实能构成一条事件，应该在流结束前提交；如果项目协议要求必须有空行才算完整事件，也可以改成记录异常而不提交。

兼容和生产边界：四个检查点

检查一：运行时是否支持 TextDecoderStream

在目标浏览器和 Web Worker 环境中分别确认这个API的能力存在：

const canDecodeStream = typeof TextDecoderStream === 'function';
console.log({ canDecodeStream });

它已经是主流浏览器里的成熟Web API，但面向旧版WebView、嵌入式浏览器或者特殊运行环境时，仍然建议提前准备好兼容实现。

检查二：fatal 是否符合业务容错

默认解码遇到非法字节会用替换字符继续输出。如果日志或者协议数据不能容忍静默替换，可使用 new TextDecoderStream('utf-8', { fatal: true })，然后在流错误处触发重连或者数据损坏提示。不要把 fatal 当成网络重试开关。

检查三：代理是否缓冲 SSE

客户端解码逻辑正确，不代表用户一定能实时看到数据。Nginx、CDN或者应用服务器可能攒够一批字节才转发，生产排查时要同时核对响应头、代理缓冲配置、心跳频率和浏览器Network面板里的数据到达时间。

检查四：断线重连是否重复消费

SSE断线重连常常会带上 Last-Event-ID。事件已经在页面显示过，不等于服务端不会再次下发；客户端需要根据事件id做去重，不能只靠TextDecoderStream解决业务层的重复问题。

常见问题：TextDecoderStream 和 SSE 解析

TextDecoderStream 会按 SSE 事件输出吗？

不会。它只负责把字节转换成字符串，输出边界由流自身的实现决定。SSE的换行、空行、data内容合并和事件提交逻辑仍需要单独写代码解析。

每个 chunk 都调用 TextDecoder.decode 可以吗？

不建议。如果一定要手写实现，应该复用同一个 TextDecoder 并在后续调用中传入 { stream: true }，流结束时再用一次空输入收尾；直接每块新建解码器很容易破坏多字节字符的完整性。

为什么响应有数据但页面迟迟不更新？

可能是服务端或代理开启了缓冲，也可能是客户端逻辑一直在等完整事件。分别检查Network面板的响应到达时间、代理配置和行缓冲里是否真的出现了事件结束的空行。

最后的判断

TextDecoderStream 解决的是UTF-8字节边界问题，不是完整的SSE协议解析。把响应体先转成连续文本，再用行缓冲组装事件，最后补上结束、错误、重连和去重处理，才能让实时中文消息既不乱码，也不会因为网络chunk的形状变化而丢失事件。