Ngrok 教學｜一鍵讓 Localhost 變成公開網址

Ngrok 能做什麼：最快讓別人看到你程式的方法

「程式在我電腦跑得好好的，但客戶想看怎麼辦？」

這是每個開發者都會遇到的問題。把程式部署到伺服器太麻煩，用 USB 傳給客戶更不現實。

Ngrok 就是為了解決這個問題而生——只要一行指令，你的 localhost 就會變成一個公開網址，任何人都能連線。

本文會從安裝到進階使用，完整教你 Ngrok 的所有功能。

要點一－Ngrok 是什麼？能解決什麼問題？

Ngrok 簡介

Ngrok 是一個網路穿透工具（tunneling tool），它會在你的電腦和 Ngrok 的雲端伺服器之間建立一條加密隧道。

簡單來說：

你的電腦 (localhost:3000)
         ↓ 加密隧道
    Ngrok 雲端伺服器
         ↓
公開網址 (https://abc123.ngrok-free.app)
         ↓
    任何人都能連線

能解決什麼問題？

1. 給客戶或團隊展示

不用部署，直接分享網址：

ngrok http 3000
# 得到 https://abc123.ngrok-free.app
# 把網址給客戶就能看了

2. Webhook 測試

Line Bot、Stripe、GitHub 等服務需要呼叫你的 API：

• 這些服務無法連到 localhost
• 用 ngrok 產生公開網址後，就能接收 Webhook

3. 跨裝置測試

想用手機測試網站？把 ngrok 網址貼到手機瀏覽器就行。

4. 臨時 Demo

開會時需要展示？開啟 ngrok 就有公開網址可用。

要點二－Ngrok 安裝教學

macOS 安裝

方法一：Homebrew（推薦）

brew install ngrok/ngrok/ngrok

方法二：手動下載

1. 前往 ngrok.com/download
2. 下載 macOS 版本
3. 解壓縮後移動到可執行路徑

unzip ngrok-v3-stable-darwin-amd64.zip
sudo mv ngrok /usr/local/bin

Windows 安裝

方法一：Chocolatey

choco install ngrok

方法二：手動下載

1. 前往 ngrok.com/download
2. 下載 Windows 版本
3. 解壓縮到任意資料夾
4. 加入環境變數 PATH

Linux 安裝

Ubuntu/Debian

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

驗證安裝

ngrok version
# ngrok version 3.x.x

看到版本號就代表安裝成功。

要點三－註冊帳號與設定 Authtoken

為什麼需要帳號？

Ngrok 免費版也需要帳號，這樣可以：

• 使用更長的連線時間
• 存取個人儀表板
• 管理多個隧道

註冊帳號

1. 前往 dashboard.ngrok.com
2. 選擇 Sign up
3. 可用 GitHub 或 Google 帳號快速註冊

設定 Authtoken

登入後，在儀表板找到你的 Authtoken：

Your Authtoken → 複製 token

然後在終端機設定：

ngrok config add-authtoken YOUR_AUTHTOKEN

這個只需要做一次，token 會存在本機設定檔。

要點四－基本使用：一行指令上線

最簡單的用法

假設你的程式跑在 port 3000：

ngrok http 3000

執行後會看到：

Session Status                online
Account                       [email protected] (Plan: Free)
Version                       3.x.x
Region                        Asia Pacific (ap)
Latency                       -
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://abc123.ngrok-free.app -> http://localhost:3000

重點資訊：

把網址給別人

複製 https://abc123.ngrok-free.app，任何人打開這個網址就會看到你的 localhost:3000。

本機監控介面

打開 http://127.0.0.1:4040，可以看到：

• 所有進來的請求
• Request/Response 內容
• 請求時間和狀態碼

這對於 debug Webhook 特別有用。

其他 port

不是跑在 3000？改一下就好：

# React 預設 port
ngrok http 5173

# Django 預設 port
ngrok http 8000

# PHP 內建伺服器
ngrok http 8080

要點五－進階功能：自訂子網域

免費版的網址問題

免費版每次啟動 ngrok，網址都會變：

• 第一次：https://abc123.ngrok-free.app
• 第二次：https://xyz789.ngrok-free.app

這對於需要固定網址的情境很不方便（例如 Webhook 設定）。

付費版自訂子網域

升級付費版後，可以固定子網域：

ngrok http 3000 --domain=myproject.ngrok.io

這樣每次都是同一個網址。

使用自己的網域

更高階的方案可以綁定自己的網域：

ngrok http 3000 --domain=dev.yourdomain.com

需要在 DNS 設定 CNAME 指向 ngrok。

指定區域

預設會自動選擇最近的區域，也可以手動指定：

# 亞太區域
ngrok http 3000 --region=ap

# 可選區域：us, eu, ap, au, sa, jp, in

要點六－Ngrok 免費版限制

免費版有一些限制，了解後才能評估是否需要升級：

限制一覽

免費版瀏覽器提示

免費版網址第一次打開會看到一個警告頁面：

"You are about to visit a site hosted by ngrok..."

需要點擊「Visit Site」才能繼續。這可能讓客戶感到困惑。

繞過警告頁面

有兩種方式：

1. 加上 Header（程式端處理）

如果是 API 請求，加上這個 Header：

ngrok-skip-browser-warning: true

2. 升級付費版

付費版不會有這個警告頁面。

💡 免費版不夠用但不想付費？ 可以考慮使用 Cloudflare Tunnel，完全免費且沒有這些限制。

要點七－實戰：Webhook 測試搭配 Ngrok

Webhook 測試是 ngrok 最常見的使用場景。

Line Bot Webhook 設定

1. 啟動你的 Bot 伺服器

# 假設你的 Line Bot 跑在 5000 port
python app.py

2. 啟動 ngrok

ngrok http 5000

得到網址：https://abc123.ngrok-free.app

3. 設定 Line Webhook

到 Line Developer Console：

Webhook URL: https://abc123.ngrok-free.app/webhook

4. 監控請求

打開 http://127.0.0.1:4040，可以看到 Line 送來的每一個訊息。

Stripe Webhook 設定

Stripe 的金流通知也需要 Webhook：

ngrok http 3000

在 Stripe Dashboard 設定：

Endpoint URL: https://abc123.ngrok-free.app/stripe/webhook
Events: payment_intent.succeeded, payment_intent.failed

GitHub Webhook 設定

讓 GitHub 在 push 時通知你的程式：

Payload URL: https://abc123.ngrok-free.app/github/webhook
Content type: application/json

Debug 小技巧

在 ngrok 的 Web 介面（4040 port）可以：

• 看到完整請求內容：包含 Headers、Body
• Replay 請求：重新發送之前的請求，方便 debug
• 檢視回應：看你的程式回傳了什麼

要點八－常見問題排解

問題一：ERR_NGROK_108

ERR_NGROK_108: Your account may not run more than 1 tunnels

原因：免費版只能同時開一個隧道

解決：

# 先關閉其他 ngrok 程序
killall ngrok

# 或直接用一個隧道
ngrok http 3000

問題二：Tunnel not found

Tunnel abc123.ngrok-free.app not found

原因：ngrok 已經關閉，網址失效

解決：重新執行 ngrok http 3000 取得新網址

問題三：Connection refused

failed to connect to localhost:3000

原因：你的程式沒在跑

解決：

1. 確認程式有啟動
2. 確認 port 正確
3. 試試 curl localhost:3000 看看

問題四：Too many connections

ERR_NGROK_108: Your account may not run more than X connections

原因：超過免費版連線限制

解決：

• 等待限制重置（每分鐘 20 個請求）
• 升級付費版

問題五：警告頁面影響 API

Webhook 請求被警告頁面擋住？

解決：請求時加上 Header

curl -H "ngrok-skip-browser-warning: true" https://abc123.ngrok-free.app

💡 Ngrok 問題排解不了？ 可以聯繫我們讓工程師幫你處理。

要點九－Ngrok 替代方案比較

Ngrok 不是唯一選擇，這裡比較幾個替代方案：

比較表

什麼時候用 Ngrok？

• 需要最快速地產生公開網址
• 不想花時間設定
• 臨時 Demo 或測試

什麼時候用其他方案？

• 需要免費自訂網域 → Cloudflare Tunnel
• 不想註冊任何帳號 → Localtunnel
• 只用 VS Code → VS Code Port Forwarding

程式只能在本機跑？

讓我們幫你從 localhost 走向全世界，把專案部署到雲端。

幫我上線

常見問題 FAQ

Q1：Ngrok 免費嗎？

是的，Ngrok 有免費版。免費版限制包括：每分鐘 20 個請求、1GB 月流量、隨機網址（每次重啟會變）。對於開發測試來說通常夠用。

Q2：Ngrok 產生的網址會變嗎？

免費版每次執行 ngrok http 都會產生新的隨機網址。如果需要固定網址，需要升級付費版使用自訂子網域功能。

Q3：Ngrok 安全嗎？

Ngrok 使用加密隧道傳輸資料，而且可以設定密碼保護：

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

但要注意，任何知道網址的人都能連線，所以不要用於敏感資料。

Q4：Ngrok 連不上怎麼辦？

常見原因：
1. 本機程式沒啟動 → 先確認 localhost 可連
2. Port 錯誤 → 確認程式實際跑的 port
3. 防火牆阻擋 → 檢查防火牆設定
4. 超過連線限制 → 等待重置或升級

延伸閱讀

• 如何讓 Localhost 上線？5 種方法總覽
• Cloudflare Tunnel 教學｜免費讓本機程式上線
• Localhost 是什麼？127.0.0.1 完整指南
• Localhost 拒絕連線？5 種原因與解決方法

程式只能在本機跑？

讓我們幫你從 localhost 走向全世界，把專案部署到雲端。

幫我上線

圖片描述

插圖 1：Ngrok 概念示意圖
- 檔名 slug: ngrok-concept-diagram
- 圖片類型: 概念示意圖
- 主要視覺元素:
- 左側：開發者電腦顯示 localhost:3000
- 中央：Ngrok logo 和發光隧道效果
- 右側：多個使用者裝置（手機、平板、電腦）
- 文字標註: "localhost:3000"、"ngrok tunnel"、"Public URL"
- 色調與風格: Ngrok 品牌紫色調，現代科技感
- 構圖建議: 水平流程圖，清楚顯示本機→隧道→公開的流程

插圖 2：Ngrok 儀表板畫面
- 檔名 slug: ngrok-dashboard-authtoken
- 圖片類型: 介面截圖示意
- 主要視覺元素:
- 模擬 Ngrok 儀表板介面
- 重點標示 Authtoken 區塊
- 左側導覽列
- 文字標註: "Your Authtoken"、"Copy"按鈕、部分遮蔽的 token
- 色調與風格: Ngrok 深色主題介面風格
- 構圖建議: 完整儀表板畫面，用紅框或箭頭標示重點區域

插圖 3：穿透工具比較圖
- 檔名 slug: tunnel-tools-comparison
- 圖片類型: 比較資訊圖
- 主要視覺元素:
- 四個工具卡片：Ngrok、Cloudflare、Localtunnel、VS Code
- 每個卡片含 logo 和主要特點
- 底部選擇建議區塊
- 文字標註: 各工具名稱、特點標籤、推薦情境
- 色調與風格: 資訊圖表風格，使用顏色區分優缺點
- 構圖建議: 2x2 卡片式排版，底部附選擇指南

插圖 4：Webhook 測試流程圖
- 檔名 slug: ngrok-webhook-flow
- 圖片類型: 流程示意圖
- 主要視覺元素:
- Line/Stripe/GitHub 圖示
- 箭頭指向 Ngrok URL
- Ngrok 轉發到 localhost
- 開發者電腦接收請求
- 文字標註: "Webhook Request"、"ngrok-free.app"、"localhost:5000"
- 色調與風格: 技術流程圖風格，清晰的箭頭和標註
- 構圖建議: 水平流程，從左到右顯示請求路徑