ngrok 教學：讓外網 Webhook 安全連到你的本機開發環境

管
管管
4 分鐘閱讀 ·
教學文章 技術分享
ngrok 網路隧道示意圖

開發 Telegram Bot、LINE Bot、Slack App 或串接 GitHub Webhook 時，你一定遇過這個問題：第三方服務需要打 webhook 到你的伺服器，但你的開發環境在本機，外網根本連不到。

傳統做法是把服務部署到雲端測試，或是設定路由器的 port forwarding，但這些方法不是麻煩就是有安全風險。今天介紹的 ngrok，能讓你用一行指令就把本機服務暴露給外網，開發測試超級方便。

什麼是 Webhook？為什麼需要外網可訪問？

Webhook 是一種「反向 API」的設計模式。一般 API 是你主動發請求去拿資料，而 Webhook 是當事件發生時，對方主動發請求通知你。

常見的 Webhook 應用場景：

  • 聊天機器人：Telegram、LINE、Discord 收到訊息時通知你的 bot
  • 支付通知：金流平台（綠界、藍新）付款完成時回呼
  • CI/CD：GitHub push 時觸發自動部署
  • 第三方整合：Notion、Slack、Trello 等服務的事件通知

這些服務都需要一個外網可訪問的 URL 來接收通知。如果你的開發環境在本機 localhost:8000，外網是打不進來的。

傳統做法的問題

方法一：直接部署到雲端測試

每次改 code 都要部署一次，開發效率極低。而且雲端環境和本機環境可能有差異，debug 困難。

方法二：路由器 Port Forwarding

把路由器的某個 port 轉發到你的電腦。問題是：

  • 需要固定 IP 或 DDNS
  • 公司網路、咖啡廳 WiFi 根本沒權限設定
  • 直接暴露本機，有安全風險

方法三：租一台有公網 IP 的 VPS

成本高、設定麻煩，只是為了測試 webhook 太殺雞用牛刀。

ngrok：一行指令搞定內網穿透

ngrok 是一個內網穿透（tunneling）服務。它會幫你建立一條從公網到你本機的安全隧道，讓外部請求可以轉發到你的 localhost。

運作原理：

  • ngrok 在你的電腦上啟動一個 client
  • 這個 client 連線到 ngrok 的雲端伺服器
  • ngrok 給你一個公開的 URL（如 https://abc123.ngrok.io）
  • 所有打到這個 URL 的請求，都會透過隧道轉發到你的 localhost

安裝與基本使用

步驟一：安裝 ngrok

macOS（使用 Homebrew）：

brew install ngrok

Windows / Linux：

到 ngrok 官網 下載對應版本，解壓縮後放到 PATH 中。

步驟二：註冊並設定 authtoken

免費版需要註冊帳號取得 authtoken：

ngrok config add-authtoken YOUR_TOKEN

步驟三：啟動隧道

假設你的本機服務跑在 port 8000：

ngrok http 8000

執行後會看到類似這樣的輸出：

Forwarding    https://a1b2c3d4.ngrok.io -> http://localhost:8000

這個 https://a1b2c3d4.ngrok.io 就是你的公開 URL，把它填到第三方服務的 webhook 設定裡即可。

實際案例：Clawdbot Webhook 設定

以 Clawdbot（一個 AI 助理框架）為例，它需要接收來自 Telegram、LINE 等平台的 webhook。

傳統做法是把 Clawdbot 部署到有公網 IP 的伺服器，但開發測試時我們想在本機跑。這時 ngrok 就派上用場：

步驟

  1. 在本機啟動 Clawdbot（假設監聽 port 3000）
  2. 執行 ngrok http 3000
  3. 把 ngrok 給的 URL 設定到 Telegram Bot 的 webhook： 
    https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://a1b2c3d4.ngrok.io/webhook/telegram
  4. 現在 Telegram 的訊息就會透過 ngrok 轉發到你的本機 Clawdbot

開發時可以即時看到請求、debug、修改程式碼，不用一直部署到雲端。

ngrok 進階功能

查看請求記錄

ngrok 提供一個本地的 Web 介面（預設 http://127.0.0.1:4040），可以看到所有經過隧道的請求，包括：

  • Request / Response 的完整內容
  • Headers、Body
  • 可以重送請求（Replay）方便 debug

固定子網域（付費功能）

免費版每次啟動會拿到隨機的 URL，付費版可以設定固定子網域：

ngrok http --subdomain=myapp 8000

這樣 URL 就會是 https://myapp.ngrok.io，不用每次都去改 webhook 設定。

加上 Basic Auth

如果擔心隧道被亂打，可以加上認證：

ngrok http --basic-auth="user:password" 8000

安全注意事項

ngrok 雖然方便，但要注意幾點：

  • 不要長時間暴露：開發測試完記得關掉，不要讓隧道一直開著
  • 免費版 URL 會變：每次重啟都是新的 URL，不適合正式環境
  • 敏感資料：流量會經過 ngrok 的伺服器，不要傳輸機密資料
  • 正式環境請用正規方案：Cloudflare Tunnel、自建 reverse proxy 等

替代方案

除了 ngrok，還有其他類似的服務：

  • Cloudflare Tunnel：免費、穩定，適合長期使用
  • localtunnel：npx localtunnel --port 8000，完全免費
  • localhost.run：用 SSH 就能用，免安裝
  • Tailscale Funnel：如果你有用 Tailscale VPN

總結

ngrok 是開發者測試 webhook 的神器。一行指令就能把本機服務暴露給外網，省去部署、設定路由器的麻煩。搭配它的 Web 介面，debug 請求也變得超級方便。

下次開發 bot 或串接第三方服務時，試試 ngrok http 8000，你會愛上這種即開即用的開發體驗。