React浏览器扩展中navigator.clipboard粘贴功能网页正常扩展失效

• navigator.clipboard.readText() 是浏览器高权限API，调用必须同时满足三个条件：运行在安全上下文、由明确的用户手势（点击、按键等）直接触发、调用上下文持有剪贴板读取权限。普通网页环境下用户操作时默认满足以上条件，所以功能正常。
• 浏览器扩展的运行上下文和普通网页隔离：
  • 扩展的popup、options、sidepanel等自有页面，默认没有剪贴板读取权限，直接调用API会抛出权限异常；
  • 注入到网页的content script运行在独立的隔离世界，就算用户触发了交互，默认也无法调用剪贴板API，调用会直接被浏览器拦截；
  • background service worker运行在后台，没有前台聚焦的窗口，完全不满足剪贴板API的调用要求，任何场景下调用都会失败。
• 多数开发者未捕获API抛出的异常，只会表现为功能无响应，控制台也容易忽略权限类报错。

1. 先配置扩展权限 #

在扩展的manifest.json中声明剪贴板读取权限，以Manifest V3为例：

{
  "manifest_version": 3,
  "permissions": ["clipboardRead"],
  // 如果在content script中使用，需要配置对应宿主站点的host权限
  "host_permissions": ["https://*/*", "http://*/*"]
}

2. 根据运行场景选择对应实现 #

场景A：功能在扩展自有页面（popup/options/侧边栏）中使用 #

保证readText调用在用户交互的同步调用栈中，同时增加错误捕获即可，修正后的代码：

async function onPasteHandler(): Promise<void> {
  try {
    // 不要在readText前加无关的异步等待，避免脱离用户手势调用栈
    const text = await navigator.clipboard.readText();
    console.log("获取到剪贴板文本", text);
    setValue(text);
  } catch (err) {
    console.error("读取剪贴板失败，错误信息：", err);
  }
}

场景B：功能在content script中使用 #

优先使用兼容性更好、无额外权限依赖的原生paste事件方案，避免隔离世界的权限限制：

import { useEffect, useState } from 'react';

// React组件内使用示例
function YourPasteComponent() {
  const [value, setValue] = useState('');

  useEffect(() => {
    const pasteHandler = (e: ClipboardEvent) => {
      // 如果不需要拦截默认粘贴行为可以去掉preventDefault
      e.preventDefault();
      const pasteText = e.clipboardData?.getData('text/plain')?.trim() || '';
      if (pasteText) {
        console.log("通过paste事件获取文本：", pasteText);
        setValue(pasteText);
      }
    };

    // 绑定到对应的输入元素，或全局window
    const bindTarget = document.querySelector('#your-paste-input') || window;
    bindTarget.addEventListener('paste', pasteHandler);

    return () => bindTarget.removeEventListener('paste', pasteHandler);
  }, []);

  // 其余组件逻辑
}

如果是点击自定义按钮主动触发粘贴，可以在按钮点击回调中先让目标输入框聚焦，再调用document.execCommand('paste')获取内容，该接口在配置clipboardRead权限的content script中可正常使用。

注意事项 #

禁止在background service worker中调用任何剪贴板读取API，该上下文无前台窗口，所有剪贴板读取请求都会被浏览器直接拦截。

内容的提问来源于stack exchange，提问作者Abdullah Ibrâhim