剪貼板復制失敗時，你的"成功提示"在撒謊

你剛點完"復制密鑰"，看到綠色對勾，自信地切到終端粘貼——結果粘進來的是昨天復制的快遞單號。這不是用戶手滑，是代碼在假裝成功。

我在給管理后臺加"復制令牌"按鈕時撞上了這個坑。剪貼板接口（Clipboard API）返回了 undefined，控制臺卻干干凈凈。用戶會看見勾選動畫，粘貼時卻一片空白，甚至更糟：粘上的是剪貼板里殘留的任意內容。在那個場景下，"任意內容"可能是任何東西。

這讓我想起 Hacker News 上那篇 977 贊的熱帖《Copy Fail》。作者扒了一個真實現象：navigator.clipboard.writeText() 會在特定場景下靜默失敗。沒有異常，沒有拒絕回調，什么都沒有。用戶點擊，圖標變勾，剪貼板原封不動。

帖子的評論區炸了，因為誰都見過這毛病，但沒人說得清根因。答案從"Chromium 的權限模型"到"iframe 的鍋"到"文檔沒聚焦"，個個都對，個個不全。

我的判斷：問題不是剪貼板會失敗，而是我們寫的交互假設它永遠不會失敗。這個假設在復制密碼、API 密鑰、私鑰時尤其危險。

我在自己的環境里復現了這個問題。這是發現。

三個場景，三種死法

我拆了一個生產環境跑著的組件——管理后臺里復制 API 密鑰的按鈕。技術棧：Next.js 15、TypeScript、Railway 托管、反向代理后面。

第一個意外：bug 不是在哪都復現。我搭了三個場景才摸清規律。

場景一，iframe 埋雷。組件如果套在 iframe 里，且沒寫 allow="clipboard-write" 屬性，writeText() 的 Promise 會 resolve，但什么都不寫。我的 setCopied(true) 照跑，用戶看見綠勾。

場景二，權限查詢的幻覺。我以為用 Permissions API 先查 clipboard-write 狀態就能避險。結果在部分瀏覽器里，query() 返回的 state 是"prompt"——不是"granted"也不是"denied"。這時候調用 writeText()，用戶可能根本沒看到權限彈窗，Promise 就已經掛了。

場景三，最陰的。文檔失去焦點時（比如用戶點了按鈕后快速切到別的標簽頁），writeText() 的行為因瀏覽器而異。Chrome 可能靜默失敗，Firefox 可能拋異常，Safari 可能直接忽略調用。

同一行代碼，三種尸體。

為什么錯誤抓不到

Clipboard API 的設計是 Promise 化的，這讓我們誤以為能用 try-catch 兜底。但規范里留了一個后門：如果權限檢查在底層就被攔截，Promise 可以 resolve 為 undefined，而不是 reject。

我的日志證實了這點。在 iframe 場景里，writeText() 返回的 Promise 正常走完，await 之后我拿到的是 undefined，不是拋錯。我的 catch 塊成了擺設。

更麻煩的是，瀏覽器的權限模型和剪貼板 API 是兩套系統。Permissions API 能查到的"clipboard-write"，和 writeText() 實際需要的權限，在邊緣場景下并不完全對齊。查出來"可以寫"，不代表真能寫。

我試了一種防御寫法：先讀剪貼板，再寫，再讀驗證。結果撞上了另一個限制——readText() 需要"clipboard-read"權限，比 write 更嚴格。這套方案在 HTTP 環境下直接爆炸，因為剪貼板 API 要求安全上下文（secure context）。

fallback 不是退路，是主路

我最終保留了兩套方案。第一套走 Clipboard API，但加了顯式的權限預檢和結果驗證。第二套是 document.execCommand('copy')，這個被標記為廢棄的老 API，在 iframe 和舊瀏覽器里反而更穩。

execCommand 的缺陷很明顯：它只能寫選中的文本，所以我需要臨時創建一個 textarea，塞入內容，選中，執行復制，再清理 DOM。代碼丑，但行為可預測。失敗時它會返回 false，而不是假裝成功。

關鍵改動在 UX 層。我不再假設"調用復制 = 復制成功"。無論走哪條路，最后都驗證一次：嘗試讀剪貼板（在允許讀的上下文里），或者至少確保 Promise 返回的不是 undefined。只有驗證通過，才顯示那個綠色對勾。

代價是延遲。驗證多了幾十毫秒，但相比讓用戶把舊密鑰粘貼到生產環境，這買賣劃算。

這件事的實用指向

剪貼板 API 的靜默失敗是個設計債，但短期內不會改。規范允許 Promise resolve 為空，瀏覽器廠商各有各的實現偏差，你等不及他們統一。

能做的是三件事：一，復制敏感內容時，永遠準備 fallback 方案，execCommand 雖然 deprecated，但死得比你的用戶信任慢；二，別信 Promise 的 resolve，顯式檢查結果或者做寫后驗證；三，把"復制成功"的反饋從"我調用了 API"改成"我確認了內容在剪貼板里"。

那個綠色對勾，用戶已經學會無視了。你要給的是他們敢切到終端直接粘貼的信心。