# web-streams-polyfill 中文文档

规范地址：https://npmcn.com/package/web-streams-polyfill/

版本：4\.5\.0
npm 元数据更新时间：2026-11-02T19:42:19.594Z
中文译文更新时间：2026-11-05T15:32:32.677Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/web-streams-polyfill
原文对照：https://npmcn.com/package/web-streams-polyfill/?lang=original
项目主页：https://github.com/MattiasBuelens/web-streams-polyfill#readme
源码仓库：https://github.com/MattiasBuelens/web-streams-polyfill

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：524 kB，12 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 8
- 运行依赖：0 个
- 首次发布：2016-03-02T18:29:50.194Z
- 最新版本发布：2026-11-02T19:42:19.188Z
- 近 30 天下载量：330668565（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：40（近 12 个月 3 个）

## 中文简介

网络流,基于WHWG的参考执行

## 安装

```sh
npm install web-streams-polyfill
```

也可以使用：`pnpm add web-streams-polyfill`、`yarn add web-streams-polyfill`、`bun add web-streams-polyfill`

## README

# 网络流-聚合

Web Streams,基于WHWG的光谱参考执行.

[![build status](https://api.travis-ci.com/MattiasBuelens/web-streams-polyfill.svg?branch=master)](https://travis-ci.com/MattiasBuelens/web-streams-polyfill) [![npm version](https://img.shields.io/npm/v/web-streams-polyfill.svg)](https://www.npmjs.com/package/web-streams-polyfill) [![license](https://img.shields.io/npm/l/web-streams-polyfill.svg)](https://github.com/MattiasBuelens/web-streams-polyfill/blob/master/LICENSE)

## 链接

-   [官方谱](https://streams.spec.whatwg.org/)
-   [参考执行情况](https://github.com/whatwg/streams)

## 使用量

这个库有多种变体:

-   `web-streams-polyfill`(单位:千美元) [填马](https://github.com/sindresorhus/ponyfill) 提供流执行 不取代任何全球,针对ES2015+环境. 建议用于节点6+应用程序,或用于支持现代浏览器的网络库.
-   `web-streams-polyfill/es5`:以ES5+环境为目标的马匹填充. 建议用于遗留的节点应用程序,或用于支持更老浏览器的网络库.
-   `web-streams-polyfill/polyfill`: 取代本地流执行的多填充, 目标为ES2015+环境. 推荐用于支持现代浏览器的 Web 应用程序 `<script>` 标签.
-   `web-streams-polyfill/polyfill/es5`:针对ES5+环境的多填充. 建议用于支持旧浏览器的网络应用程序 `<script>` 标签.

每个变体还包含TypeScript类型定义,与TypeScript中包含的流的DOM类型定义相兼容. 这些类型定义需要TypeScript版本5.7或更高.

在第4版中,变体列表被重新修改,以拥有更现代的默认并减少包的下载大小. 见 [移徙指南](https://github.com/MattiasBuelens/web-streams-polyfill/blob/master/MIGRATING.md) 更多信息.

用作多填充器 :

```html
<!-- option 1: hosted by unpkg CDN -->
<script src="https://unpkg.com/web-streams-polyfill/dist/polyfill.js"></script>
<!-- option 2: self hosted -->
<script src="/path/to/web-streams-polyfill/dist/polyfill.js"></script>
<script>
var readable = new ReadableStream();
</script>
```

用作节点模块 :

```js
var streams = require("web-streams-polyfill");
var readable = new streams.ReadableStream();
```

ES2015模块内用作马厩:

```js
import { ReadableStream } from "web-streams-polyfill";
const readable = new ReadableStream();
```

在ES2015模块内用作多填充:

```js
import "web-streams-polyfill/polyfill";
const readable = new ReadableStream();
```

> \[尖叫声\] **与内置流相兼容**
> 
> 如果您的浏览器或运行时间已经支持 Web Streams, 装入多填充会 _无条件_ 替换 全球 `ReadableStream`, (中文(简体) ), `WritableStream` 财务报告和审定财务报表 `TransformStream` 包含多填充版本的课. 然而,浏览器 API 喜欢 `fetch()` 将仍然使用 _内置_ 溪流课. 例如,这会导致令人惊讶的结果 `Response.body` 不会是 `instanceof ReadableStream` 在多填充取代全局后 `ReadableStream` 课.
> 
> 考虑使用 `ReadableStream.from()` 转换内置流(例如从 `fetch()`以一条充满的河流发誓, 或尝试 [有条件地装入多填充](https://npmcn.com/package/web-streams-polyfill/#readme-conditional-loading) 如果你不总是需要多填充.
> 
> 见 [问题20](https://github.com/MattiasBuelens/web-streams-polyfill/issues/20) 更多细节.

## 有条件装载

网络流是 [得到广泛支持](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API#browser_compatibility) 跨越所有现代浏览器 (包括Chrome,Firefox和Safari)和服务器运行时间(包括Node.js,Deno和Bun). 考虑使用特性检测来检查您的平台的内置流执行能否满足您的应用需求, 并仅在需要时加载多填充.

以下是几个有条件地加载多填充的例子:

```js
// Check for basic ReadableStream support
if (!globalThis.ReadableStream) {
  await import("web-streams-polyfill/polyfill");
}

// Check for basic TransformStream support
if (!globalThis.TransformStream) {
  await import("web-streams-polyfill/polyfill");
}

// Check for async iteration support
if (typeof globalThis.ReadableStream?.prototype[Symbol.asyncIterator] !== 'function') {
  await import("web-streams-polyfill/polyfill");
}
```

## 兼容性

这个 `polyfill` 财务报告和审定财务报表 `ponyfill` 变体在任何ES2015相容的环境中工作.

这个 `polyfill/es5` 财务报告和审定财务报表 `ponyfill/es5` 变体在具有全球特性的任何ES5兼容环境中起作用 `Promise`。 。 。 . 如果您需要支持旧浏览器或没有本地版本的节点版本 `Promise` 执行 (检查 [辅助表格](https://kangax.github.io/compat-table/es6/#test-Promise)),您必须首先包括 `Promise` 多边填充 (例如:. [承诺填充](https://www.npmjs.com/package/promise-polyfill)) (中文(简体) ).

[可同步支持 `ReadableStream`](https://streams.spec.whatwg.org/#rs-asynciterator) 所有变体中都有,但需要ES2018兼容环境或多填充 `Symbol.asyncIterator`。 。 。 .

[`WritableStreamDefaultController.signal`](https://streams.spec.whatwg.org/#ws-default-controller-signal) 在所有变体中都有,但需要一个全球 `AbortController` 建筑师。 必要时,考虑使用多填充法,例如: [中止控制器- 聚合](https://www.npmjs.com/package/abortcontroller-polyfill)。 。 。 .

[用 BOB 读取器读取](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamBYOBReader/read) 在所有变体中都有,但需要 `ArrayBuffer.prototype.transfer()` 或者说 `structuredClone()` 以正确转移给定视图的缓冲。 如果无法使用,则缓冲器在读取时不会被转移.

### 工具兼容性

此软件包使用 [子路径导出](https://nodejs.org/api/packages.html#subpath-exports) 对于它的变体。 因此,您需要12个或以上的节点才能 `import` 或者说 `require()` 这样的变体.

当使用 TypeScript 时, 请确定您 [`moduleResolution`](https://www.typescriptlang.org/tsconfig#moduleResolution) 设置为 `"node16"`, (中文(简体) ), `"nodenext"` 或者说 `"bundler"`。 。 。 .

## 遵守情况

多填充工具 [版本 `080852c` (2025年4月3日) (中文(简体) )](https://streams.spec.whatwg.org/commit-snapshots/080852ccd709e063cc6af239ae07fc040e365179/) 中 .

对多填充物进行测试 [网络平台测试](https://github.com/web-platform-tests/wpt/tree/ed5926bf7261f8fcd1716f1831c9480958784a5a/streams) 用于测试其本地执行. 混合填充旨在通过所有测试,但出于实际原因允许一些例外:

-   默认(ES2015)变体通过所有测试,但 [原型的测试 `ReadableStream`同步执行器](https://github.com/web-platform-tests/wpt/blob/ed5926bf7261f8fcd1716f1831c9480958784a5a/streams/readable-streams/async-iterator.any.js#L24)。 。 。 . 获取正确的 `%AsyncIteratorPrototype%` 需要使用同位素生成器(`async function* () {}`),在ES2018之前为无效语法. 相反,多填充 [创建自己的版本](https://github.com/MattiasBuelens/web-streams-polyfill/blob/v4.0.0/src/lib/readable-stream/async-iterator.ts#L143-L147) 这在功能上相当于真正的原型.
-   ES5变体通过与ES2015变体相同的测试,但关于构造器的具体特征,特性和方法的各种测试除外. 这些测试失败不影响多填充的运行时间行为. 例如:
    -   这个 `name` 下平面构造器的属性不正确.
    -   这个 `length` 带有可选参数的下平面构造器和方法的属性是不正确的.
    -   并非所有属性和方法都被正确标记为不可承担.
    -   下级分级方法不正确标出不可分级.

## 贡献者

多亏了这些人 [原始多填充](https://github.com/creatorrr/web-streams-polyfill)数字 :

-   迪旺克·辛格·托默(签名)[创建者rr](https://github.com/creatorrr)(中文(简体) )
-   安德斯·里乌塔(Anders Riutta) (英语:[马里乌塔](https://github.com/ariutta)(中文(简体) )

## 常见问题

### web-streams-polyfill 是什么？

网络流,基于WHWG的参考执行

### 如何安装 web-streams-polyfill？

在项目目录运行 npm install web-streams-polyfill，或使用 pnpm add / yarn add / bun add。

### web-streams-polyfill 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### web-streams-polyfill 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### web-streams-polyfill 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 8。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### web-streams-polyfill 可以商用吗？

web-streams-polyfill 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### web-streams-polyfill 的下载量有多少？

根据 npm 官方下载统计，web-streams-polyfill 在 2026/10/05 – 2026/11/03 这 30 天内被下载 330,668,565 次，日均约 11,022,286 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### web-streams-polyfill 还在维护吗？

最新版本 4\.5\.0 发布于 2026/11/03（3 天前）；至今共发布 40 个版本，其中过去 12 个月发布了 3 个；首次发布于 2016/03/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。