Chrome扩展调用navigator.clipboard.readText返回pending状态问题求助

1. 权限逻辑差异：Chrome扩展的权限为预声明机制，和普通网页运行时申请权限的逻辑不同。你没有在扩展的manifest.json中声明clipboardRead权限时，调用navigator.clipboard.readText()不会触发用户权限申请弹窗，属于未授权调用。
2. 调用触发条件不满足：Clipboard API的读取操作要求必须在用户主动交互事件（如click、keydown等）的同步回调中执行，非交互场景下调用会被Chrome拦截。
3. 无错误抛出的pending状态：是Chrome扩展环境的Clipboard API实现特性，当调用不满足上述两个要求时，不会抛出错误，而是直接让返回的Promise永久处于pending状态，无任何控制台输出。

第一步：配置manifest.json声明权限 #

根据你使用的扩展版本选择对应配置：

Manifest V3（当前主流版本） #

{
  "manifest_version": 3,
  "name": "你的扩展名称",
  "version": "1.0.0",
  "permissions": ["clipboardRead"]
  // 其余配置保留即可
}

Manifest V2（旧版本） #

{
  "manifest_version": 2,
  "name": "你的扩展名称",
  "version": "1.0.0",
  "permissions": ["clipboardRead"]
  // 其余配置保留即可
}

第二步：在用户交互事件的同步回调中调用 #

必须将navigator.clipboard.readText()放在用户主动触发的事件回调里执行，示例如下：

// 监听按钮点击事件，用户点击时触发读取
document.querySelector('#pasteButton').addEventListener('click', async () => {
  try {
    const clipboardString = await navigator.clipboard.readText();
    console.log('Clipboard Contains: ', clipboardString);
  } catch (err) {
    console.log('Clipboard Error: ', err);
  }
});

特殊场景：非用户交互时读取剪贴板 #

如果需要在后台service worker、定时任务等非用户交互场景读取剪贴板，需要配合Chrome扩展的offscreen（离屏文档）能力实现：

1. 先在Manifest V3的权限中新增offscreen权限：

"permissions": ["clipboardRead", "offscreen"]

2. 新建offscreen.html文件，放在扩展根目录：

<!DOCTYPE html>
<script>
// 监听后台消息，执行剪贴板读取
chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
  if (msg.type === 'readClipboard') {
    navigator.clipboard.readText().then(text => sendResponse(text));
    // 异步返回结果需要返回true保持端口开放
    return true;
  }
});
</script>

3. 在后台service worker中调用读取逻辑：

async function readClipboardFromOffscreen() {
  // 创建离屏文档
  await chrome.offscreen.createDocument({
    url: 'offscreen.html',
    reasons: [chrome.offscreen.Reason.CLIPBOARD],
    justification: '读取剪贴板内容完成扩展功能'
  });
  // 发送消息获取剪贴板内容
  const clipboardText = await chrome.runtime.sendMessage({type: 'readClipboard'});
  // 关闭离屏文档释放资源
  await chrome.offscreen.closeDocument();
  return clipboardText;
}

• 修改manifest.json后需要重新加载扩展，配置才会生效
• 可以访问chrome://extensions/找到对应扩展，进入详情页确认剪贴板权限已被正常授予
• 隐身模式下扩展默认没有剪贴板访问权限，需要在扩展详情页手动开启隐身模式权限

内容的提问来源于stack exchange，提问作者jimmythecoder