下面我将为你详细介绍 ngrok 的命令，从基础到高级,并提供丰富的示例。

安装和认证 (准备工作)

在使用任何命令之前,你需要先完成安装和认证。

安装

根据你的操作系统选择安装方式：

使用包管理器 (推荐)

• macOS (Homebrew):

  
  （图片来源网络，侵删）

  brew install ngrok/ngrok/ngrok

• Windows (Chocolatey):

  choco install ngrok

• Linux (Debian/Ubuntu):

  # 下载并安装 GPG 密钥
  sudo apt update
  sudo apt install curl
  curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo gpg --dearmor -o /usr/share/keyrings/ngrok.gpg
  # 将 ngrok 存储库添加到你的系统
  echo "deb [signed-by=/usr/share/keyrings/ngrok.gpg] https://ngrok-agent.s3.amazonaws.com/binary/ngrok-stable $(. /etc/os-release && echo $VERSION_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ngrok.list
  # 安装 ngrok
  sudo apt update
  sudo apt install ngrok

直接下载二进制文件

1. 访问 ngrok 官网下载页面。
2. 下载适合你操作系统的版本。
3. 将下载的可执行文件移动到你的系统 PATH 中，/usr/local/bin (macOS/Linux) 或 C:\Windows\System32 (Windows)。

认证

ngrok 需要一个免费的账户来获取 Authtoken，这个 Token 用于将你的 ngrok 客户端与你的账户关联起来。

1. 注册/登录: 访问 ngrok.com 注册一个免费账户。

2. 获取 Token: 登录后，进入你的 Dashboard 页面，找到你的 Authtoken。

3. 配置 Token: 在你的终端中运行以下命令，将 Token 保存到本地配置文件中。

   ngrok config add-authtoken YOUR_AUTHTOKEN

   将 YOUR_AUTHTOKEN 替换为你自己 Dashboard 中的 Token。

核心命令

ngrok 的核心功能是通过子命令来实现的，最常用的是 http 和 tcp。

ngrok http - 隧道本地 Web 服务

这是最常见的用法，用于将本地的 HTTP/HTTPS 服务暴露到公网。

基本语法:

ngrok http [本地端口] [选项]

示例:

1. 隧道本地 8080 端口 假设你的本地网站运行在 http://localhost:8080。

   ngrok http 8080

   运行后，ngrok 会给你一个公网 URL，https://random-string.ngrok.io 和 http://random-string.ngrok.io，所有访问这个公网 URL 的请求都会被转发到你的 localhost:8080。

2. 隧道 HTTPS 本地服务 如果你的本地服务运行在 https://localhost:8443。

   ngrok http https://localhost:8443

3. 同时隧道 HTTP 和 HTTPS

   ngrok http 8080 --host-header=localhost:8080

   --host-header 选项可以告诉 ngrok 当收到请求时，应该将 Host 请求头设置为什么，这对于某些需要特定 Host 头的应用（如 WordPress）很有用。

4. 绑定自定义域名 你可以将你自己的域名（api.mydomain.com）绑定到 ngrok 隧道。

   • 在 ngrok Dashboard 的 Domains 页面添加一个子域名（api.mydomain.com）。
   • 配置你的 DNS，将 api.mydomain.com 的 CNAME 指向 ngrok 提供的域名（ngrok-free.app）。
   • 使用以下命令启动隧道：

     ngrok http http://localhost:8080 --host-header=api.mydomain.com

ngrok tcp - 隧道任意 TCP 端口

http 子命令只处理 HTTP 流量，如果你的服务是数据库（如 MySQL, PostgreSQL）、SSH、游戏服务器或其他非 HTTP 协议，你需要使用 tcp 子命令。

基本语法:

ngrok tcp [本地端口] [选项]

示例:

1. 隧道本地 MySQL 数据库 (3306 端口)

   ngrok tcp 3306

   运行后，ngrok 会给你一个类似 tcp://0.tcp.ngrok.io:12345 的地址，你可以使用 tcp.ngrok.io 作为主机，12345 作为端口，从任何地方连接到你的本地 MySQL 数据库。

2. 隧道本地 SSH 服务 (22 端口)

   ngrok tcp 22

   你会得到一个类似 tcp://0.tcp.ngrok.io:54321 的地址，然后你就可以用这个地址和端口进行 SSH 连接了：

   ssh your_username@0.tcp.ngrok.io -p 54321

高级选项和功能

指定地区

ngrok 的免费版会在美国随机选择一个地区，付费版可以选择特定地区,以获得更低的延迟。

ngrok http 8080 --region=ap  # 亚太地区 ( jp, sg, au, in)
ngrok http 8080 --region=eu  # 欧洲
ngrok http 8080 --region=au  # 澳大利亚
ngrok http 8080 --region=sa  # 南美洲
ngrok http 8080 --region=jp  # 日本

完整的地区代码列表可以在 ngrok 文档 中找到。

身份验证

为了防止别人随意访问你的本地服务，你可以为 ngrok 隧道添加 HTTP Basic Auth。

ngrok http 8080 --auth="username:password"

这样，任何访问你公网 URL 的人都需要输入 username 和 password 才能进入。

查看和管理会话

当 ngrok 在后台运行时,你需要一些命令来管理它。

1. 查看活动会话列表

   ngrok status

   这会显示当前正在运行的所有隧道。

2. 停止所有会话

   ngrok stop all

3. 停止特定会话 你需要知道会话的 ID（从 ngrok status 或启动日志中获取）。

   ngrok stop <session_id>

4. 在后台运行 (不阻塞终端) 使用 -log 和 logfile 选项将日志输出到文件，然后你可以用 Ctrl+Z 将进程挂起到后台，并用 bg 命令使其继续运行。 更简单的方式是使用 nohup (Linux/macOS) 或直接在新的终端窗口中运行。

Web 界面

ngrok 启动后，它会提供一个本地的 Web UI 地址（通常是 http://127.0.0.1:4040），在这个界面里,你可以：

• 实时查看所有 HTTP 请求和响应。
• 检查请求头、响应头、请求体和响应体。
• 重放请求。
• 查看隧道的详细统计信息。

这对于调试 API 和排查问题非常有用。

完整命令行参数参考

你可以使用 ngrok help [command] 或 ngrok help [flag] 来查看特定命令的帮助。

# 查看 http 命令的所有选项
ngrok help http
# 查看所有全局标志
ngrok help

一些常用的全局标志：

• -config, -c: 指定配置文件的路径。
• -log, -l: 指定日志文件的路径。
• -log-format: 指定日志格式 (json 或 text)。
• -log-level: 指定日志级别 (debug, info, warn, error)。

配置文件 (.ngrok2/ngrok.yml)

对于复杂的配置，手动输入命令会很麻烦。ngrok 支持使用 YAML 配置文件。

1. 创建配置文件 配置文件通常位于用户主目录下的 .ngrok2 文件夹中，名为 ngrok.yml。

   # macOS / Linux
   mkdir -p ~/.ngrok2
   nano ~/.ngrok2/ngrok.yml
   # Windows
   mkdir %USERPROFILE%\.ngrok2
   notepad %USERPROFILE%\.ngrok2\ngrok.yml

2. 配置文件示例

   # ngrok.yml
   tunnels:
     # 定义一个名为 "my-web-app" 的隧道
     my-web-app:
       addr: 8080 # 本地端口
       proto: http # 协议
       host_header: localhost:8080 # 可选：Host 头
       auth: "user:pass" # 可选：Basic Auth
     # 定义一个名为 "my-db" 的隧道
     my-db:
       addr: 3306 # 本地端口
       proto: tcp # 协议
       region: jp # 可选：地区
   # 启动时自动运行所有定义的隧道
   # ngrok start --all

3. 使用配置文件启动隧道

   # 启动单个命名的隧道
   ngrok start my-web-app
   # 启动所有在配置文件中定义的隧道
   ngrok start --all

希望这份详细的指南能帮助你完全掌握 ngrok 的使用！