Clipboard API 写入文本需要什么权限上下文

Clipboard API 写入文本，最稳妥的前提不是“先弹出一个权限框”，而是同时满足三个边界：页面处于安全上下文、调用发生在用户明确操作产生的瞬时激活期间、嵌入场景没有被 Permissions Policy 拦截。浏览器对 clipboard-write 权限的处理并不完全一致，所以不能只看一个权限状态就断定复制一定成功。

官方资料：https://developer.mozilla.org/en-US/docs/Web/API/Clipboard/writeText

规范参考：https://www.w3.org/TR/clipboard-apis/

先保护资产：剪贴板写入为什么需要安全上下文

剪贴板属于操作系统级的数据缓冲区。网页一旦能静默改写它，就可能把用户原本要粘贴的地址替换成另一条地址，或者把诱导执行的命令放进去。因此 navigator.clipboard.writeText() 只在安全上下文中可用，常见的生产入口是 HTTPS。

安全上下文只是入口条件，不等于浏览器已经同意本次写入。代码可以先做能力判断，但不要把“存在 navigator.clipboard”当成成功保证：

function canUseClipboardWrite() {
  // 安全上下文和 Clipboard API 都是写入文本的基础条件。
  return window.isSecureContext && Boolean(navigator.clipboard?.writeText);
}

function showCopyUnavailable() {
  // 给用户说明当前环境不满足条件，而不是静默吞掉复制动作。
  document.querySelector('#copy-status').textContent = '当前环境不支持安全复制';
}

攻击路径的关键：把 writeText 放在用户激活里

跨浏览器更稳妥的调用方式，是让用户点击“复制”按钮后，在这个事件处理函数中直接调用 writeText()。不要先等待一个不相关的网络请求，再把写入放到后续回调里；这会让调用时机脱离用户刚刚产生的激活。

const copyButton = document.querySelector('#copy-button');
const copyStatus = document.querySelector('#copy-status');

copyButton.addEventListener('click', async () => {
  // 在点击产生的用户激活期间直接发起写入，不先等待网络任务。
  const text = document.querySelector('#copy-source').textContent;

  if (!window.isSecureContext || !navigator.clipboard?.writeText) {
    // 能力缺失时给出明确提示，便于用户切换到 HTTPS 页面。
    copyStatus.textContent = '请在安全上下文中重试';
    return;
  }

  try {
    await navigator.clipboard.writeText(text);
    // 当前 Promise 成功只表示本次写入已被浏览器接受。
    copyStatus.textContent = '已复制';
  } catch (error) {
    // NotAllowedError 通常表示权限、激活或浏览器策略没有满足。
    if (error instanceof DOMException && error.name === 'NotAllowedError') {
      copyStatus.textContent = '浏览器拒绝了剪贴板写入';
      return;
    }
    // 其他异常也要保留给日志系统，不能假装复制成功。
    copyStatus.textContent = '复制失败，请稍后重试';
    console.error('clipboard write failed', error);
  }
});

这里的“用户激活”是调用时机约束，不是让用户在设置页手动打开某个统一开关。尤其在 Firefox 和 Safari 中，写入通常仍要求瞬时用户激活；把按钮点击作为统一入口，比依赖某个浏览器私有的持久授权更可靠。

权限不是一个跨浏览器通用的开关

Clipboard API 规范定义了 clipboard-write 权限，Chromium 系浏览器可能接受“已有写入权限”或“当前有瞬时用户激活”这两类条件。MDN 同时记录了实现差异：Firefox 和 Safari 不支持把 clipboard-read、clipboard-write 当作同样的 Permissions API 权限来使用，它们更依赖瞬时用户激活。

因此，应用层不应把 navigator.permissions.query({ name: 'clipboard-write' }) 的结果当成唯一门禁。它可以作为 Chromium 场景的诊断信息，但真正的写入仍要依赖用户操作和 writeText() 的 Promise 结果。

嵌入页面要检查 Permissions Policy

页面运行在 iframe 中时，还要确认宿主文档没有禁止剪贴板写入。MDN 对 Chromium 场景特别指出，iframe 访问剪贴板需要允许 clipboard-write 的 Permissions Policy。也就是说，即使子页面是 HTTPS、按钮也确实被点击，策略不允许时仍可能得到 NotAllowedError。

这段标记只是嵌入关系的说明。实际部署时还要结合响应头中的 Permissions-Policy 配置，并把授权范围限制在确实需要复制能力的来源，不要对所有未知来源开放。

把风险分级：复制成功也不等于数据安全

写入剪贴板的文本可能包含令牌、密码、内部地址或一次性代码。安全实现至少应做到三点：只在用户明确点击后写入；界面明确告诉用户复制了什么类型的数据；对敏感值设置短生命周期并提醒用户不要把剪贴板当作长期秘密存储。不要为了“自动复制”而在页面加载、定时器或隐藏事件中静默写入。

失败记录可以保留异常名称、页面环境类别和操作入口，但不要把待复制的原文写进普通日志。这样既能定位权限上下文问题，也不会把敏感内容扩散到日志系统。

上线前检查清单

• 生产页面是否使用 HTTPS 等安全上下文，而不是把 HTTP 当作正常复制环境？
• writeText() 是否直接位于点击、键盘操作等明确用户激活的处理路径中？
• 是否捕获并区分了 NotAllowedError，没有在 Promise 未完成时显示“已复制”？
• 如果页面位于 iframe，宿主是否允许 clipboard-write，且来源范围足够收敛？
• 是否把权限查询仅作为诊断，而不是当成所有浏览器都支持的统一开关？
• 复制内容是否可能包含敏感值，日志和提示是否避免泄露原文？

相关问题

为什么 HTTPS 页面调用 writeText 仍然失败？安全上下文只是前提，当前调用还可能缺少瞬时用户激活、被 iframe 的 Permissions Policy 拦截，或受到浏览器自身策略限制。

是否必须先申请 clipboard-write 权限？不应把它理解成所有浏览器都要先执行的统一步骤。以用户点击触发写入，并处理 Promise 结果，通常比预先依赖权限查询更稳妥。

能否在页面加载后自动把文本复制到剪贴板？不建议这样设计。它缺少清晰的用户意图，也更容易被浏览器以缺少用户激活或安全风险为理由拒绝。

记住这条最实用的判断顺序：先看安全上下文，再看是否紧邻用户激活，接着看 iframe 的权限策略，最后把浏览器差异和 NotAllowedError 当作正常分支处理。