解決 PWA 安裝按鈕在 iOS 與 Android 上顯示異常的終極指南

漸進式網頁應用程式 (PWA) 最大的賣點之一，就是能讓使用者一鍵「安裝為應用程式」，並在主畫面產生像原生 App 一樣的圖示。然而，只要你實作過自訂的「安裝按鈕」，就一定會遇過以下這兩個讓人崩潰的靈異現象：

1. iPhone (iOS) 有時候會同時跑出「兩個」安裝按鈕或提示。
2. Android (Chrome 等) 或是電腦版的瀏覽器，安裝按鈕有時候就是死活不顯示出來。

這篇文章將帶你剖析這兩個現象的背後成因，並提供一個完美解決跨平台顯示異常的終極寫法。

---

為什麼按鈕會消失或鬧雙胞？

這一切的罪魁禍首，都要歸咎於各家瀏覽器對於 beforeinstallprompt 事件的實作差異與神經質。

1. Android 的「神經質」機制

在 Android 或 PC 版 Chrome 開發 PWA 時，官方標準教法是去監聽 beforeinstallprompt 事件。當系統判定你的 PWA 符合標準，它就會拋出這個事件，這時你才能把自訂的按鈕顯示出來。

但問題就在於，Chrome 的觸發條件非常嚴苛且不可控：

• 如果當時網路稍微慢了一點導致 Service Worker 還沒完全 Ready…
• 如果使用者曾經在原生的安裝提示上點過「取消」或關閉…
• 甚至如果 Chrome 根據某個神奇的啟發式演算法認為現在「不適合」…

它就絕對不發送這個事件！一旦沒有事件，你的框架狀態（例如 const [installPrompt, setInstallPrompt] = useState(null)）就永遠是 null，按鈕也就永遠不會轉譯出來，即使這台裝置完全有能力將其加到主畫面。這讓使用者覺得「咦？為什麼別人的手機有安裝按鈕，我的沒有？」。

2. iOS Safari 的「傲嬌與意外」

Apple 對於 PWA 一向抱持著警惕的態度。在 iOS Safari 身上，至今都沒有實作官方標準的 beforeinstallprompt API。在 iOS 上，使用者唯一的安裝途徑，是點開 Safari 底部的「分享」按鈕，自己去大海撈針找出「加入主畫面」。

為了照顧 iOS 使用者，開發者通常會寫另一套邏輯：「如果判斷 User Agent 是 iOS，就渲染一個專屬的教學按鈕」。

然而災難就此發生。我們原本的寫法大概像這樣：

{/* 邏輯 A：如果是 Android/PC 且有 prompt 事件，顯示一般按鈕 */}
{!isInstalled && installPrompt && (
   <button onClick={handleInstall}>安裝 App</button>
)}

{/* 邏輯 B：如果是 iOS，顯示 iOS 專屬提示按鈕 */}
{isIOS && !isInstalled && (
   <button onClick={showiOSTutorial}>iOS 安裝指引</button>
)}

這樣的寫法乍看完美，但在某些非 Safari 的 iOS 瀏覽器（例如 iOS 上的 Chrome），或是未來的 Safari 更新中，瀏覽器可能會丟出類似 beforeinstallprompt 的行為。結果就是：系統同時滿足了「是 iOS」且「存在 installPrompt」，兩個按鈕就牽著手一起出現在畫面上了。

---

終極解決方案：單一按鈕與優雅降級

為了解決 iOS 鬧雙胞，以及 Android 動不動就把按鈕沒收的問題，我們徹底翻轉了思維：不要等系統恩賜安裝事件才顯示，而是「只要你沒安裝，我就讓你看到這顆按鈕」！

我們將安裝按鈕整併為單一個組件 (Unified Button)，並在使用者點擊時才進行「智慧分流機制」。

實作程式碼範例 (React / TypeScript)

{/* 單一 PWA 安裝按鈕 */}
{isMounted && !isInstalled && (
    <button
        onClick={() => {
            if (isIOS) {
                // 情境 1：iOS 設備
                alert('iOS 安裝方法：\n1. 點擊 Safari 底部的「分享」按鈕\n2. 選擇「加入主畫面」即可完成安裝。');
            } else if (installPrompt) {
                // 情境 2：正常觸發了標準安裝事件
                installPrompt.prompt();
            } else {
                // 情境 3：Android/PC 但系統拒絕發送安裝事件 (Fallback)
                alert('目前瀏覽器環境尚未觸發自動安裝，或不支援快速安裝。\n您可以透過瀏覽器右上角選單選擇「加到主畫面」或是「安裝應用程式」來手動完成。');
            }
        }}
        className="..."
    >
        <Smartphone size={16} /> 
        <span>{isIOS ? 'iOS 安裝指引' : '安裝為應用程式'}</span>
    </button>
)}

為什麼這樣寫最好？

1. 徹底根除雙胞胎 BUG： 我們只寫了一個 <button>，在渲染層面就物理隔絕了出現兩顆按鈕的可能性。
2. 拯救 Android 幽靈按鈕： 用戶在畫面上一定會看到那顆安裝按鈕。如果他很倒楣沒觸發原生安裝事件，點下去時至少會出現 Fallback 彈跳視窗（情境 3），溫馨提醒他從選單手動「加到主畫面」。這遠比按鈕憑空消失、讓使用者不知所措來得友善幾百倍。
3. 體驗一致且順暢： 手機端的條件判斷被整合在點擊事件裡，代碼更乾淨好維護，UI 不會因為等待 Service Worker 而突然跳動。

結語

PWA 在不同瀏覽器平台充滿了碎片的實作細節，開發者往往要在這之中權衡，找出體驗最好的路徑。

透過將「顯示按鈕的決定權」與「觸發安裝的行為」拆分，我們成功規避了瀏覽器底層 API 不可控的風險。下次當你在撰寫 PWA 安裝邏輯時，不妨試試這種「單一按鈕加上優雅降級」的策略，省下大把的除錯時間吧！