# @expo/ngrok 中文文档

规范地址：https://npmcn.com/package/%40expo/ngrok/

版本：4\.1\.3
npm 元数据更新时间：2026-09-23T11:26:40.230Z
中文译文更新时间：2026-11-14T05:24:56.271Z
软件包许可：BSD-2-Clause

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

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

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

- 包体积（解压后）：28.1 kB，7 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=10\.19\.0
- 运行依赖：4 个
- 首次发布：2017-07-03T22:17:59.201Z
- 最新版本发布：2023-11-17T11:37:50.936Z
- 近 30 天下载量：3783242（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 0 个）

## 中文简介

ngrok 的节点包

## 安装

```sh
npm install @expo/ngrok
```

也可以使用：`pnpm add @expo/ngrok`、`yarn add @expo/ngrok`、`bun add @expo/ngrok`

## README

# 无 [![Tests](https://github.com/bubenshchykov/ngrok/workflows/Tests/badge.svg)](https://github.com/bubenshchykov/ngrok/actions) ![TypeScript compatible](https://img.shields.io/badge/typescript-compatible-brightgreen.svg) [![npm](https://img.shields.io/npm/v/ngrok.svg)](https://www.npmjs.com/package/ngrok) [![npm](https://img.shields.io/npm/dm/ngrok.svg)](https://www.npmjs.com/package/ngrok)

![alt ngrok.com](https://ngrok.com/static/img/overview.png)

-   [使用量](https://npmcn.com/package/%40expo/ngrok/#readme-usage)
    -   [本地安装](https://npmcn.com/package/%40expo/ngrok/#readme-local-install)
    -   [全局安装](https://npmcn.com/package/%40expo/ngrok/#readme-global-install)
    -   [Auth 托肯语](https://npmcn.com/package/%40expo/ngrok/#readme-auth-token)
    -   [连接](https://npmcn.com/package/%40expo/ngrok/#readme-connect)
        -   [选项](https://npmcn.com/package/%40expo/ngrok/#readme-options)
    -   [断开连接](https://npmcn.com/package/%40expo/ngrok/#readme-disconnect)
    -   [配置](https://npmcn.com/package/%40expo/ngrok/#readme-config)
    -   [检查员](https://npmcn.com/package/%40expo/ngrok/#readme-inspector)
    -   [API 密码](https://npmcn.com/package/%40expo/ngrok/#readme-api)
        -   [列出隧道](https://npmcn.com/package/%40expo/ngrok/#readme-list-tunnels)
        -   [开始隧道](https://npmcn.com/package/%40expo/ngrok/#readme-start-tunnel)
        -   [获取隧道细节](https://npmcn.com/package/%40expo/ngrok/#readme-get-tunnel-details)
        -   [停止隧道](https://npmcn.com/package/%40expo/ngrok/#readme-stop-tunnel)
        -   [名单请求](https://npmcn.com/package/%40expo/ngrok/#readme-list-requests)
        -   [重放请求](https://npmcn.com/package/%40expo/ngrok/#readme-replay-request)
        -   [删除所有请求](https://npmcn.com/package/%40expo/ngrok/#readme-delete-all-requests)
        -   [请求细节](https://npmcn.com/package/%40expo/ngrok/#readme-request-detail)
    -   [代理服务器](https://npmcn.com/package/%40expo/ngrok/#readme-proxy)
-   [博览会变化](https://npmcn.com/package/%40expo/ngrok/#readme-expo-changes)
-   [如何运作](https://npmcn.com/package/%40expo/ngrok/#readme-how-it-works)
-   [ngrok 二进制更新](https://npmcn.com/package/%40expo/ngrok/#readme-ngrok-binary-update)
-   [用点头符](https://npmcn.com/package/%40expo/ngrok/#readme-using-with-nodemon)
-   [贡献者](https://npmcn.com/package/%40expo/ngrok/#readme-contributors)
-   [升级到第4版](https://npmcn.com/package/%40expo/ngrok/#readme-upgrading-to-version-4)
    -   [类型脚本](https://npmcn.com/package/%40expo/ngrok/#readme-typescript)

## 使用量

### 本地安装

用 npm 安装软件包 :

```bash
npm install ngrok
```

然后使用 `ngrok.connect()` 开始ngrok和打开地道.

```javascript
const ngrok = require('ngrok');
(async function() {
  const url = await ngrok.connect();
})();
```

此模块使用 `node>=10.19.0` 与同步/等待。 用于基于召回的版本 [2.3.0 (单位:千美元)](https://github.com/bubenshchykov/ngrok/blob/330674233e3ec77688bb692bf1eb007810c4e30d/README.md)。 。 。 .

### 全局安装

```bash
npm install ngrok -g
ngrok http 8080
```

对于Linux 上的全球安装, 您可能需要运行 `sudo npm install --unsafe-perm -g ngrok` 应付 [性质](https://github.com/bubenshchykov/ngrok/issues/115#issuecomment-380927124) npm 邮购脚本.

### Auth 托肯语

您可以创建基本的 http- https- tcp 地道 [自定义](https://ngrok.com/docs#authtoken)。对于自定义的子域和更多域,您应当通过 [在 ngrok.com 注册](https://ngrok.com/)。一旦您设置了自动调试机,它就会被存储在 ngrok 配置中,并用于所有隧道。 您可以直接设置验证符 :

```javascript
await ngrok.authtoken(token);
```

或将认证传给 `connect` 这样的方法 :

```javascript
await ngrok.connect({authtoken: token, ...});
```

### 连接

有几种方法可以创建隧道 Ngrok使用 `connect` 方法.

默认, `connect` 将打开 HTTP 隧道到端口 80

```javascript
const url = await ngrok.connect(); // https://757c1652.ngrok.io -> http://localhost:80
```

您可以将端口号码传递到 `connect` 指定端口:

```javascript
const url = await ngrok.connect(9090); // https://757c1652.ngrok.io -> http://localhost:9090
```

或者你可以通过一个选项对象,例如:

```javascript
const url = await ngrok.connect({proto: 'tcp', addr: 22}); // tcp://0.tcp.ngrok.io:48590
const url = await ngrok.connect(opts);
```

#### 选项

有很多选择,你可以通过 `connect`,这里有一些例子:

```javascript
const url = await ngrok.connect({
  proto: 'http', // http|tcp|tls, defaults to http
  addr: 8080, // port or network address, defaults to 80
  auth: 'user:pwd', // http basic authentication for tunnel
  subdomain: 'alex', // reserved tunnel name https://alex.ngrok.io
  authtoken: '12345', // your authtoken from ngrok.com
  region: 'us', // one of ngrok regions (us, eu, au, ap, sa, jp, in), defaults to us
  configPath: '~/git/project/ngrok.yml', // custom path for ngrok config file
  binPath: path => path.replace('app.asar', 'app.asar.unpacked'), // custom binary path, eg for prod in electron
  onStatusChange: status => {}, // 'closed' - connection is lost, 'connected' - reconnected
  onLogEvent: data => {}, // returns stdout messages from ngrok process
});
```

见 [所有隧道定义选项的 ngrok 文档](https://ngrok.com/docs#tunnel-definitions) 包括: `name, inspect, host_header, bind_tls, hostname, crt, key, client_cas, remote_addr`。 。 。 .

关于区域的说明:第一隧道所使用的区域将用于以下所有隧道.

### 断开连接

Ngrok进程和所有地道将在节点进程完成后被杀死. 为了手动阻止地道:

```javascript
await ngrok.disconnect(url); // stops one
await ngrok.disconnect(); // stops all
await ngrok.kill(); // kills ngrok process
```

HTTP地道上的注释:默认绑定 tls是真实的,所以每当使用HTTP原型两条地道时都会被创建出-HTTP和HTTP. 如果断开HTTPS隧道,HTTP隧道仍然开放. 您可能想要通过 HTTP 版本 URL 来关闭它们, 或者简单地将全部断开 `ngrok.disconnect()`。 。 。 .

### 配置

你可以使用ngrok的 [配置文件](https://ngrok.com/docs#config),然后通过 `name` 选项。 配置文件允许存储隧道选项 。 Ngrok在这里寻找他们:

```
OS X	/Users/example/.ngrok2/ngrok.yml
Linux	/home/example/.ngrok2/ngrok.yml
Windows	C:\Users\example\.ngrok2\ngrok.yml
```

您可以指定自定义 `configPath` 当做地道.

### 检查员

当隧道建成后,您可以使用http://127.0.0.1:4040中托管的ngrok接口来检查通过ngrok制作的webhooks.

内部主机为同一 URL [客户端 api](https://ngrok.com/docs#client-api)。这个软件包暴露了一个API客户端,该客户端将API包裹起来,您可以自己管理地道.

```javascript
const url = await ngrok.connect();
const api = ngrok.getApi();
const tunnels = await api.listTunnels();
```

您也可以获取内部 API 的 URL :

```javascript
const url = await ngrok.connect();
const apiUrl = ngrok.getUrl();
```

### API 密码

API 包装器可以访问所有 [ngrok 客户端 API](https://ngrok.com/docs#client-api) 方法:

```javascript
const url = await ngrok.connect();
const api = ngrok.getApi();
```

#### [列出隧道](https://ngrok.com/docs#list-tunnels)

```javascript
const tunnels = await api.listTunnels();
```

#### [开始隧道](https://ngrok.com/docs#start-tunnel)

```javascript
const tunnel = await api.startTunnel(opts);
```

#### [获取隧道细节](https://ngrok.com/docs#tunnel-detail)

```javascript
const tunnel = await api.tunnelDetail(tunnelName);
```

#### [停止隧道](https://ngrok.com/docs#stop-tunnel)

```javascript
await api.stopTunnel(tunnelName);
```

#### [名单请求](https://ngrok.com/docs#list-requests)

```javascript
await api.listRequests(options);
```

#### [重放请求](https://ngrok.com/docs#replay-request)

```javascript
await api.replayRequest(requestId, tunnelName);
```

#### [删除所有请求](https://ngrok.com/docs#delete-requests)

```javascript
await api.deleteAllRequests();
```

#### [请求细节](https://ngrok.com/docs#request-detail)

```javascript
const request = await api.requestDetail(requestId);
```

### 代理服务器

-   如果你是公司代理的幕后黑手 有问题安装ngrok,你可以设定 `HTTPS_PROXY` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}我们来修理它 ngrok的后置脚本使用 [`got`](https://www.npmjs.com/package/got) 模块以获取二进制和 [`hpagent`](https://github.com/delvedor/hpagent) 模块支持 HTTPS 代理。 您需要安装 `hpagent` 作为依赖的模块
-   如果您正在使用 CA 文件, 请在环境变量中设置路径 `NGROK_ROOT_CA_PATH`。在邮站脚本中下载 ngrok 二进制需要路径

## 博览会变化

### 获取活动进程处理

给产卵的ngrok工艺使用一个把手

```javascript
ngrok.getActiveProcess(); // returns ChildProcess
```

### 使用 @ expo/ngrok- bin来管理 ngrok 二进制

版本二进制的好处 。 这个 `binPath` 选项不支持.

## 如何运作

`npm install` 从正式的 ngrok 主机下载您平台的 ngrok 二进制 。 自己设置二进制 `NGROK_CDN_URL` 安装 ngrok 之前的环境变量 。 强制特定平台 `NGROK_ARCH`,例如: `NGROK_ARCH=freebsdia32`。 。 。 .

第一次创建地道时, ngrok 进程会产出并运行到断开或母进程被杀死时. 所有进一步的地道都通过通常在http://127.0.0.1:4040上运行的内部ngrok API连接或断开.

## ngrok 二进制更新

如果您想从您的软件直接强制更新 ngrok 二进制, 您可以要求 `ngrok/download` 模块并调用 `downloadNgrok` 直接函数 :

```javascript
const downloadNgrok = require('ngrok/download');
downloadNgrok(myCallbackFunc, { ignoreCache: true });
```

## 用点头符

如果您想要在更改时重新启动您的应用程序, 您可以使用 [节点恶魔](https://nodemon.io/)。此博客文章显示 [如何使用 nodemon 和 ngrok 一起使用 这样您的服务器会重新启动, 但您的隧道不会](https://philna.sh/blog/2021/03/15/restart-app-not-tunnel-ngrok-nodemon/)。 。 。 .

## 贡献者

请跑 `git update-index --assume-unchanged bin/ngrok` 不覆盖 [ngrok 树枝](https://github.com/bubenshchykov/ngrok/blob/master/bin/ngrok) 在你的公关。 不幸的是,它不能被赋予.

测试套房包括没有认证的基本用途,以及免费和付费认证的功能。 作为环境变量,您可以提供自己的符号,否则会给出警告并忽略某些规格(局部和在PR构建中). GitHub Actions 向主分支提供真实的代号,并运行所有规格 .

## 升级到第4版

更新软件包的主要动力是消除对已贬值软件的依赖 `request` 模块. `request` 改为: `got`。主要呼吁 `ngrok` 函数, `connect`, (中文(简体) ), `authtoken`, (中文(简体) ), `disconnect`, (中文(简体) ), `kill`, (中文(简体) ), `getVersion` 财务报告和审定财务报表 `getUrl` 回应与第3版相同.

更新了HTTP库,意味着被包裹的API会改变,因此创建了一个客户端类,其中包含了可用API调用的方法. 见上文文件 [如何使用 API 客户端](https://npmcn.com/package/%40expo/ngrok/#readme-api)。 。 。 .

反之在于你不再需要知道你需要的API方法的路径了. 例如,要在第三版中列出运行中的地道,你会做到:

```javascript
const api = ngrok.getApi();
const tunnels = await api.get('api/tunnels');
```

现在你可以打电话给 `listTunnels` 函数 :

```javascript
const api = ngrok.getApi();
const tunnels = await api.listTunnels();
```

### 类型脚本

从第3版到第4版,捆绑型号也进行了大修. 大多数类型生活在 `Ngrok` 命名空间,特别是 `Ngrok.Options` 替换 `INgrokOptions`。 。 。 .

## 常见问题

### @expo/ngrok 是什么？

ngrok 的节点包

### 如何安装 @expo/ngrok？

在项目目录运行 npm install @expo/ngrok，或使用 pnpm add / yarn add / bun add。

### @expo/ngrok 支持 TypeScript 吗？

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

### @expo/ngrok 支持 ESM 还是 CommonJS？

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

### @expo/ngrok 需要什么版本的 Node\.js？

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

### @expo/ngrok 可以商用吗？

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

### @expo/ngrok 的下载量有多少？

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

### @expo/ngrok 还在维护吗？

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