Ngrok 配置：實現 Uniapp 前后端項目內網穿透

文章目錄

- 一、下載并安裝 ngrok
- 二、配置 ngrok Authtoken
- 三、啟動本地 uniapp 項目
- 四、使用 ngrok 暴露本地服務
- 五、通過公網 URL 訪問項目
- 六、后端API項目的穿透問題排查 (uni-app + 后端 API 示例)
- - 交互流程圖示
- 七、ngrok Web 界面 (本地監控)
- 八、停止 ngrok
- 總結

ngrok 是一款強大的工具，可以讓你將本地運行的 web 服務暴露到公網上，非常適合用于本地開發調試、向客戶演示項目或測試 webhook 等場景。

一、下載并安裝 ngrok

訪問 ngrok 官網下載頁面：https://ngrok.com/download
下載 Windows 版本的 ngrok
解壓 ngrok：將下載的 ngrok.zip 文件解壓到一個你方便訪問的目錄，解壓后你會得到一個 ngrok.exe 文件。

二、配置 ngrok Authtoken

為了使用 ngrok 的更多功能（例如自定義子域名等，盡管某些高級功能可能需要付費），建議連接到你的 ngrok 賬戶。

登錄 ngrok 官網：訪問 https://dashboard.ngrok.com/。
獲取 Authtoken：在儀表盤的 “Your Authtoken” 或 “Setup & Installation” 部分，你會找到你的 Authtoken。
配置 Authtoken：
- 運行ngrok.exe
- 運行以下命令（將 YOUR_AUTHTOKEN 替換為你自己的 Authtoken）：
```
.\ngrok.exe config add-authtoken YOUR_AUTHTOKEN
```
- 成功后，ngrok 會將 Authtoken 保存到其默認的配置文件中 (通常在 C:\Users\YourUserName\.ngrok2\ngrok.yml)。
可選：將 ngrok添加到系統環境變量 (PATH)
為了在任何目錄下都能直接運行 ngrok 命令，而不是每次都 cd 到其所在目錄，你可以將其路徑添加到系統環境變量 PATH 中。
1. 在 Windows 搜索中搜索"環境變量"，選擇"編輯系統環境變量"。
2. 在"系統屬性"窗口中，點擊"系統變量(N)…"按鈕。
3. 在"系統變量"區域找到名為 Path 的變量，選中它，然后點擊"編輯(E)…"。
4. 點擊"新建(N)"，然后輸入 ngrok.exe 所在的目錄路徑 (例如 D:\tools\ngrok)。
5. 一路點擊"確定"保存更改。之后新打開的命令行窗口即可直接使用 ngrok 命令。
- (截圖機會：展示添加環境變量的步驟)

三、啟動本地 uniapp 項目

接下來，我們需要一個在本地運行的 web 服務。這里以 uniapp H5 項目為例。

進入 uniapp 項目目錄：使用命令行工具 (CMD, PowerShell, Git Bash 等) cd 到你的 uniapp 項目根目錄。
啟動開發服務器：運行 uniapp 的 H5 開發命令。
- 如果使用 npm:
```
npm run dev:h5
```
- 如果使用 yarn:
```
yarn dev:h5
```
記錄本地地址和端口：項目啟動后，命令行通常會顯示 H5 預覽地址，例如 http://localhost:8080 或 http://127.0.0.1:3000。記下這個端口號，我們稍后會用到。

四、使用 ngrok 暴露本地服務

現在，我們將使用 ngrok 將本地運行的 uniapp 項目暴露到公網上。

新建域并啟動
啟動隧道，運行 ngrok 命令：
獲取公網URL：ngrok 啟動后，會在命令行界面顯示一些信息，最重要的就是 Forwarding 中的https:// 開頭的 URL，這就是你的公網訪問地址。

五、通過公網 URL 訪問項目

現在，你或你的朋友、同事、客戶等，可以在任何有網絡連接的設備上，通過瀏覽器打開上一步中 ngrok 生成的 Forwarding URL (通常建議使用 https 的那個)，就能訪問到你本地運行的 uniapp 項目了，到這里對于未配置后端的項目來說已經穿透成功了。

六、后端API項目的穿透問題排查 (uni-app + 后端 API 示例)

當你使用 uni-app 開發前端，并需要連接到一個獨立的后端 API 服務（例如 Java Spring Boot, Node.js 等）時，通過 ngrok 暴露前端后，可能會遇到 API 請求失敗的問題。本地直接訪問 localhost:UNIAPP_DEV_PORT (uni-app H5 運行的端口) 時一切正常，但通過 ngrok 生成的公網 URL 訪問時，后端接口調用不通。

常見現象:

瀏覽器開發者工具的網絡(Network)標簽頁顯示 API 請求失敗，錯誤可能是 net::ERR_CONNECTION_REFUSED。
或者，如果后端沒有正確配置CORS，可能會看到跨域相關的錯誤信息。

主要原因及解決方案 (針對絕對 BASE_URL 配置):

假設你的 uni-app 項目中，API 請求的基礎路徑 BASE_URL 是一個寫死的本地地址，例如：

// 在 api/index.js 或類似文件中
const BASE_URL = 'http://localhost:8080/api'; // 你的后端API基礎路徑

問題核心：localhost 指向的是客戶端
- 當你的同學或同事通過 ngrok 的公網 URL (例如 https://xxxx.ngrok.io) 訪問你的 uni-app 應用時，應用內的 JavaScript 代碼（包括 API 請求）是在他們的瀏覽器中執行的。
- 因此，代碼中對 http://localhost:8080/api 的請求，實際上是嘗試連接他們自己電腦上的 localhost:8080 服務。如果他們的電腦上沒有運行對應的后端服務，這個請求自然會失敗。
解決方案：為后端 API 服務也啟動 ngrok
- 步驟1: 確保后端服務正常運行：首先，確保你的 Spring Boot (或其他) 后端服務正在你的開發機器上的 localhost:8080 (或你配置的任何端口) 成功運行。
- 步驟2: 為后端啟動單獨的 ngrok 實例：打開一個新的命令行窗口，cd 到 ngrok.exe 所在的目錄（或者如果已配置環境變量，直接運行），然后為你的后端服務端口啟動 ngrok。如果后端運行在 8080 端口：
```
ngrok http 8080
```
- ngrok 會為你的后端服務生成另一個公網 URL，例如 https://yyyy.ngrok.io。
- 步驟3: (臨時) 修改前端的 BASE_URL：回到你的 uni-app 項目代碼，在 api/index.js (或類似文件) 中，將 BASE_URL 臨時修改為 ngrok 為后端生成的公網地址：
```
// 臨時修改，用于公網演示
const BASE_URL = 'https://yyyy.ngrok.io/api'; // 注意：這里是后端 ngrok 的地址
```
- 步驟4: 重新編譯 uni-app 項目 (如果需要)，并確保訪問前端 ngrok 地址的用戶獲取到的是更新了 BASE_URL 的前端代碼。
- 現在，通過前端 ngrok URL 訪問應用時，API 請求就會正確地指向你通過 ngrok 暴露的公網后端服務了。
后端 CORS 配置:
- 非常重要！你的后端服務（如 Spring Boot）必須配置 CORS (跨源資源共享) 策略，以允許來自你的前端 ngrok URL (例如 https://xxxx.ngrok.io) 和后端 ngrok URL (https://yyyy.ngrok.io，如果請求來源是它) 的請求。否則，即使地址正確，瀏覽器也可能因為安全策略阻止請求。
- 在 Spring Boot 中，通常使用 @CrossOrigin注解或全局 CORS 配置。

替代方案 (推薦用于開發和更便捷的共享): 使用代理

雖然上述方法可行，但每次共享都需要修改 BASE_URL 并可能需要重新部署前端，比較繁瑣。更推薦的做法是在 uni-app 開發服務器層面設置代理，將特定的 API 請求轉發到本地后端。

前端 BASE_URL 使用相對路徑:

// api/index.js
const BASE_URL = '/api_proxy'; // 一個自定義的代理前綴
// ... 確保請求方法中 url 拼接正確，例如： request({ url: options.url ...}) 變成 request({ url: BASE_URL + options.url ...})
// 如果 options.url 已經是 /resource/action, 那么拼接后就是 /api_proxy/resource/action

配置 vue.config.js (uni-app H5 項目根目錄):
如果項目根目錄下沒有 vue.config.js 文件，新建一個。

// vue.config.js
module.exports = {devServer: {proxy: {'/api_proxy': { // 匹配前端以 /api_proxy 開頭的請求target: 'http://localhost:8080', // 你的本地后端服務地址changeOrigin: true, // 必須，用于支持跨域pathRewrite: {'^/api_proxy': '/api' // 將請求路徑中的 /api_proxy 替換為 /api (如果后端是以 /api 開頭的)// 例如 /api_proxy/users/list -> http://localhost:8080/api/users/list}}}}
};

修改 vue.config.js 后，需要重啟 uni-app 開發服務器 (npm run dev:h5)。

ngrok 暴露 uni-app 開發服務器: 這種情況下，你只需要像之前一樣，用 ngrok 暴露 uni-app H5 運行的端口 (例如 ngrok http UNIAPP_DEV_PORT)。uni-app 的開發服務器會自動將 /api_proxy 的請求轉發到你的本地后端。這樣，前端代碼中的 BASE_URL 無需改動，分享也更方便。

交互流程圖示

下面通過圖示來進一步說明兩種主要配置下的工作流程。

(一) 絕對 BASE_URL + 前后端分別使用 Ngrok (推薦用于需要固定公網后端地址的場景)

這種配置下，前端代碼中的 BASE_URL 直接指向后端 ngrok 的公網地址。

解釋:

用戶 (自己或他人)：通過 https://frontend.ngrok.io (前端的公網 ngrok 地址) 訪問應用。
前端應用加載后，其 API 請求直接指向 https://backend.ngrok.io/api (后端的公網 ngrok 地址)。
這種方式清晰地分離了前端和后端的公網訪問點。

(二) 相對 BASE_URL + Uni-app devServer.proxy + 前端使用 Ngrok (推薦用于開發調試和便捷分享)

這種配置下，前端代碼中的 BASE_URL 是一個相對路徑 (如 /api_proxy)，由 Uni-app 開發服務器代理到本地后端。

解釋:

用戶 (自己或他人)：通過 https://frontend.ngrok.io 訪問應用。
前端應用加載后，其 API 請求 (例如 /api_proxy/users) 被發送到 https://frontend.ngrok.io/api_proxy/users。
這個請求到達開發者的 Uni-app 開發服務器后，其內部的代理設置會將此請求轉發給實際運行在 localhost:portB 的后端服務。
這種方式下，只需要為前端啟動一個 ngrok 實例，配置相對簡單。

通用排查提示:

確認后端服務已啟動并監聽正確端口：這是最基本的一步。
直接測試后端接口：使用 Postman、curl 或直接在瀏覽器中（如果接口支持GET）訪問你的本地后端接口 (例如 http://localhost:8080/api/some-endpoint)，確保它能正常工作并返回數據。如果本地都訪問不通，ngrok 自然也無法使其工作。

通過以上步驟，應該能解決大部分 ngrok 穿透后 API 請求失敗的問題。