Chrome扩展Manifest V3：Offscreen调用麦克风报“Not supported”求助

问题根源 #

Offscreen页面调用getUserMedia获取麦克风失败，核心是两个原因：

1. 未在Manifest中声明必要的音频捕获权限
2. API调用不在用户交互触发的上下文中（Chrome禁止无用户交互的后台上下文调用媒体捕获API）

必要配置 #

首先在manifest.json中添加以下权限和Offscreen页面配置：

{
  "permissions": ["offscreen", "audioCapture"],
  "background": {
    "service_worker": "background.js"
  },
  "offscreen": {
    "matches": ["<all_urls>"],
    "default_path": "offscreen.html"
  }
}

• audioCapture：允许扩展访问麦克风
• offscreen：启用Offscreen页面功能
• offscreen.matches：指定Offscreen页面能匹配的URL范围，<all_urls>适配大多数场景

实现步骤 #

1. 基于用户交互触发API调用 #

Offscreen页面中，必须在用户主动操作（比如点击按钮）的回调里调用getUserMedia，示例如下：
offscreen.html：

<button id="activateMic">启用麦克风</button>
<script src="offscreen.js"></script>

offscreen.js：

document.getElementById('activateMic').addEventListener('click', async () => {
  try {
    const micStream = await navigator.mediaDevices.getUserMedia({ video: false, audio: true });
    // 将流存储在全局变量，避免页面意外回收导致丢失
    window.persistedMicStream = micStream;
  } catch (err) {
    console.error('麦克风捕获失败:', err);
  }
});

2. 通过扩展消息触发（需用户交互前置） #

如果需要从Service Worker或其他扩展页面触发，必须确保消息是由用户操作（比如点击扩展图标）发起的：

• Service Worker中发送触发消息：

chrome.action.onClicked.addListener(async () => {
  // 创建Offscreen文档，指定音频捕获的原因
  await chrome.offscreen.createDocument({
    url: 'offscreen.html',
    reasons: ['AUDIO_CAPTURE'],
    justification: '需要录制麦克风音频'
  });
  // 发送触发消息
  chrome.runtime.sendMessage({ type: 'INITIATE_MIC_CAPTURE' });
});

• Offscreen页面监听消息并执行捕获：

chrome.runtime.onMessage.addListener(async (message) => {
  if (message.type === 'INITIATE_MIC_CAPTURE') {
    try {
      const micStream = await navigator.mediaDevices.getUserMedia({ video: false, audio: true });
      window.persistedMicStream = micStream;
    } catch (err) {
      console.error('麦克风捕获失败:', err);
    }
  }
});

重要提示 #

• Offscreen页面只要不主动调用chrome.offscreen.closeDocument()关闭，获取到的麦克风流会持续保留，不会像普通标签页关闭那样丢失。
• 创建Offscreen文档时，reasons必须包含'AUDIO_CAPTURE'，这是Manifest V3中使用音频捕获的强制要求。

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