在浏览器环境里，JavaScript 操作剪切板主要经历两个时代：早期的 document.execCommand 方式和现代的 Clipboard API。前者通过 execCommand('copy') 或 execCommand('paste') 借助选区完成读写，但缺乏统一权限控制，且在非安全上下文或失去焦点时容易失效。后者以 navigator.clipboard 为核心，提供 Promise 化的异步接口，并受 Permissions Policy 与用户手势约束，更适合处理敏感数据。
一、传统 execCommand 方式的原理与局限
execCommand 是 IE 时代延续下来的命令式接口。典型写剪切板流程是：创建一个临时 DOM 节点，选中其文本，再调用 document.execCommand('copy')，最后移除节点。这种方式依赖浏览器内部的编辑命令机制，本质上是在模拟用户 Ctrl+C 行为。
它的主要问题在于安全模型模糊。任何脚本只要能操作 DOM 选区，就能触发复制，用户往往无感知。同时，现代浏览器逐渐将 execCommand 标记为废弃，在 iframe 或后台标签页中调用会直接返回 false。下面的代码展示了一个常见的兼容写法：
function copyByExecCommand(text) {
var textarea = document.createElement('textarea');
textarea.value = text;
textarea.style.position = 'fixed';
textarea.style.opacity = '0';
document.body.appendChild(textarea);
textarea.select();
var ok = false;
try {
ok = document.execCommand('copy');
} catch (e) {
ok = false;
}
document.body.removeChild(textarea);
return ok;
}
上述代码在 HTTP 页面或用户未交互时可能失败，且无法读取剪切板内容。因此，新项目应优先使用 Clipboard API，仅在需要支持老旧浏览器时将其作为降级方案。
二、现代 Clipboard API 的安全读写
navigator.clipboard 提供了 writeText、readText、write 和 read 方法。浏览器要求页面处于安全上下文（HTTPS 或 localhost），且文档拥有焦点。读取操作还必须由用户手势（如 click）触发，否则会抛出 NotAllowedError。
写入文本是最常用的场景。下面示例在按钮点击后写剪切板，并做异常兜底：
document.getElementById('btn').addEventListener('click', async function () {
try {
await navigator.clipboard.writeText('敏感数据请勿外传');
console.log('写入成功');
} catch (err) {
console.warn('写入失败，原因：', err.message);
}
});
读取文本同样需要包裹在用户事件中。由于剪切板可能含有令牌或手机号，代码不应将其打印到公开日志，也不宜长期缓存。推荐做法是读取后立即使用，用完即弃。
button.addEventListener('click', async function () {
try {
const text = await navigator.clipboard.readText();
if (text.length > 20) {
console.log('内容过长，已做脱敏处理');
} else {
handleUserInput(text);
}
} catch (e) {
alert('无法读取剪切板，请检查浏览器权限');
}
});
三、处理非文本类型的剪切板数据
当我们需要复制图片时，应使用 clipboard.write 配合 ClipboardItem。ClipboardItem 接受 MIME 类型到 Blob 的映射，浏览器据此写入对应格式。下列代码将 canvas 图像写入剪切板：
async function copyImageFromCanvas(canvas) {
await new Promise(res => canvas.toBlob(res, 'image/png'));
canvas.toBlob(async function (blob) {
const item = new ClipboardItem({ 'image/png': blob });
try {
await navigator.clipboard.write([item]);
} catch (e) {
console.error('图片写入被拒绝');
}
});
}
读取图片则遍历 clipboard.read 返回的 ClipboardItem，通过 getType 获取 Blob 并生成对象 URL。注意此类操作在跨站 iframe 中通常被 Permissions Policy 禁用，需要在 HTTP 头中声明 clipboard-read 允许来源。
四、隐私与权限的最佳实践
为避免隐私泄露，首先应在 manifest 或元信息中声明所需权限，减少静默失败。其次，任何读取行为都应在用户明确动作后发生，不在页面加载时自动读剪切板。对于包含 credential 的内容，建议先本地校验格式，再决定是否上传。
另外，在混合内容页面（HTTPS 中嵌入 HTTP 资源）里，clipboard 对象可能不存在。此时可通过特性检测决定降级：
function safeCopy(text) {
if (navigator.clipboard && window.isSecureContext) {
return navigator.clipboard.writeText(text);
}
return Promise.resolve(copyByExecCommand(text));
}
最后，开发阶段不要将剪切板原文记入分析平台。若必须调试，可对前四位之后的字符做掩码，确保即使日志泄露也不会暴露完整敏感信息。
五、常见误区与排查清单
不少开发者误以为 clipboard 读写在 Service Worker 或 Web Worker 中可用，实际上 navigator.clipboard 仅存在于 Window 上下文。还有人用 <input> 标签的 select 方法配合 execCommand，却忘记先让元素可见，导致选区为空。
排查时建议确认：页面协议是否为 HTTPS、是否由用户点击触发、浏览器是否在焦点状态、iframe 是否获得 clipboard-write 权限。对照清单通常能解决绝大部分被拒问题。
Clipboard_APIdocument_execCommandnavigator_clipboard修改时间：2026-08-01 02:30:26