ngrok：开发者的内网穿透神器，不止于webhook回调本地调试

在本地开发时，你是否遇到过这些场景？需要调试微信支付回调却发现外网无法访问本地服务；想用手机测试后端接口却苦于没有公网地址；向客户演示功能时不得不临时部署到服务器。本文介绍的 ngrok 正是解决这些痛点的利器——一个命令，让你的本地服务秒变公网可访问。

为什么需要内网穿透

作为开发者，我们的日常工作流通常是这样的：

1. 在本地启动开发服务器（localhost:3000 或 localhost:8080）
2. 在浏览器中访问 http://localhost:PORT 进行调试
3. 一切正常后部署到测试/生产环境

但现实世界总有意外：

• Webhook 调试： 微信支付 、GitHub、钉钉等第三方服务的回调地址必须是公网 HTTPS URL，本地 localhost 无法接收
• 移动开发：手机 App 需要连接后端，但手机和电脑不在同一网络，或 iOS 要求 HTTPS
• 远程协作：向同事或客户展示功能，对方无法访问你的内网
• 跨域问题：前端调用后端 API 遇到 CORS 限制，需要模拟真实域名环境
• IoT 开发：硬件设备需要连接云端服务进行调试

传统的解决方案是部署到云服务器，但这意味着：

• 每次修改都要重新部署，反馈周期长
• 需要维护测试环境，成本增加
• 无法快速验证想法，影响开发效率

ngrok 的出现完美解决了这些问题。

什么是 ngrok

ngrok 是一个安全的内网穿透工具，它可以将本地运行的服务暴露到公网，让外部网络能够访问你电脑上的应用。无论你是前端开发、后端开发、移动开发还是 DevOps 工程师，ngrok 都能在多个场景下提升你的开发效率。

核心功能：

• 将本地 localhost 服务转为公网可访问的 HTTPS URL
• 实时查看和分析所有 HTTP 请求
• 支持自定义域名和子域名
• 提供请求重放功能，便于调试
• 支持 TCP、TLS、HTTP/2 等多种协议

ngrok安装与配置

macOS 安装

# 使用 Homebrew 安装
brew install ngrok

# 或手动安装
curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | \
  sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null && \
  echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | \
  sudo tee /etc/apt/sources.list.d/ngrok.list && \
  sudo apt update && sudo apt install ngrok

Windows 安装

# 使用 Chocolatey
choco install ngrok

# 使用 Scoop
scoop install ngrok

# 或下载 MSI 安装包：https://ngrok.com/download

Linux 安装

# 下载最新版本
wget https://bin.equinox.io/c/bNyj1mQVY4c/ngrok-v3-stable-linux-amd64.tgz

# 解压
tar xvzf ngrok-v3-stable-linux-amd64.tgz

# 移动到系统路径
sudo mv ngrok /usr/local/bin/

ngrok首次配置

1. 访问 ngrok.com 注册账号
2. 获取 Authtoken（Dashboard → Your Authtoken）
3. 配置本地 ngrok：

ngrok config add-authtoken YOUR_AUTHTOKEN

ngrok基础用法

1. HTTP 服务穿透（最常用）

将本地 Web 服务 8080 端口暴露到公网：

# 转发本地 8080 端口
ngrok http 8080

# 转发特定目录（静态文件）
ngrok http file:///Users/username/project/static

# 转发本地其他端口
ngrok http 3000
ngrok http 5000
ngrok http 8000

启动后你会看到：

Session Status                online
Account                       Your Name (Plan: Free)
Version                       3.35.0
Region                        Asia Pacific (ap)
Latency                       28ms
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://a1b2c3d4.ngrok-free.app -> http://localhost:8080

Connections                   ttl     opn     rt1     rt5     p50     p90
                              2       2       0.01    0.01    40.47   72.12

访问 https://a1b2c3d4.ngrok-free.app 即可访问你本地的 8080 端口服务。

首次访问可能出现安全提示，点击「Visit Site」即可：

如果浏览器页面显示：Invalid Host Header，解决方法是设置你的--host-header，比如：

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

2. 查看请求详情

ngrok 提供一个本地 Web 界面查看所有请求：

http://127.0.0.1:4040

在这个界面你可以：

• 查看完整的 HTTP 请求和响应
• 查看请求头、请求体、查询参数
• 重放任意请求
• 按状态码、路径过滤请求

3. 自定义子域名（付费功能）

# 使用固定子域名，避免每次重启 URL 变化
ngrok http --domain=myapp.ngrok.io 8080

# 使用自定义域名（需要 DNS 配置）
ngrok http --domain=dev.mycompany.com 8080

4. 密码保护

为公网访问添加基础认证：

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

ngrok核心应用场景

场景一：Webhook 调试（支付、短信、GitHub 等）

几乎所有第三方服务的 Webhook 都需要公网可访问的 URL。

微信支付回调调试：

ngrok http 8080
# 将 https://xxx.ngrok.io/api/notify 配置为回调地址

GitHub Webhook 开发：

ngrok http 3000
# 在 GitHub 仓库设置 Webhook 指向 https://xxx.ngrok.io/github/webhook

钉钉/企业微信机器人：

ngrok http 5000
# 将机器人回调地址配置为 ngrok 提供的 URL

场景二：移动 App 后端开发

开发移动应用时，需要让手机访问本地后端服务：

# 启动本地后端
ngrok http 8080

# 手机 App 配置 base URL 为 https://xxx.ngrok.io
# 无需部署到服务器即可真机调试

优势：

• 手机、模拟器都能访问
• 支持 HTTPS，符合 iOS ATS 要求
• 实时查看 App 发出的请求

场景三：前端跨域调试

前端开发时经常遇到跨域问题，需要后端配合：

# 前端运行在 localhost:3000
# 后端运行在 localhost:8080

# 将后端暴露到公网
ngrok http 8080

# 前端配置 API 地址为 ngrok URL
# 避免本地跨域问题，模拟生产环境

场景四：远程演示与协作

向客户或同事展示本地开发的功能：

# 启动本地项目
ngrok http 3000

# 将 https://xxx.ngrok.io 发送给其他人
# 对方无需安装任何环境即可查看效果

配合密码保护：

ngrok http 3000 --basic-auth="demo:demo123"

场景五：IoT 设备联调

智能家居、硬件设备开发时，设备需要连接云端服务：

# 模拟云端服务
ngrok tcp 1883  # MQTT 协议
ngrok tcp 5683  # CoAP 协议

# 设备配置 ngrok 提供的 TCP 地址和端口
# 实现本地调试物联网应用

场景六：数据库远程访问（临时）

临时需要让外部访问本地数据库（注意安全性）：

# 将本地 MySQL 暴露到公网（仅临时使用）
ngrok tcp 3306

# 获得类似 tcp://0.tcp.ngrok.io:12345 的地址
# 可在其他地方连接此地址访问本地数据库

⚠️ 安全警告： 生产数据库绝对不要这样暴露，仅用于临时调试。

场景七：SSH 远程访问内网服务器

通过 ngrok 实现内网服务器的远程 SSH 访问：

# 在内网服务器上运行
ngrok tcp 22

# 获得地址如 tcp://0.tcp.ngrok.io:12345

# 从外部连接
ssh user@0.tcp.ngrok.io -p 12345

场景八：静态网站快速分享

快速分享一个本地文件夹：

# 进入项目目录
cd my-project

# Python 快速启动 HTTP 服务
python3 -m http.server 8000

# 用 ngrok 暴露
ngrok http 8000

# 获得公网 URL，立即分享给他人

ngrok高级配置技巧

使用配置文件

创建 ngrok.yml 配置文件，避免每次输入长命令：

# ngrok.yml
version: "2"
authtoken: YOUR_AUTHTOKEN

tunnels:
  # Web 开发
  web:
    proto: http
    addr: 8080
    domain: myapp.ngrok.io
    inspect: true

  # API 服务
  api:
    proto: http
    addr: 3000
    subdomain: api-demo

  # 数据库
  mysql:
    proto: tcp
    addr: 3306
    remote_addr: 1.tcp.ngrok.io:12345

使用配置：

# 启动特定 tunnel
ngrok start web
ngrok start api

# 启动多个
ngrok start web api

# 启动全部
ngrok start --all

请求过滤与修改

通过 ngrok 的 Web 界面，你可以：

1. 重放请求： 右键任意请求 → Replay
2. 修改重放： Replay with modifications，修改请求头或 Body 后重放
3. 导出请求： 导出为 curl 命令或 HAR 文件

与开发工具集成

VS Code 集成：

安装 “ngrok for VS Code” 插件，一键启动隧道。

package.json 脚本：

{
  "scripts": {
    "dev": "next dev",
    "share": "ngrok http 3000",
    "share:prod": "ngrok http --domain=myapp.ngrok.io 3000"
  }
}

Makefile：

.PHONY: dev share

dev:
	npm run dev

share:
	ngrok http 3000

ngrok免费版 vs 付费版对比

建议： 个人开发免费版够用，团队协作或需要固定域名建议付费。

安全注意事项

1. 不要暴露生产数据库： 仅临时调试使用 TCP 隧道
2. 使用密码保护： 敏感服务添加 --basic-auth
3. 及时关闭： 调试完成后立即关闭 ngrok
4. 验证签名： Webhook 回调务必验证请求签名（如微信支付）
5. IP 白名单： 如果服务支持，配置 ngrok 出口 IP 白名单

ngrok同类工具对比

如果你是在国内可能使用ngrok加载很慢，可以考虑以下国内内网穿透工具作为替代品：

• cpolar ：用法与ngrok几乎一模一样，国内速度很快，有免费版

总结

ngrok 是每个开发者工具箱中的必备工具，它解决了"本地服务如何让外部访问"这一常见问题。无论是调试 Webhook、移动开发、远程协作还是临时演示，ngrok 都能显著提升开发效率。

核心使用流程：

1. 本地启动服务 → npm run dev / go run . / python app.py
2. 启动 ngrok → ngrok http PORT
3. 获得公网 URL → 配置到第三方服务或分享给他人
4. 查看请求详情 → http://127.0.0.1:4040

掌握 ngrok，让你的开发调试更加高效顺畅。

参考资源

• ngrok官网：https://ngrok.com
• 文档：https://ngrok.com/docs
• GitHub：https://github.com/inconshreveable/ngrok
• 定价：https://ngrok.com/pricing

本文首发于 阿小信的博客-人言兑 ，转载请注明出处。