iPhone 上 PDF 預覽白屏：我們剛修好的 Safari 地雷
2026-09-14
用戶回報得很直白：在 iPhone 上點檔案要預覽，沒反應，甚至整頁白掉；電腦上卻一切正常。這篇文章記錄真正壞掉的是什麼，以及我們怎麼把它修到每一支還在使用的 iPhone 都能跑。
症狀與病因
我們的預覽引擎是 pdf.js，所有解析都丟進 Web Worker 執行，頁面才不會卡死。這次崩潰跟我們的程式碼路徑無關：pdfjs-dist 4.x 內部呼叫 Promise.withResolvers，而這個 JavaScript API Safari 直到 17.4 才內建。在 iOS 17.3.1 以下，PDF 一開始解析，worker 就撞上一個不存在的函式，預覽於是安靜地死掉。
為什麼一般的 polyfill 救不了
標準修法是在函式庫載入前補上缺失的函式。但 Web Worker 是獨立的 JavaScript 環境：主頁面和 worker 不共用全域變數，裝在頁面上的 polyfill 永遠到不了真正崩潰的 worker。所以我們自己出了一個 worker 入口檔：先安裝 polyfill，然後才載入真正的 pdf.js worker。
順手修掉的兩個小惡靈
- 幽靈點擊：iOS 有時在全螢幕視窗打開後補發一次延遲的點擊，可能把剛開的預覽瞬間關掉。現在視窗打開後前 400 毫秒會忽略關閉點擊。
- 記憶體壓力：大檔案以前會立刻把每一頁縮圖都畫出來，手機比筆電更容易砍分頁，現在縮圖先畫前 12 頁，其餘用 +N 標籤顯示。
我們怎麼驗證
實機測了 iOS 17.3.1 的 Safari、Chrome 和 Telegram 內建瀏覽器；模擬測了 iPad mini、iPad Pro、Android 平板，以及桌機的 Safari 與 Chrome。我們還做了一個公開的診斷頁，會在任何裝置上把整條 PDF 管線逐層跑一遍並回報結果——將來哪個瀏覽器更新又弄壞什麼，任何用戶花 30 秒就能把報告傳給我們。
對你意味著什麼
「本機處理、絕不上傳」不是行銷話術，而是工程承諾——包括支援那些已經好幾年沒更新系統的手機這種不性感的工作。如果你在任何裝置上遇到空白預覽，開我們的診斷頁跑一次，把結果告訴我們。