Manifest V3 Chrome扩展使用tabCapture API录制标签页生成GIF报错如何解决

问题根因 #

• 你把tabCapture配置为可选权限，没有提前向用户申请授权，调用API时权限不足
• 调用tabCapture的上下文不符合要求：content script不支持调用该API，嵌入普通网页的扩展资源iframe继承网页上下文，不属于扩展可信前台上下文，后台service worker属于后台上下文，也不满足调用要求
• 未处理chrome.runtime.lastError导致抛出未检查异常
• activeTab权限需要用户主动触发扩展交互后才生效，非主动触发场景下无法获取当前tab操作权限

解决步骤 #

1. 调整上下文触发逻辑

不要将录制页面嵌入普通网页的iframe中，改为在扩展独立前台上下文调用，优先通过用户主动触发扩展交互的入口拉起录制页面：

// 写入background.js，监听扩展图标点击/快捷键触发事件
chrome.action.onClicked.addListener(async () => {
  // 打开独立的扩展录制窗口，属于扩展可信前台上下文
  await chrome.windows.create({
    url: chrome.runtime.getURL('gif.html'),
    type: 'popup',
    width: 400,
    height: 300
  })
})

2. 先申请权限再调用API

tabCapture为可选权限，必须在用户交互回调中主动申请授权，用户同意后才能调用录制接口：

// 替换gif.html中的核心录制代码
const getStream = async () => {
  // 先申请tabCapture权限
  const hasPermission = await chrome.permissions.request({
    permissions: ['tabCapture']
  })
  if (!hasPermission) {
    alert('需要录屏权限才能使用该功能')
    return
  }

  chrome.tabCapture.capture(
    {
      video: true,
      audio: true,
      videoConstraints: {
        mandatory: {
          minWidth: 16,
          minHeight: 9,
          maxWidth: 854,
          maxHeight: 480,
          maxFrameRate: 60,
        },
      },
    },
    (stream) => {
      // 捕获运行时错误，避免抛出未检查异常
      if (chrome.runtime.lastError) {
        console.error('录屏启动失败：', chrome.runtime.lastError)
        return
      }
      console.log('获取到媒体流：', stream)
      // 绑定流到video元素播放
      if (videoRef.current) {
        videoRef.current.srcObject = stream
        videoRef.current.play()
      }
    }
  );
};

3. 可选配置调整

如果需要默认请求录屏权限，可以把tabCapture从optional_permissions移动到permissions数组中，可选权限的用户接受度相对更高。

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