跳至主要內容
FrAIFlow

問題解決指南 / 瀏覽器與裝置

複製按鈕在 localhost 有效,上線後卻失敗?

複製按鈕在 localhost 能用,部署到網站後卻失敗。請先分清楚是 Clipboard API 根本不存在,還是寫入剪貼簿的請求被拒絕,兩種情況需要不同的修正方式。

找出失敗的邊界
依保留範例製作的說明圖,並非應用程式截圖。

不降低瀏覽器安全性,也能取出文字

如果只是要複製結果,請在可見文字中點一下、選取內容,再使用作業系統的複製指令。手機上可長按文字叫出選取控制點。如果結果被藏在故障的複製按鈕後面,這是網站管理者應修正的易用性問題。不要為了複製短文字,就安裝擴充功能或關閉安全限制。

網站管理者應在實際部署的頁面重現問題。確認網址以 HTTPS 開頭、頁面目前取得焦點,並檢查是否嵌入其他網站。localhost 上正常的按鈕有助於開發,但不能證明部署後的來源擁有相同權限。

檢查上線頁面,不要只看 localhost

2018 年一則公開案例確認,改用 HTTPS 後,原本無法取得的 clipboard 物件恢復可用。本機回送位址的 HTTP 可能被視為可信,因此 localhost 容易掩蓋這個問題;這個例外不代表一般 HTTP 網站也屬於安全環境。

console.table({
  secure: window.isSecureContext,
  exposed: Boolean(navigator.clipboard),
  active: navigator.userActivation?.isActive
});

保留的隔離 Chromium 測試比較了本機回送 HTTP 與對應到回送位址的測試主機名稱,只測量 API 是否可用。沒有讀寫剪貼簿,也沒有授予權限。部署頁面若不安全,應修正 HTTPS 提供方式,而不是要求訪客停用安全控制。

讓操作與真實點擊保持連結
依保留範例製作的說明圖,並非應用程式截圖。

直接在點擊事件中啟動剪貼簿寫入

HTTPS 本身不保證有寫入權限。一則 WebKit 案例顯示,Safari 的點擊處理函式在等待 fetch 後寫入失敗;修正範例改在點擊期間啟動寫入,並以 Promise 提供 ClipboardItem 資料。這不能證明所有瀏覽器中的非同步操作都會失敗。

這個最小範例保持文字可見,在真實點擊時直接啟動剪貼簿寫入,失敗則顯示手動複製說明。請將它放在允許的安全來源所提供的測試頁。它不要求讀取剪貼簿,也不會把文字傳到其他地方。將範例 textarea 的值換成應用程式已準備完成的結果即可。

<textarea id="copy-source" readonly aria-label="Text to copy">Your finished result</textarea>
<button id="copy-button" type="button">Copy result</button>
<p id="copy-status" role="status"></p>
<script>
const source = document.getElementById("copy-source");
const status = document.getElementById("copy-status");
document.getElementById("copy-button").addEventListener("click", async () => {
  try {
    if (!window.isSecureContext || !navigator.clipboard) {
      throw new Error("Clipboard unavailable");
    }
    await navigator.clipboard.writeText(source.value);
    status.textContent = "Copied. Paste it where you need it.";
  } catch {
    source.focus();
    source.select();
    status.textContent = "Automatic copy failed. Use your device's Copy command on the selected text.";
  }
});
</script>

這是實作指引,不代表新的跨瀏覽器測試。若結果需要網路請求,應在啟用複製按鈕前完成請求。不要因為點擊處理函式執行過,就告訴使用者複製成功;這個範例是在寫入 Promise 成功完成後才顯示成功。

確認複製結果,並保留手動備用方式

使用含換行與帶重音字元的簡短非敏感範例。點擊複製後,貼到純文字編輯器,比對完整值,也要測試手動複製。如果只有嵌入框架中的自動複製失敗,請比較頂層頁面與嵌入版本,並和網站管理者確認嵌入權限政策。不同瀏覽器引擎的權限對話框與設定,不能假設完全相同。

請正確理解下方的來源測試:它證明的是 API 是否可取得,不是這個按鈕能否在每一種瀏覽器寫入。實務目標是提供兩條可用路徑:允許時成功複製,不允許時仍有可見、可選取的結果。

請保持文字可見且可選取。嵌入頁面可能受到父頁面的 Permissions Policy 限制;文件焦點、瀏覽器設定與平台規則也會影響結果。各瀏覽器的剪貼簿權限名稱與行為不同,應查閱對應文件,不要將一次 Chromium 結果視為 Safari 或 Firefox 的保證。

實測回送 HTTP 可取得 Clipboard API,一般 HTTP 測試主機名稱不行。
保留的原始說明圖。
隔離 Chromium 的紀錄:迴路位址可存取 Clipboard API,測試用一般 HTTP 位址則不可;未測試讀寫剪貼簿
保存的隔離 Chromium 來源與 API 可用性檢查,沒有讀寫剪貼簿。這是測試結果畫面,不是原發問者的應用程式。開啟完整尺寸的證據圖片。

資料來源與延伸閱讀