# @currentspace/http3 中文文档

规范地址：https://npmcn.com/package/%40currentspace/http3/

版本：1\.0\.0
npm 元数据更新时间：2026-10-31T19:55:44.004Z
中文译文更新时间：2026-10-31T22:35:45.102Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40currentspace/http3
原文对照：https://npmcn.com/package/%40currentspace/http3/?lang=original
项目主页：https://github.com/currentspace/http3#readme
源码仓库：https://github.com/currentspace/http3

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

- 包体积（解压后）：3.1 MB，179 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：0 个
- 首次发布：2026-03-13T03:59:13.118Z
- 最新版本发布：2026-10-31T19:55:43.672Z
- 已发布版本数：30（近 12 个月 30 个）

## 中文简介

基于Node.js的HTTP/3服务器和客户端，由Cloudflare quiche提供支持

## 安装

```sh
npm install @currentspace/http3
```

也可以使用：`pnpm add @currentspace/http3`、`yarn add @currentspace/http3`、`bun add @currentspace/http3`

## README

# @currentspace / http3

针对Node.js 24+的HTTP/3、HTTP/2和原始QUIC服务器/客户端包，由Rust + quache提供支持。

## 功能

-   HTTP/3服务器和客户端通过QUIC/UDP
-   HTTP/2在同一侦听器上通过TLS/TCP回退
-   原始QUIC：双向流，数据报，会话恢复，自定义ALPN
-   运行时选择: `auto`， `fast`， `portable`，或者 `wasm`
-   平台原生I/O: kqueue (macOS), io\_uring （Linux快速路径）， `poll` （Linux可移植路径）
-   WASM运行时(`runtimeMode: 'wasm'`)用于HTTP/3和原始QUIC客户端，加上a 仅节点WASM服务器-没有本机 `.node` 需要插件，并确认 在真正的Cloudflare workerd中运行
-   获取/ SSE EventSource适配器
-   通过表达兼容性 `@currentspace/http3/express`

## 安装

```bash
npm install @currentspace/http3
```

版本 **1.0.0** 增加了自动WASM回退，有限制的大写入，外观 运行时元数据，以及Linux和Intel macOS的本机包。早些时候 当本地插件不可用时，安装需要显式WASM。

保持可选的依赖项为本机性能启用。如果是本地插件 不能加载，默认值 `auto` 模式选择绑定的WASM运行时并发出 `WARN_HTTP3_RUNTIME_FALLBACK`． 根包包含JavaScript、声明、 WASM和CLI；它不捆绑本机二进制文件、文档或示例。

| 平台 | 本机包目标 | 当插件无法加载时 |
| --- | --- | --- |
| macOS arm64 / x64 | `darwin-arm64` / `darwin-x64` | WASM |
| Linux glibc arm64 / x64 | `linux-arm64-gnu` / `linux-x64-gnu` | WASM |
| Linux arm64 / x64 （Alpine） | `linux-arm64-musl` / `linux-x64-musl` | WASM |
| 窗户 | 无 | WASM |
| 其他Node平台 | 发布矩阵中没有 | WASM;平台资质不同 |

所有六个本机目标都使用匹配的1.0.0 sidecars。没有安装时间 编译器回退。看到 [`docs/SUPPORT_MATRIX.md`](https://github.com/currentspace/http3/blob/HEAD/docs/SUPPORT_MATRIX.md).

## 快速服务器示例

```ts
import { createSecureServer } from '@currentspace/http3';

const server = createSecureServer({
  key: process.env.TLS_KEY_PEM,
  cert: process.env.TLS_CERT_PEM,
}, (stream, headers) => {
  stream.respond({ ':status': '200', 'content-type': 'text/plain' });
  stream.end(`hello ${String(headers[':path'] ?? '/')}`);
});

server.listen({ port: 443 }); // Dual-stack ::, all interfaces.
```

## 地方发展

在0.9.7 +, `npx @currentspace/http3 dev-cert --out .certs --trust` 创建一个约束 localhost CA，显式安装本地信任，并颁发证书。从一个 构建的源代码检出使用 `node bin/http3.cjs dev-cert --out .certs --trust`. 使用 `key.pem`/`cert.pem` 在服务器上设置 `NODE_EXTRA_CA_CERTS=/absolute/path/.certs/ca.pem` **启动Node客户端之前**. 此库的本机/WASM客户端需要一个显式的 `ca` 选项。

Chrome还需要 `--origin-to-force-quic-on=localhost:1` 用于本地可信QUIC。 未使用的端口启用local-root异常；应用程序仍然 通过Alt-Svc协商H3。监听器默认为双堆栈 `::` (所有 接口)，所以localhost工作在IPv4和IPv6上。看到 [本地发展指南](https://github.com/currentspace/http3/blob/HEAD/docs/LOCAL_DEVELOPMENT.md) 要删除信任，请使用服务器 配置、浏览器启动命令和仅环回绑定。

## 快速客户端示例

```ts
import { connectAsync } from '@currentspace/http3';

const session = await connectAsync('example.com:443');
const stream = session.request({
  ':method': 'GET',
  ':path': '/',
  ':authority': 'example.com',
  ':scheme': 'https',
}, { endStream: true });
```

## 流式传输和取消

H3请求和响应主体在本机和 WASM运行时。暂停一个读者最终会给对方带来反压力；其他流 在连接上可以继续。QUIC接收窗口和传输队列是 与Node的可读高水位标志分开。

使用 `pipeline()` 或者等待 `drain` 当 `write()` 返回 `false`． 写 回调, `drain`, `finish` 描述本地写许可，而不是收据或 对等体的确认。销毁未完成的客户端流将取消它 远程并拒绝挂起的写；正常的双工完成不会重置它。

## 运行时模式

每个支持quic的API都接受：

-   `runtimeMode: 'auto' | 'fast' | 'portable' | 'wasm'`
-   `fallbackPolicy: 'error' | 'warn-and-fallback'`
-   `onRuntimeEvent(info)`

返回的客户端会话和服务器对象公开 `runtimeInfo`, `auto` 回退还会发出带有代码的进程警告 `WARN_HTTP3_RUNTIME_FALLBACK`. 返回的Node facade `createNodeServerFactory`.

`auto` 更喜欢原生的，保留Linux `fast` → `portable` 回退时 Io\_uring不可用。如果绑定本身无法加载， `auto` 与 默认的 `warn-and-fallback` 策略在构造原生状态之前选择WASM。 该警告标识操作系统、体系结构、Linux libc和加载程序失败。 `runtimeInfo.reasonCode` 是 `native-binding-unavailable` 对于这种情况。 显式的 `fast`/`portable`，或者 `auto` 与 `fallbackPolicy: 'error'`，而不是失败 与 `ERR_HTTP3_RUNTIME_UNSUPPORTED`． 显式WASM从不探测本机加载。

```ts
import { connectQuicAsync } from '@currentspace/http3';

const session = await connectQuicAsync('https://sfu:9080', {
  alpn: ['sfu-repl'],
  rejectUnauthorized: false,
  runtimeMode: 'auto',
  fallbackPolicy: 'warn-and-fallback',
});

console.log(session.runtimeInfo);
```

看到 [`docs/RUNTIME_MODES.md`](https://github.com/currentspace/http3/blob/HEAD/docs/RUNTIME_MODES.md) 对于部署矩阵， 功能需求、Docker指南、拓扑策略和原始端点 合同。

客户端拓扑现在在实现中是显式的：

-   原始QUIC快速客户端每个绑定族共享一个worker和一个本地UDP端口
-   H3快速客户端每个绑定族共享一个worker和一个本地UDP端口
-   macOS可移植模式保持相同的共享客户机-worker所有权模型 最高的 `kqueue`
-   QUIC和H3服务器仍然是每个端口一个工作人员的架构

使用内置基准测试来检查运行时选择和内部选择 反应堆计数器:

```bash
npm run bench:quic -- --profile smoke
npm run bench:h3 -- --profile smoke
```

## WASM运行时

`runtimeMode: 'wasm'` 运行HTTP/3和原始QUIC客户端和Node服务器 `wasm32-wasip1` 构建相同的quiche + BoringSSL协议核心，没有 本地的 `.node` 插件:

```ts
import { connectAsync } from '@currentspace/http3';

const session = await connectAsync('example.com:443', { runtimeMode: 'wasm' });
```

大节点流写入，包括 `res.end(buffer)`，在限定范围内被允许 WASM下的切片。继续尊重可写反压；并发工作 仍然共享有限的WASM堆。本机写入保留其现有路径。

消费者测量2026-10-30，在macOS arm64 / Node 26.13上使用0.9.9 使用本机客户机，在WASM下发现大约5,060-5,270个请求/s 10,500-12,300本机可移植，用于并发50的1,000个小型get。流 32 MiB的下载速度为91-93 MiB/s，而不是836-933 MiB/s。这些描述了那些 其他主机上的工作负载，而不是性能保证。使用本机包 throughput-sensitive部署;WASM保持开发和较小的工作负载 无需插件即可使用。

服务器端(`Http3SecureServer.listen()` / `QuicServer.listen()`)也 支持 `runtimeMode: 'wasm'`,节点只。客户端构建另外有 已在真正的Cloudflare workerd中运行验证-参见 [`examples/workerd-client`](https://github.com/currentspace/http3/blob/HEAD/examples/workerd-client/README.md);唯一的 真正的workerd部署的剩余障碍是Workers没有出站 UDP客户端套接字API[cloudflare / workerd # 4463](https://github.com/cloudflare/workerd/issues/4463)）。

看到 [`docs/WASM_RUNTIME.md`](https://github.com/currentspace/http3/blob/HEAD/docs/WASM_RUNTIME.md) 获取完整的使用指南 和当前Node/workerd支持矩阵 [`docs/WASM_CLIENT_PLAN.md`](https://github.com/currentspace/http3/blob/HEAD/docs/WASM_CLIENT_PLAN.md) 对于设计。

## 原始快速mTLS

-   原始QUIC客户端可以通过稳定的公开使用mTLS `cert` 和 `key` 选项 `connectQuic()` 和 `connectQuicAsync()`.
-   原始QUIC服务器支持显式客户端证书策略 `clientAuth`，默认为 `require` 当一个验证 `ca` 配置。
-   原始的QUIC服务器会话公开经过验证的对等证书，因此应用程序可以检查或使用Node的精确客户端证书 `X509Certificate` API。

看到 [`CHANGELOG.md`](https://github.com/currentspace/http3/blob/HEAD/CHANGELOG.md) 查阅发行说明及 [`docs/RELEASE_EVIDENCE.md`](https://github.com/currentspace/http3/blob/HEAD/docs/RELEASE_EVIDENCE.md) 对于当前 发布审计分类账和注意事项。

## 快速快速服务器

```ts
import { createQuicServer } from '@currentspace/http3';

const server = createQuicServer({
  key: process.env.TLS_KEY_PEM,
  cert: process.env.TLS_CERT_PEM,
});

server.on('session', (session) => {
  session.on('stream', (stream) => {
    stream.pipe(stream); // echo
  });
});

await server.listen(4433, '0.0.0.0');
```

## 快速客户端

```ts
import { connectQuicAsync } from '@currentspace/http3';

const session = await connectQuicAsync('127.0.0.1:4433', {
  rejectUnauthorized: false,
});

const stream = session.openStream();
stream.end(Buffer.from('hello QUIC'));

const chunks: Buffer[] = [];
stream.on('data', (c) => chunks.push(c));
stream.on('end', () => console.log(Buffer.concat(chunks).toString()));
```

## 兼容性的表面

实验 [节点风格的服务器工厂](https://github.com/currentspace/http3/blob/HEAD/docs/NODE_SERVER.md),介绍了 在0.9.4中，支持fasttify集成。版本0.9.5添加了兼容性修复 由 [js自定义服务器示例](https://github.com/currentspace/http3/blob/HEAD/examples/nextjs/README.md).

-   `@currentspace/http3` -规范API。
-   `@currentspace/http3/parity` -用于迁移的http2风格别名。
-   `@currentspace/http3/h3` —HTTP/3扩展命名空间。

包根也导出 `createNodeServerFactory` 和 `createExpressHandler`． 子路径声明使用 `typesVersions` 对于遗留 打印稿 `moduleResolution: "node"`;现代Node16/NodeNext/捆绑器解析 继续使用 `exports`． 不需要环境模块声明。

从0.9.7开始，本机和WASM H3请求体是流控制的：缓慢的或 暂停处理程序保留客户端。一个4 MiB的上传可以通过慢速流 具有默认值的处理程序 `maxBufferedRequestBytes: 1024 * 1024` (1 MiB)。 此选项限制传输流中缓冲的未读字节，包括数据 阅读暂停时已经在飞行；这不是一个总的上传大小限制。 超过上限会重置流，但大型流上传通常不会 需要更高的值。框架车身尺寸限制仍然适用。看到 [请求缓冲](https://github.com/currentspace/http3/blob/HEAD/docs/NODE_SERVER.md#request-buffering-and-shutdown).

## 示例

-   [原始API示例](https://github.com/currentspace/http3/blob/HEAD/examples/raw-api/README.md)
-   [快速适配器示例](https://github.com/currentspace/http3/blob/HEAD/examples/express-adapter/README.md)
-   [Hono `serveFetch()` 例子](https://github.com/currentspace/http3/blob/HEAD/examples/hono/README.md)
-   [Next.js自定义服务器与HTTP/3和快速刷新](https://github.com/currentspace/http3/blob/HEAD/examples/nextjs/README.md)
-   [基于HTTP/3的netjs](https://github.com/currentspace/http3/blob/HEAD/examples/nestjs/README.md)
-   [Next.js和NestJS与Express在一个进程中](https://github.com/currentspace/http3/blob/HEAD/examples/nextjs-nestjs/README.md) (0.9.6 +)

## 从这里开始

-   [快速入门](https://github.com/currentspace/http3/blob/HEAD/docs/QUICKSTART.md)
-   [运行时模式和部署矩阵](https://github.com/currentspace/http3/blob/HEAD/docs/RUNTIME_MODES.md)
-   [WASM运行时指南](https://github.com/currentspace/http3/blob/HEAD/docs/WASM_RUNTIME.md)
-   [支持矩阵](https://github.com/currentspace/http3/blob/HEAD/docs/SUPPORT_MATRIX.md)
-   [配置选项参考](https://github.com/currentspace/http3/blob/HEAD/docs/CONFIGURATION_OPTIONS.md)
-   [错误处理指南](https://github.com/currentspace/http3/blob/HEAD/docs/ERROR_HANDLING.md)
-   [更新日志](https://github.com/currentspace/http3/blob/HEAD/CHANGELOG.md)

## 部署与操作

-   [QUIC指南](https://github.com/currentspace/http3/blob/HEAD/docs/QUIC_GUIDE.md)
-   [生产文档索引](https://github.com/currentspace/http3/blob/HEAD/docs/README.md)
-   [HTTP/2奇偶矩阵](https://github.com/currentspace/http3/blob/HEAD/docs/HTTP2_PARITY_MATRIX.md)
-   [ECS / Fargate部署](https://github.com/currentspace/http3/blob/HEAD/docs/ECS_FARGATE_DEPLOYMENT.md)
-   [AWS NLB QUIC直通](https://github.com/currentspace/http3/blob/HEAD/docs/AWS_NLB_QUIC_PASSTHROUGH.md)
-   [跨实例的会话票证密钥](https://github.com/currentspace/http3/blob/HEAD/docs/SESSION_TICKET_KEYS.md)

## 贡献者和维护者

-   [测试策略](https://github.com/currentspace/http3/blob/HEAD/docs/TEST_STRATEGY.md)
-   [贡献指南](https://github.com/currentspace/http3/blob/HEAD/CONTRIBUTING.md)
-   [发放证据分类账](https://github.com/currentspace/http3/blob/HEAD/docs/RELEASE_EVIDENCE.md)
-   [释放runbook](https://github.com/currentspace/http3/blob/HEAD/docs/RELEASE_RUNBOOK.md)

## 常见问题

### @currentspace/http3 是什么？

基于Node\.js的HTTP/3服务器和客户端，由Cloudflare quiche提供支持

### 如何安装 @currentspace/http3？

在项目目录运行 npm install @currentspace/http3，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 http3，可以用 npx http3 直接运行。

### @currentspace/http3 支持 TypeScript 吗？

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

### @currentspace/http3 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @currentspace/http3 需要什么版本的 Node\.js？

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

### @currentspace/http3 可以商用吗？

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

### @currentspace/http3 还在维护吗？

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