最可靠方式是 navigator.clipboard.writeText()，但需满足安全上下文（HTTPS/localhost）和用户手势触发；否则报错如“undefined”“Permission denied”或“Document not focused”。
现代浏览器中，JavaScript 实现复制到剪贴板最可靠的方式是使用 navigator.clipboard.writeText()，它取代了已废弃的 document.execCommand('copy')。但直接调用该 API 有明确的限制条件，不是任何时候都能成功。
为什么 navigator.clipboard.writeText() 会报错？
这个 API 只能在安全上下文（HTTPS 或 localhost）中调用，且必须由用户手势（如 click、keydown）触发 —— 不能在定时器、异步回调或页面加载完成时自动执行。
- 常见错误信息：
"navigator.clipboard is undefined"（旧版 Safari 或禁用权限时） -
"Permission denied"（未获用户授权，或非用户触发） -
"Failed to execute 'writeText' on 'Clipboard': Document is not focused"（页面失焦，尤其在 Electron 或某些 iframe 场景）
如何安全调用 navigator.clipboard.writeText()？
必须确保：① 在事件处理器内；② 检查 API 是否可用；③ 捕获并处理拒绝情况。
button.addEventListener('click', async () => {
if (!navigator.clipboard) {
console.error('Clipboard API not supported');
return;
}
try {
await navigator.clipboard.writeText('Hello, world!');
console.log('Copied!');
} catch (err) {
console.error('Failed to copy: ', err);
}
});
- 不要省略
async/await或.catch()，否则静默失败 - 避免在
setTimeout或Promise.resolve().then()中调用 —— 即使紧接在 click 后也会失去“用户手势”上下文 - Safari 16.4+ 才支持
writeText()，更早版本需降级方案
需要兼容老浏览器怎么办？
当 navigator.clipboard 不可用时，可回退到临时 <textarea></textarea> + execCommand，但仅限于用户触发且页面有焦点的场景（且 execCommand 已被标记为废弃，Chrome 95+ 在非安全上下文中完全禁用）。
你是 TypeScript 项目架构专家，专注于脚手架搭建生产就绪的 Node.js 和前端应用。生成包含现代工具链（pnpm、Vite、Next.js）、类型
立即学习“Java免费学习笔记（深入）”；
- 临时 textarea 必须
position: fixed; left: -9999px;，避免视觉跳动 - 必须先
select()再execCommand('copy')，否则无效 - 务必在操作后立即
remove()临时元素，防止内存泄漏或重复绑定 - 此方式无法复制富文本或图片，仅适用于纯文本
复制富文本或 HTML 内容怎么处理？
navigator.clipboard.writeText() 只支持字符串；若要复制带样式的 HTML（如从 contenteditable 区域），需用 navigator.clipboard.write() 配合 ClipboardItem，但目前仅 Chromium 和 Firefox 支持，Safari 完全不支持。
- 示例写入 HTML：
new ClipboardItem({ 'text/html': new Blob(['<b>Bold</b>'], {type: 'text/html'}) }) - 注意 MIME 类型必须精确匹配，
'text/plain'和'text/html'是两个独立粘贴项 - 移动端 WebView（如微信内置浏览器）普遍不支持
write()，务必降级到纯文本
真正容易被忽略的是：即使 API 调用成功，也无法保证用户实际粘贴出你期望的内容 —— 粘贴行为最终由目标应用决定，比如某些编辑器会过滤 HTML 标签，或纯文本编辑器只取 text/plain 版本。所以，优先用 writeText()，别为了“看起来高级”强行上 write()。
