複製按鈕在 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 的保證。
