前端剪贴板复制方案：clipboard-copy vs clipboard-polyfill vs copy-to-clipboard

在 Web 开发中，"复制到剪贴板"看似简单，实则暗藏玄机。浏览器的安全策略、API 的演进以及对富文本的支持差异，让开发者面临多种选择。clipboard-copy、clipboard-polyfill 和 copy-to-clipboard 代表了三种不同的技术路线：拥抱现代标准、填补功能空白、以及兼容旧时代。

本文将从底层机制、功能边界和实战场景三个维度，深入剖析这三者的区别，助你做出正确的架构决策。

⚙️ 核心机制：现代 API vs 多面手 vs 传统回退

这三款库的根本区别在于它们调用浏览器能力的方式不同，这直接决定了它们的能力上限和兼容性下限。

clipboard-copy 是"现代原生派"。它完全依赖现代的 navigator.clipboard API。如果浏览器不支持该 API，它会直接抛出错误，不做任何尝试。这意味着它极其轻量，但只能在较新的浏览器和 HTTPS 环境下工作。

// clipboard-copy 用法
import copy from 'clipboard-copy';

// 仅支持纯文本，依赖 navigator.clipboard.writeText
copy('Hello World')
  .then(() => console.log('复制成功'))
  .catch(err => console.error('复制失败，可能是不支持现代 API', err));

clipboard-polyfill 是"功能增强派"。它同样首选 navigator.clipboard，但它的核心价值在于当原生 API 功能不足（例如不支持写入 HTML）或部分缺失时，提供复杂的降级策略或填充实现。它允许你构建包含多种格式（文本 + HTML + 图片）的剪贴板项。

// clipboard-polyfill 用法
import * as clipboard from 'clipboard-polyfill';

// 支持富文本和多种格式
const item = new clipboard.ClipboardItem({
  'text/html': new Blob(['<b>Bold Text</b>'], { type: 'text/html' }),
  'text/plain': new Blob(['Bold Text'], { type: 'text/plain' })
});

clipboard.write([item])
  .then(() => console.log('富文本复制成功'))
  .catch(err => console.error('失败', err));

copy-to-clipboard 是"经典兼容派"。它主要依赖古老的 document.execCommand('copy') 方法。为了执行这个命令，它通常需要在 DOM 中临时创建一个 <textarea> 或 <input> 元素，选中文本，执行命令，然后移除元素。这种方法兼容性极好，但无法复制非文本内容。

// copy-to-clipboard 用法
import copy from 'copy-to-clipboard';

// 内部使用 execCommand，自动处理 DOM 临时元素
const success = copy('Hello World');
if (success) {
  console.log('复制成功（通过 execCommand）');
} else {
  console.log('复制失败（可能权限被拒或不支持）');
}

📝 功能边界：纯文本 vs 富文本 vs 极致兼容

选择哪个库，很大程度上取决于你需要复制什么内容。

1. 纯文本复制

三者都能完成，但体验不同。

• clipboard-copy：代码最少，Promise 风格清晰。
• copy-to-clipboard：同步返回布尔值，无需 async/await，适合简单脚本。
• clipboard-polyfill：杀鸡用牛刀，虽然能做，但不推荐仅为了纯文本引入它。

2. 富文本（HTML）复制

这是分水岭。

• clipboard-copy：不支持。尝试传入 HTML 字符串会被当作纯文本处理，标签会被转义。
• copy-to-clipboard：不支持。execCommand 机制本身对富文本支持极差且不可控。
• clipboard-polyfill：完美支持。你可以明确指定 text/html 类型，让用户粘贴到 Word 或 Gmail 时保留格式。

// 场景：复制一段带样式的代码
const htmlContent = '<code style="color:red">console.log("Hi")</code>';
const textContent = 'console.log("Hi")';

// ❌ clipboard-copy: 粘贴出来是 <code>... 纯文本
// ❌ copy-to-clipboard: 粘贴出来是 <code>... 纯文本

// ✅ clipboard-polyfill: 粘贴到支持富文本的编辑器会显示红色代码
const item = new clipboard.ClipboardItem({
  'text/html': new Blob([htmlContent], { type: 'text/html' }),
  'text/plain': new Blob([textContent], { type: 'text/plain' })
});
clipboard.write([item]);

3. 图片复制

• clipboard-copy 和 copy-to-clipboard 均无法直接复制图片。
• clipboard-polyfill 支持通过 ClipboardItem 写入图片数据（如 PNG），但这通常需要浏览器较新版本的支持配合。

🌍 兼容性与运行环境

环境限制往往是架构选型的决定性因素。

关键点解析： 现代 Clipboard API (navigator.clipboard) 被浏览器严格限制在安全上下文（即 HTTPS 或 localhost）中。如果你的应用部署在 HTTP 环境，clipboard-copy 和 clipboard-polyfill 的核心功能将直接失效。此时，copy-to-clipboard 是唯一的选择，因为它基于旧的 execCommand，不受 HTTPS 强制限制。

🛠️ 实战场景选型指南

场景 A：现代后台管理系统，仅需复制 ID 或链接

推荐：clipboard-copy 理由：环境可控（通常是 HTTPS），浏览器较新，只需复制纯文本。代码最干净，无副作用。

// 在 React 组件中
const handleCopyId = async (id) => {
  try {
    await copy(id);
    message.success('ID 已复制');
  } catch (e) {
    // 处理不支持的情况，提示用户升级浏览器
  }
};

场景 B：在线文档编辑器，需"复制为富文本"

推荐：clipboard-polyfill 理由：用户期望从网页复制内容到 Word 或邮件时保留加粗、列表和链接。只有此库能构造包含 text/html 的 ClipboardItem。

const copyRichText = async (html, plain) => {
  const item = new clipboard.ClipboardItem({
    'text/html': new Blob([html], { type: 'text/html' }),
    'text/plain': new Blob([plain], { type: 'text/plain' })
  });
  await clipboard.write([item]);
};

场景 C：老旧的企业内网系统，运行在 HTTP 下

推荐：copy-to-clipboard 理由：内网可能未配置 HTTPS，且用户可能使用旧版浏览器。execCommand 是唯一可行的路径。虽然需要用户交互（点击），但这是旧技术栈下的最优解。

const copyLegacy = (text) => {
  if (copy(text)) {
    alert('复制成功');
  } else {
    alert('复制失败，请手动复制');
  }
};

⚠️ 常见陷阱与注意事项

1. 异步与用户交互：无论是现代 API 还是 execCommand，浏览器都要求复制操作必须由用户手势（如 click 事件）触发。在 setTimeout 或 fetch 回调中直接调用通常会失败。所有三个库都遵循这一规则，开发者需确保调用时机正确。

2. 移动端 Safari 的特殊性：在 iOS 上，navigator.clipboard 的支持直到 iOS 13.4 才完善。在此之前，即使使用了 clipboard-polyfill，也可能无法在非用户直接触发的事件中工作。对于极度重视移动端兼容的项目，可能需要组合使用：优先尝试现代 API，失败则降级到 copy-to-clipboard（如果环境允许）。

3. 权限问题：现代 API 可能会弹出权限询问（虽然 writeText 通常不需要，但读取需要）。而 execCommand 在某些浏览器配置下可能被禁用。务必包裹 try...catch 或检查返回值。

💡 总结与建议

这三款库没有绝对的"最好"，只有"最适合"：

• 追求代码简洁且环境现代？选 clipboard-copy。
• 需要富文本、图片或精细控制？选 clipboard-polyfill。
• 必须兼容HTTP、IE 或旧设备？选 copy-to-clipboard。

在现代前端架构中，趋势是逐步淘汰 execCommand。如果你的项目没有沉重的历史包袱，建议优先基于 navigator.clipboard 构建（使用 clipboard-copy 或原生 API），并将 copy-to-clipboard 作为可选的降级依赖，仅在检测到环境不支持时动态加载。这样既能享受现代 API 的强大功能，又能兼顾极端情况下的可用性。