Fetch 流式上传为什么需要 duplex 选项

我第一次把 ReadableStream 塞进 fetch() 的 body 时，真正让代码停下来的不是网络，而是一个看起来像“传输模式”的小选项：duplex。结论很明确：当请求体是可读流时，应在 RequestInit 中显式写 duplex: "half"；它表示当前 Fetch 采用半双工语义，并不承诺上传数据和响应可以在浏览器里任意交错。

官方资料：https://developer.mozilla.org/en-US/docs/Web/API/Request/duplex

duplex: "half" 解决的到底是什么

普通 Fetch 请求可以先准备好完整的请求体，再交给网络层发送。可读流不同：数据可能还在生产，浏览器不能假设它马上拥有全部字节，因此需要知道调用方选择了哪种请求体传输语义。duplex 就是在 Request 构造阶段补充这个声明。

当前 Web Fetch 语义里可用的值是 "half"。这里的 half 不是“只上传一半”，也不是 WebSocket 那种持续双向通道；它更接近“请求体可以按流发送，但响应处理遵循浏览器定义的半双工边界”。因此，把它理解成“允许 ReadableStream 作为请求体的开关”比理解成“上传下载同时自由进行”更准确。

流式请求体如何接到 Fetch

最小结构是“生产流 → Request body → duplex → fetch”。下面的流每次推送一小段文本，实际上传时可以替换成文件分片、编码器输出或业务消息。示例中的 /upload 只是接口占位符，服务端仍需按流式请求读取 HTTP body。

const stream = new ReadableStream({
  start(controller) {
    // 生产第一段数据；真实项目可改为文件或分片读取
    controller.enqueue(new TextEncoder().encode("chunk-1\n"));
    controller.enqueue(new TextEncoder().encode("chunk-2\n"));
    // 数据全部交付后关闭流，避免请求一直等待
    controller.close();
  },
  cancel(reason) {
    // 取消时释放文件句柄、读取器或业务队列
    console.warn("upload cancelled", reason);
  }
});

const response = await fetch("/upload", {
  method: "POST",
  body: stream,
  // ReadableStream 请求体需要显式声明半双工模式
  duplex: "half",
  headers: { "Content-Type": "application/octet-stream" }
});

if (!response.ok) {
  // HTTP 错误不会自动变成 rejected Promise，要显式判断状态码
  throw new Error(`upload failed: ${response.status}`);
}

这里有两个容易漏掉的细节。第一，controller.close() 决定请求体何时结束；如果数据来自外部读取器，还要在取消和异常路径中关闭资源。第二，fetch() 返回响应并不代表服务端已经成功保存全部数据，上传协议仍要由服务端返回明确状态，必要时还要设计校验和重试。

为什么它不是全双工以及如何处理兼容性

MDN 将 duplex 标为兼容性有限的实验性能力，并提醒它在一些常用浏览器中不可用。即使某个环境接受了 duplex 字段，也不要据此推断响应可以在请求体尚未结束时按任意节奏消费。对浏览器端来说，最重要的是把“能否建立流式 Request”和“服务端是否支持分段读取”分开判断。

可以先构造一个最小 Request 做特性检测；检测失败时不要继续把同一个流重复交给另一个请求，因为流通常是一次性的。若业务允许等待完整内容，优先把数据收集为 Blob 或 ArrayBuffer，再走普通 Fetch。

function supportsStreamingUpload() {
  try {
    // 只检测构造能力，不发送网络请求，也不消费业务数据
    const probe = new ReadableStream({
      start(controller) {
        controller.close();
      }
    });
    const request = new Request("/upload", {
      method: "POST",
      body: probe,
      duplex: "half"
    });
    return request.duplex === "half";
  } catch {
    // 构造阶段抛错时走缓冲上传分支
    return false;
  }
}

async function uploadBytes(bytes) {
  if (supportsStreamingUpload()) {
    // 业务代码应在这里创建新的、尚未消费的 ReadableStream
    return fetch("/upload", {
      method: "POST",
      body: new Blob([bytes]),
      headers: { "Content-Type": "application/octet-stream" }
    });
  }
  // 不支持流式请求体时，使用已缓冲的 Blob 保持接口行为稳定
  return fetch("/upload", {
    method: "POST",
    body: new Blob([bytes]),
    headers: { "Content-Type": "application/octet-stream" }
  });
}

上例为了突出分支结构，两个分支都使用了 Blob；生产代码应让支持流式的分支创建真正的新流，并把数据源的生命周期交给该请求。特性检测只能说明当前运行环境能否构造对应 Request，不能替代服务端协议、CORS、代理缓冲和超时配置的检查。

代码里容易踩的坑与选择建议

如果 body 是字符串却加上 duplex，通常只会让代码更难读；如果 body 是流却省略它，部分环境会在构造请求时直接报错。还要留意流只能消费一次、跨域上传可能触发 CORS 约束，以及服务端反向代理可能把分块数据重新缓冲。需要进度条、断点续传或可靠重试时，单靠 duplex 也不够，应该采用服务端可恢复的分片协议。

我的取舍是：大文件、可持续产生的数据且服务端能边收边处理时，采用 ReadableStream + duplex: "half"；数据量可控或浏览器兼容性优先时，直接使用 Blob；必须保证用户在旧环境里也能完成上传时，则把流式能力作为增强路径，保留缓冲上传作为明确降级。

常见问题

duplex: "half" 是不是表示只能上传不能接收响应？

不是。它描述的是请求体与响应处理之间的半双工语义，Fetch 仍会返回 Response；只是不要把它当成任意双向实时通道。

为什么加了 duplex 仍然上传失败？

可能是浏览器尚不支持、ReadableStream 已被消费、服务端或代理不接受分块请求，也可能是 CORS、超时或请求头配置问题。先区分构造阶段错误和网络返回错误。

不用流式上传时还要保留 duplex 吗？

不需要。字符串、Blob、ArrayBuffer、FormData 等普通请求体应按普通 Fetch 写法处理，减少无关兼容变量。