Fetch 上传 ReadableStream 时怎么设置 duplex: half

给 fetch() 的 body 传入 ReadableStream 时，RequestInit 里要显式写 duplex: "half"。它不是“打开全双工上传”的开关，而是 Fetch 规范目前允许的唯一值：浏览器发送完整个请求后再处理响应。缺少这个字段，浏览器可能直接以 TypeError 拒绝请求。

duplex: half 到底解决了什么

duplex 属于请求初始化参数，不是服务器响应头，也不是把请求变成 WebSocket。当前标准只接受 "half"：请求体全部发送完之后，用户代理才处理响应。它听起来像“半双工”，但对上传代码的直接要求很简单：只要 body 是 ReadableStream，就把字段放在和 method、headers 同一级。

因此下面两种写法不要混淆。body: file 或 body: blob 不需要为了它们额外添加 duplex；body: stream 则需要显式声明。duplex: "full" 也不是可用的替代值，当前 Fetch 标准保留了 full，但没有把它作为有效配置开放。

用 ReadableStream 组织可结束的上传请求

流式上传最容易留下的故障不是参数拼写，而是流永远不结束。下面用一组内存中的字节块模拟文件分片；真实项目可以把文件切片、压缩器或其他生产者接到同一个接口。示例中的注释只标出关键边界，避免把业务数据误当成协议配置。

const chunks = [
  new TextEncoder().encode("part-A\n"),
  new TextEncoder().encode("part-B\n"),
];

const stream = new ReadableStream({
  start(controller) {
    // 逐块交给请求体，真实生产者应在数据耗尽后结束流
    for (const chunk of chunks) controller.enqueue(chunk);
    controller.close();
  },
});

const controller = new AbortController();
const response = await fetch("/upload", {
  method: "POST",
  headers: { "Content-Type": "application/octet-stream" },
  body: stream,
  duplex: "half", // ReadableStream 请求体必须显式声明
  signal: controller.signal,
});

这里的 close() 表示没有更多请求体数据；如果生产者发生异常，应调用 controller.error(error)，而不是继续 enqueue。上传内容较大时还要考虑生产速度与消费速度，不能无限制地把数据压入内存队列。服务端是否按块读取、是否要求 Content-Length，则是另一个协议边界，不能靠 duplex 自动解决。

上传失败、取消和兼容性要分开处理

调用成功返回 Response 只代表 Fetch 取得了响应，不代表业务上传成功。先检查 response.ok，再读取服务端结果；主动取消会抛出 AbortError，网络失败通常没有可用的 HTTP 状态码。把这三类情况写进不同分支，日志才有诊断价值。

try {
  const response = await fetch("/upload", {
    method: "POST",
    body: stream,
    duplex: "half", // 只对流式请求体声明 half
    signal: controller.signal,
  });

  if (!response.ok) {
    // HTTP 到达服务端但业务未成功，保留状态码便于排查
    throw new Error(`upload failed: ${response.status}`);
  }
  console.log("upload accepted");
} catch (error) {
  if (error.name === "AbortError") {
    console.log("upload cancelled"); // 用户主动取消，不当成服务端故障
  } else {
    console.error("upload unavailable", error); // 网络或流本身的异常
  }
}

上线前检查浏览器和服务端边界

MDN 将 Request.duplex 标为 Limited availability，不能只看本机浏览器能否构造请求。可以把能力检查放在上传入口，但不要用读取属性作为唯一判断，因为部分浏览器虽然接受构造参数，却不一定暴露同样的可读属性。

如果目标浏览器集合包含不支持该能力的环境，推荐在真正发送前做特性分支；不要发送一次失败请求后才决定回退。还要记住，浏览器能力通过不等于接口契约通过，服务端仍需明确是否允许分块传输、最大请求体和中断后的清理方式。

相关问题

duplex: "half" 能让前端边上传边读取响应吗？

不能把它理解成完整双工。当前有效值是 half，浏览器会先发送完整请求，再处理响应；如果业务必须边写边读，需要评估其他协议或服务端设计。

普通 File 上传也要写 duplex 吗？

本文讨论的必需条件是请求体为 ReadableStream。File、Blob 等普通 BodyInit 不因为是上传就自动需要 duplex，仍应以目标浏览器和服务端的实际契约为准。