【Day 29】用 ngrok 進行實機測試：連線除錯與手機版面微調

2026 iThome 鐵人賽

DAY 29

Modern Web

微光採集瓶：用 Vue 3 打造每日美好記錄網頁系列第 29 篇

18th鐵人賽

y0yi9ue

2026-10-13 23:51:29

45 瀏覽

分享至

在電腦瀏覽器使用開發者工具模擬手機排版雖然方便，但為了確認實際的觸控體驗與介面比例，今天將《微光採集瓶》放到 iPhone 上進行實機測試。過程中遇到了一些本地連線限制與設定問題，因此改用 ngrok 建立外部測試網址，並針對手機螢幕調整響應式版面（RWD），同時微調深色背景下的文字可讀性。

一、手機實機連線測試與排除問題

共用網路限制與切換 ngrok

一開始嘗試透過區網 IP 讓手機連入電腦上的開發伺服器，但連線始終逾時，無法順利開啟網頁。當時推測可能與 Wi-Fi 的 AP 隔離設定、電腦防火牆或防毒軟體的連線限制有關，但沒有進一步確認確切原因。

為了避免花費太多時間排查底層網路設定，我改用 ngrok 將本地開發伺服器公開為外部 HTTPS 網址，讓 iPhone 可以透過 Safari 開啟專案。

1. 設定 Vite 開發伺服器

打開專案根目錄中的 vite.config.js，在 defineConfig 的 server 設定中加入相關參數：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [vue()],
  server: {
    host: '0.0.0.0',
    port: 5173,
    allowedHosts: true
  }
})

其中，host: '0.0.0.0' 讓 Vite 監聽所有網路介面，port: 5173 指定開發伺服器使用的埠號，而 allowedHosts: true 則允許所有 Host 網域通過檢查。

需要注意的是，allowedHosts: true 會降低 Host 網域檢查的保護，因此只適合在了解風險的短期測試情境下使用。較安全的方式是只允許實際使用的 ngrok 網域，並在測試結束後停止公開的開發伺服器。

2. 設定 ngrok Token

前往 ngrok 官網取得 Authtoken，並在終端機執行以下指令：npx ngrok config add-authtoken 你的Token

這個步驟主要是完成 ngrok 的帳戶驗證設定，首次使用時才需要執行。

3. 啟動 Vite 與 ngrok

啟動 Vite 開發伺服器：npx vite --host 0.0.0.0
接著啟動 ngrok，將本地的 5173 埠轉發至外部網址：npx ngrok http 127.0.0.1:5173

這裡假設 Vite 確實運作於 5173 埠。如果該埠已被其他程序佔用，Vite 可能改用其他埠號，此時就必須讓 ngrok 指向實際使用的埠號。

ngrok 啟動後，終端機會顯示 Forwarding 網址。將產生的 HTTPS 網址複製到 iPhone Safari，即可測試手機是否能正常開啟網頁。

這邊會看到 ngrok 終端機狀態畫面（如下圖）：

在手機瀏覽器上輸入上圖 Forwarding 那串網址就可以看到採集瓶網頁啦~

二、實作時遇到的問題

在使用 ngrok 將本地開發伺服器公開至外部網路的過程中，我遇到了幾個環境設定與連線問題，經過逐步排查後，才順利讓手機瀏覽器正常存取網頁。

1. 防毒軟體攔截
初次執行 ngrok 時，電腦安裝的 Avast 防毒軟體跳出警示，將 ngrok.exe 標記為 Other:PUP-gen [PUP]，導致程式無法正常執行。

原因： PUP 是指潛在不受歡迎的程式。部分防毒軟體可能會對特定網路工具發出警示，但僅憑偵測名稱，無法直接判定此次警示是否為誤判。
處理方式： 確認程式來源後，我將 ngrok 加入 Avast 的例外名單，讓程式能夠繼續執行。這次經驗也提醒我，遇到防毒警示時，應先確認檔案來源與安全性，再決定是否允許執行，而不是直接關閉所有防護。

2. 連接埠設定錯誤（ERR_NGROK_8012）
成功啟動 ngrok 後，使用手機開啟轉發網址時，畫面出現 ERR_NGROK_8012 錯誤，表示 ngrok 無法正常連接到本地端的目標服務。

原因： Vite 預設使用 5173 埠提供開發伺服器服務。當該埠已被其他程序佔用時，Vite 可能自動改用 5174 等其他可用埠號。如果 ngrok 指向的埠號與 Vite 實際使用的埠號不同，就可能造成連線失敗。此外，本機位址設定也可能影響連線結果。
處理方式： 先確認 Vite 終端機顯示的實際網址與埠號，再讓 ngrok 指向相同的服務位置。例如，當 Vite 確實運作於 5173 埠時，可以使用以下指令：
```
npx ngrok http 127.0.0.1:5173
```
透過確認兩端的連線設定一致，排除 ngrok 無法連接本地伺服器的問題。

3. Vite 安全機制阻擋（403 Forbidden）
當 ngrok 成功連接本地伺服器後，手機 Safari 載入網頁時仍出現 403 Forbidden 錯誤，並提示需要將 ngrok 網域加入 server.allowedHosts 設定。

原因： Vite 開發伺服器具有 Host 網域檢查機制，用來限制可接受的請求網域，以降低 DNS 重新綁定（DNS Rebinding）等攻擊風險。由於 ngrok 使用的外部網域未列入允許清單，因此請求遭到阻擋。
處理方式： 我在 vite.config.js 的 server 設定中加入 allowedHosts: true，允許外部轉發網址的 Host 請求通過檢查。修改設定後，重新啟動 Vite，再透過 ngrok 網址測試，最後成功在手機上開啟網頁。

不過，這種設定會允許所有 Host 網域，存在一定的安全風險。若要採用較安全的方式，可以將實際使用的 ngrok 網域加入允許清單，而不是開放所有網域。

透過這次排除問題的過程，我不僅熟悉了 ngrok 的基本使用方式，也更了解本地伺服器的連接埠設定、外部網路轉發，以及開發環境安全機制之間的關係。

三、手機版版面調整（RWD）

當網頁成功在 iPhone Safari 開啟後，我進一步觀察手機實際顯示的版面，發現電腦瀏覽器的手機模擬畫面與實機呈現仍有差異，因此針對手機直向螢幕調整了響應式版面。

這次調整主要著重在整體垂直配置，重新調整標題、搜尋欄、採集瓶、色盤、提示文字與採集按鈕等元素的位置與間距，讓主要操作區域在手機畫面中呈現得更協調。

此外，版面也運用了以下 CSS 設定：

100dvh： 配合手機瀏覽器動態變化的可視高度，減少網址列顯示或收合時造成的高度差異。
env(safe-area-inset-top) 與 env(safe-area-inset-bottom)： 配合裝置安全區域，避免內容過度貼近瀏海或底部手勢操作區。
彈性排版與寬度限制： 利用 Flexbox 及寬度限制，讓主要內容能依照可用空間配置，並減少輸入框、彈窗等元素超出手機畫面邊界的情況。

四、調整採集頁面的文字對比度

完成版面調整後，我發現部分文字在深色背景下仍然偏暗，尤其是輔助文字、輸入框提示，以及停用狀態的按鈕，辨識度不太理想。

因此，我提高了幾個區塊的文字明度與不透明度，讓文字在深色背景下更容易閱讀：

頂部導覽按鈕文字 .btn-nav-action： 調整為 rgba(255, 255, 255, 0.85)。
篩選區輔助文字 .filter-bar： 調整為 rgba(255, 255, 255, 0.8)。
重設篩選按鈕 .btn-reset-filter： 調整為 rgba(255, 255, 255, 0.8)。
已選心情顏色的標籤 .selected-label： 調整為 #cbd5e1。
標籤自訂編輯按鈕 .btn-edit-inline： 調整為 rgba(255, 255, 255, 0.8)。
心情輸入框提示文字 .note-input::placeholder： 調整為 rgba(255, 255, 255, 0.85)。
停用狀態的採集按鈕 .btn-collect.btn-disabled： 調整文字顏色為 rgba(255, 255, 255, 0.85)，並同步調整邊框顏色與文字陰影。