TextDecoderStream是专为流式解码设计的TransformStream，自动处理字节边界与缓冲，输入Uint8Array流、输出string流，无需手动调用decode(..., {stream:true})及清空缓冲，避免丢字符；仅支持utf-8、utf-16、iso-8859-1等编码，不兼容gbk等非标准编码，且不解析语义单位（如行）。
TextDecoderStream 是专为流式解码设计的可读流转换器，它比手动调用 TextDecoder.decode() 更简洁、更符合流式处理范式。直接用它，不用自己维护 stream: true 和缓冲逻辑。
为什么不用 TextDecoder 而要用 TextDecoderStream
手动用 TextDecoder 做流式解码时，必须反复调用 decode(chunk, { stream: true })，并在最后补一次 decode() 清空缓冲区——漏掉末次调用就会丢字符（比如一个 emoji 被截在 chunk 末尾）。TextDecoderStream 内部自动处理字节边界和缓冲，你只管把原始字节流塞进去，出来的就是完整字符串流。
它本质是一个 TransformStream，输入是 Uint8Array 流，输出是 string 流，天然适配 ReadableStream.pipeThrough()。
TextDecoderStream 构造与基础用法
创建实例只需传入编码名，不支持 { ignoreBOM: true } 或 { fatal: true } 等选项（这些在 TextDecoder 中才有）：
立即学习“前端免费学习笔记（深入）”；
const decoderStream = new TextDecoderStream('utf-8');
常见使用场景是处理 fetch 响应体：
- 从
response.body获取原始字节流 - 用
.pipeThrough(decoderStream)转换为字符串流 - 用
.getReader()读取解码后的文本块
示例：
const response = await fetch('/api/log-stream');
const decodedStream = response.body.pipeThrough(new TextDecoderStream());
const reader = decodedStream.getReader();
while (true) {
const { done, value } = await reader.read();
if (done) break;
console.log(value); // value 是 string，不是 Uint8Array
}
TextDecoderStream 的限制与兼容性注意点
它在浏览器中支持良好（Chrome 109+、Firefox 110+、Safari 16.4+），但不支持所有 TextDecoder 支持的编码。目前仅保证 utf-8、utf-16、iso-8859-1 可用；像 gbk、shift-jis 等非标准编码可能抛出 TypeError。
错误表现：Uncaught TypeError: Failed to construct 'TextDecoderStream': The encoding label is invalid —— 遇到这个，说明该编码未被 TextDecoderStream 实现支持，得退回用 TextDecoder 手动流式解码。
另外，TextDecoderStream 输出的是按块解码后的字符串，**不保证每块对应一个完整语义单位（如一行、一个 JSON 对象）**。如果你需要按行解析，得在 value 上做额外切分（例如用 value.split('\n') 并缓存未闭合的行）。
和手动 TextDecoder 流式解码的性能差异
两者底层都复用同一套 UTF-8 解码逻辑，性能几乎无差别。但 TextDecoderStream 少写几行代码、少踩一个“忘了清空缓冲区”的坑，实际开发中更稳。
真正容易被忽略的是：它不能和 Response.text() 混用——后者会消费整个 body 并返回 Promise，而 TextDecoderStream 是流式、可中断、可背压的。如果你需要实时响应（比如日志流、SSE、大文件预览），必须走流式路径，而不是等全部加载完再解码。
