# @deco-cx/warp-node 中文文档

规范地址：https://npmcn.com/package/%40deco-cx/warp-node/

版本：0\.3\.23
npm 元数据更新时间：2026-05-22T20:53:36.900Z
中文译文更新时间：2026-11-11T19:25:59.176Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40deco-cx/warp-node
原文对照：https://npmcn.com/package/%40deco-cx/warp-node/?lang=original
项目主页：https://github.com/deco-cx/warp-node
源码仓库：https://github.com/deco-cx/warp-node

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

- 包体积（解压后）：135 kB，64 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：2 个
- 首次发布：2025-07-28T17:25:05.739Z
- 最新版本发布：2026-05-22T20:53:36.556Z
- 近 30 天下载量：17060（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 1 个）

## 中文简介

WebSocket 为节点.js 和其他运行时间提供隧道库

## 安装

```sh
npm install @deco-cx/warp-node
```

也可以使用：`pnpm add @deco-cx/warp-node`、`yarn add @deco-cx/warp-node`、`bun add @deco-cx/warp-node`

## README

[![NPM Version](https://img.shields.io/npm/v/@deco-cx/warp-node)](https://www.npmjs.com/package/@deco-cx/warp-node) [![NPM Downloads](https://img.shields.io/npm/dm/@deco-cx/warp-node)](https://www.npmjs.com/package/@deco-cx/warp-node) [![GitHub License](https://img.shields.io/github/license/deco-cx/warp-node)](https://github.com/deco-cx/warp-node/blob/main/LICENSE)

# 曲速节点

**曲速节点** 是允许您本地运行的 HTTP 服务器的简单工具 拥有一个公开的URL,作为服务的一种容易自收自支的选择 喜欢 `ngrok`. 为 Node.js 和其他 JavaScript 运行时间执行 Warp 节点 目标是提供灵活性和最低限度的依赖.

该项目有两个主要组成部分:

-   **服务器**:可以部署在服务器上,它连接外部世界,并且是 从任意域访问.
-   **客户端**: 本地运行以连接本地运行的 HTTP 端点 或非公共网络.

![image](https://github.com/deco-cx/warp/assets/5839364/914ab723-02cf-4a1a-9799-72671ffa5974)

## 安装

```bash
npm install @deco-cx/warp-node
```

## 所需资源

-   节点.js 22+(对于节点.js环境 - 需要承诺 ). 有resolvers支持)
-   在 Cloudflare 工人、Deno 和其他 JavaScript 运行时间工作

## 服务器

Warp 服务器打开一个单独的 HTTP 端口,Warp 客户端连接到该端口 升级到 WebSocket 连接。 向此 HTTP 端口转发每个请求 (基于客户端的 HOST 头) 到相应的连接的 Wart 客户端 连接,然后满足请求.

### 使用量

要启动 Warp 服务器,请导入 `serve` 从 Warp 软件包和 用适当的配置调用它.

#### 示例

```typescript
import { serve } from "@deco-cx/warp-node";

const port = 8080; // The port where the Warp server will listen
const apiKeys = ["YOUR_API_KEY1", "YOUR_API_KEY2"]; // Array of API keys for authentication

const server = serve({ port, apiKeys });
console.log(`Warp server listening on port ${port}`);
```

#### 参数

-   `port`: Warp 服务器将监听连接的端口号码.
-   `apiKeys`: 用于客户端认证的API密钥阵列.

## 客户端

Warp客户端连接到Warp服务器. 连接后,客户共享 指定 API 密钥及其想要接收请求的域.

### 使用量

要连接客户端到 Warp 服务器,请导入 `connect` 函数从 曲速包并用适当的配置调用.

#### 示例

```typescript
import { connect } from "@deco-cx/warp-node";

const port = 3000; // The local port you want to expose
const domain = "www.your.domain.com"; // The domain name for your service
const server = "wss://YOUR_SERVER"; // The WebSocket URL of your Warp server
const apiKey = "YOUR_API_KEY"; // The apiKey

const { registered, closed } = await connect({
  domain,
  localAddr: `http://localhost:${port}`,
  server,
  apiKey,
});

await registered;
console.log("Client registered successfully");

closed.then(() => {
  console.log("Connection closed");
});
```

#### 参数

-   `domain`: 访问您本地主机服务的域名 .
-   `localAddr`:您想要曝光的服务的地方地址(例如, `http://localhost:3000`) (中文(简体) ).
-   `server`: 您 Warp 服务器的 WebSocket URL( 例如, ), `wss://YOUR_SERVER`) (中文(简体) ).
-   `apiKey`: 连接到 Warp 服务器的 apiKey .

#### 返回值

-   `registered`: 当客户端成功时解决的承诺 在服务器上注册.
-   `closed`:当连接到服务器的连接关闭时解决的许诺.

## 示例工作流程

以下是建立Warp服务器和客户端的完整例子:

### 服务器

```typescript
import { serve } from "@deco-cx/warp-node";

const port = 8080;
const apiKeys = ["YOUR_API_KEY1", "YOUR_API_KEY2"];

const server = serve({ port, apiKeys });
console.log(`Warp server listening on port ${port}`);
```

### 客户端

```typescript
import { connect } from "@deco-cx/warp-node";

const port = 3000;
const domain = "www.your.domain.com";
const server = "wss://YOUR_SERVER";
const apiKey = "API_KEY";

(async () => {
  const { registered, closed } = await connect({
    domain,
    localAddr: `http://localhost:${port}`,
    server,
    apiKey,
  });

  await registered;
  console.log("Client registered successfully");

  closed.then(() => {
    console.log("Connection closed");
  });
})();
```

## 运行时间相容性

Warp节点被设计为跨越多个JavaScript运行时间的工作:

-   **节点.js 22+**: 完全支持本地 HTTP 和 WebSocket 处理
-   **云花岗工人**: 工作与 WebSocketPair API
-   **德诺**: 与 Deno 的 WebSocket 执行兼容
-   **阿宝**: 应该与 Bun 的 WebSocket 支持合作

库自动检测运行时环境并使用 适当的API.

## 类型脚本支持

这个包包括了完整的TypeScript定义. 无额外 `@types` 需要软件包.

```typescript
import {
  connect,
  type ConnectOptions,
  type HandlerOptions,
  serve,
} from "@deco-cx/warp-node";
```

## 解决问题

### 共同问题

-   **无效的 API 密钥**: 确保您使用的 API 密钥在 `apiKeys` 服务器上的数组.
-   **连接被拒绝**: 检查服务器是否运行并可在 指定 WebSocket URL.
-   **域无法访问**: 确保域名配置正确 指向Warp服务器.
-   **节点.js 版本**:确保您完全使用节点22或以后使用 兼容性.

## 捐款

此工程为开源. 提出问题或 拉请求.

## 许可证

麻省理工学院执照 - 看 [自由主义](https://npmcn.com/package/%40deco-cx/warp-node/LICENSE) 详细文件.

## 常见问题

### @deco-cx/warp-node 是什么？

WebSocket 为节点\.js 和其他运行时间提供隧道库

### 如何安装 @deco-cx/warp-node？

在项目目录运行 npm install @deco-cx/warp-node，或使用 pnpm add / yarn add / bun add。

### @deco-cx/warp-node 支持 TypeScript 吗？

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

### @deco-cx/warp-node 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @deco-cx/warp-node 需要什么版本的 Node\.js？

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

### @deco-cx/warp-node 可以商用吗？

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

### @deco-cx/warp-node 的下载量有多少？

根据 npm 官方下载统计，@deco-cx/warp-node 在 2026/10/12 – 2026/11/10 这 30 天内被下载 17,060 次，日均约 569 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @deco-cx/warp-node 还在维护吗？

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