Chrome扩展Offscreen文档音频播放报错排查求助

1. 解决「Only a single offscreen document may be created」错误 #

Chrome扩展的Offscreen文档是单实例限制，必须先检查已有实例再决定是否创建。在Service Worker中添加检查逻辑：

// Service Worker 中创建/获取Offscreen的函数
async function createOrGetOffscreen() {
  const existingOffscreen = await chrome.offscreen.hasDocument();
  if (existingOffscreen) return;
  
  await chrome.offscreen.createDocument({
    url: 'offscreen.html',
    reasons: ['AUDIO_PLAYBACK'],
    justification: '播放用户上传的音频文件'
  });
}

调用时先执行await createOrGetOffscreen()，避免重复创建实例。

2. 解决「Could not establish connection. Receiving end does not exist」错误 #

这个错误核心是消息发送时机早于Offscreen的监听注册，或监听逻辑有误，按以下方式修正：

修正Offscreen的监听逻辑 #

确保offscreen.js在文档加载完成后立即注册监听，且支持异步响应：

// offscreen.js
document.addEventListener('DOMContentLoaded', () => {
  chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
    if (message.type === 'PLAY_AUDIO') {
      const audio = new Audio(message.audioUrl);
      audio.play().catch(err => console.error('播放失败:', err));
      sendResponse({status: 'playing'});
    }
    // 返回true以支持异步sendResponse
    return true;
  });
});

确保Service Worker等待Offscreen就绪后发消息 #

直接创建后立即发消息可能导致Offscreen未加载完成，可通过「就绪通知」处理：

// offscreen.js 加载完成后主动发就绪消息
document.addEventListener('DOMContentLoaded', () => {
  chrome.runtime.sendMessage({type: 'OFFSCREEN_READY'});
  // 上面的消息监听逻辑...
});

// Service Worker中缓存就绪状态
let isOffscreenReady = false;
chrome.runtime.onMessage.addListener((message) => {
  if (message.type === 'OFFSCREEN_READY') {
    isOffscreenReady = true;
  }
});

// 发送音频请求前确保就绪
async function sendPlayAudio(audioUrl) {
  await createOrGetOffscreen();
  if (!isOffscreenReady) {
    await new Promise(resolve => setTimeout(resolve, 100));
  }
  return chrome.runtime.sendMessage({
    type: 'PLAY_AUDIO',
    audioUrl: audioUrl
  });
}

也可改用长连接替代一次性消息，避免时机问题：

// Service Worker中建立长连接
async function connectToOffscreen() {
  await createOrGetOffscreen();
  const port = chrome.runtime.connect({name: 'audio-playback-port'});
  port.onMessage.addListener((msg) => {
    if (msg.status === 'connected') {
      port.postMessage({type: 'PLAY_AUDIO', audioUrl: 'xxx'});
    }
  });
  return port;
}

// offscreen.js中监听长连接
chrome.runtime.onConnect.addListener((port) => {
  if (port.name === 'audio-playback-port') {
    port.postMessage({status: 'connected'});
    port.onMessage.addListener((message) => {
      if (message.type === 'PLAY_AUDIO') {
        // 处理音频播放逻辑
      }
    });
  }
});

3. 额外检查点 #

• 确认manifest.json正确声明权限和路径：

{
  "manifest_version": 3,
  "permissions": ["offscreen"],
  "background": {
    "service_worker": "background.js"
  },
  "offscreen": {
    "default_path": "offscreen.html"
  }
}

• 避免页面重载时重复触发Offscreen创建逻辑，仅在需要播放音频时请求Service Worker处理。

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