我在前端接入流式接口时,最容易遇到的现象不是“完全读不到”,而是页面先显示了一小段内容,随后既没有继续追加,也没有明确告诉用户已经结束。这个问题通常不是 Fetch 只返回了一块,而是代码没有持续调用 reader.read(),或者把最后一次返回的 done 信号漏掉了。
直接答案:先等待 fetch() 得到 Response,从 response.body 取得 ReadableStream,调用 getReader(),然后循环等待 reader.read()。每次 done 为 false 时处理 value;当 done 为 true 时,说明流自然结束。用户主动离开页面或点击停止,则用 AbortController 取消,不要把取消当成服务端正常完成。
官方资料:https://developer.mozilla.org/en-US/docs/Web/API/Streams_API/Using_readable_streams
一、触发信号:为什么只显示第一块
fetch() 的 Promise 解决,通常只代表响应头已经可用,并不代表整个响应体已经读完。真正的响应体在 response.body 中,它是一个可读流;拿到流之后还要绑定 reader,并持续等待后续数据。
排查时我会先看下面三件事:
| 现象 | 优先判断 | 处理方向 |
|---|---|---|
body 为空 | 当前响应没有可读取的流,或运行环境不提供 | 记录状态并回退到普通响应处理 |
只处理了一次 read() | 只消费了第一块 | 用循环再次调用 reader.read() |
| 一直等不到“完成” | 把“收到一块”误当成“读取结束” | 只在 done === true 时收尾 |
| 停止后进入普通错误提示 | 主动 abort 与网络错误没有分支 | 通过 signal.aborted 区分用户取消 |
二、快速判断:response.body 和 reader 各自负责什么
response.body 是数据入口,getReader() 把这个入口交给一个 reader。reader 会锁定流,在锁释放前不能再用另一个 reader 读取同一条流。因此,代码里不要一边调用 response.text(),一边又调用 response.body.getReader();响应体只能按一种方式消费。
每次 read() 返回一个 Promise,解决值形如 { done, value }:
done: false:当前有一块数据,通常是Uint8Array,交给业务处理。done: true:流已经关闭,value不再代表有效数据,执行一次收尾。- Promise 被拒绝:读取过程出错,进入异常分支;主动取消也可能从这里表现出来。
三、处理步骤:用 reader 循环逐块读取
下面这段函数适合把文本流追加到页面、日志面板或编辑器缓冲区。它把 HTTP 状态判断、分块读取、字符解码和 reader 清理放在同一条流程里。
async function readTextStream(url, { signal, onText }) {
// 传入 signal,让调用方可以在页面离开时取消请求
const response = await fetch(url, { signal });
// HTTP 响应到了不代表业务成功,先处理状态码
if (!response.ok) {
throw new Error(`HTTP ${response.status}`);
}
// 某些响应没有可读 body,不能继续调用 getReader()
if (!response.body) {
throw new Error("响应没有可读取的 body");
}
const reader = response.body.getReader();
const decoder = new TextDecoder("utf-8");
try {
while (true) {
// 每次只等待下一块,完成时 done 会变成 true
const { done, value } = await reader.read();
if (done) {
// flush 可能补出最后一个被暂存的多字节字符
const tail = decoder.decode();
if (tail) onText(tail);
return;
}
// stream:true 允许 UTF-8 字符跨越两块数据边界
onText(decoder.decode(value, { stream: true }));
}
} finally {
// 不再读取时释放流锁,避免后续接管时遇到 locked 状态
reader.releaseLock();
}
}
const controller = new AbortController();
readTextStream("/api/report", {
signal: controller.signal,
// 收到一块就追加,不等待完整响应
onText(chunk) {
document.querySelector("#output").textContent += chunk;
},
}).catch((error) => {
// 主动取消是用户动作,不必显示成网络故障
if (controller.signal.aborted) return;
console.error("流读取失败", error);
});
// 停止按钮可以调用这句取消尚未完成的请求
// controller.abort();
这里有一个容易忽略的细节:文本解码器也有状态。一个汉字的 UTF-8 字节可能被拆到两块里,如果每次都直接创建新解码器,页面会出现替换字符。持续复用同一个 TextDecoder,并在中间块使用 { stream: true },最后在 done 分支调用一次无参数的 decode() 完成 flush。
四、处理完成信号:done、错误和取消必须分开
“完成”不是“这一块比较短”,也不是“服务端暂时没有新内容”。只有 reader 返回 done: true 才能结束自然读取流程。若 Promise 被拒绝,应该进入错误处理;如果请求由 AbortController.abort() 触发,则优先判断 signal.aborted,让界面显示“已停止”或静默收尾。
done、abort 与读取错误的结束路径对比图(原创结构图,不是运行截图)。如果希望用户点击停止,调用方可以保存 controller:
const stopController = new AbortController();
// 让请求和 reader 共享同一个取消信号
readTextStream("/api/report", {
signal: stopController.signal,
onText(chunk) {
appendToOutput(chunk);
},
}).then(() => {
// 只有自然读到 done=true 才标记为完成
markStatus("完成");
}).catch((error) => {
if (stopController.signal.aborted) {
// 取消是可预期操作,不覆盖已经展示的部分内容
markStatus("已停止");
return;
}
markStatus("读取失败");
reportError(error);
});
document.querySelector("#stop").addEventListener("click", () => {
// abort 会让 fetch/reader 的等待尽快结束
stopController.abort();
});
五、回滚路径:不需要逐块展示时别强行使用 reader
流式读取适合逐字展示、长任务进度或希望尽早呈现首段内容的场景。如果业务只在完整 JSON 或完整文本到齐后处理,直接使用 response.json() 或 response.text() 更简单,也不会承担 reader 锁、增量解码和取消分支的维护成本。
另一种较简洁的流读取写法是异步迭代:
async function readByIteration(url, signal) {
// 仍然把取消信号交给 fetch,而不是只在循环外设置变量
const response = await fetch(url, { signal });
if (!response.body) throw new Error("响应没有 body");
for await (const chunk of response.body) {
// 每次循环拿到一块 Uint8Array,按需解码或转存
consumeChunk(chunk);
}
// 异步迭代自然结束后,表示流已经没有更多块
markStatus("完成");
}
这个写法省去了手动的 while 和 releaseLock(),但当你需要精细控制每次 read()、做统一的 reader 清理,或要把“自然完成”和“取消”暴露给更复杂的状态机时,显式 reader 循环更容易排查。
六、上线确认:用三个信号判断流程是否健康
- 收到分块:每次
done === false都有一条可追踪的追加路径,页面不会只处理首块。 - 自然完成:仅在
done === true后标记完成,并完成 decoder flush。 - 主动取消:取消后不把预期操作当成网络故障,也不留下长期占用的 reader 锁。
我自己的取舍是:先用上面的显式 reader 版本把状态走通,再根据界面复杂度决定是否改成 for await...of。只要记住“fetch() 解决不等于 body 读完”“read() 要持续调用”“done 才是自然结束”,大多数只显示首段、无法收尾和取消误报的问题都能很快定位。
常见问题
response.body 为什么可能是 null?
当前响应可能没有可读取的 body,或者运行环境没有提供对应的流能力。代码应先判断,再选择错误提示或普通响应处理。
read() 返回 done=true 时还要处理 value 吗?
不应把它当作普通数据块处理。此时重点是完成 decoder flush、更新完成状态并退出读取循环。
为什么停止后 catch 会执行?
取消可能让等待中的 Fetch 或 reader Promise 以拒绝结束。通过同一个 AbortSignal 判断 signal.aborted,即可把主动取消和真正的读取错误分开。

Linux /proc/PID/status 怎样读取进程状态字段
